Quotes (FX)
The FX Quote API allows you to request and lock in foreign exchange rates for a specific currency corridor and amount. The returned quoteId guarantees the rate for a fixed window, protecting both you and your customer from FX fluctuations during the transaction flow.
How Pricing Works
Two components determine the cost to the end user:
- FX Spread β Your margin on the exchange rate, configured per corridor by Inyo during onboarding. Depending on your contract, you can also override the spread per quote β as a percentage or a fixed amount. See Spread Adjustments.
- Transaction Fee β A per-transaction fee, also configured during onboarding. Depending on your contract, you may be able to override fees at the quote level (e.g., for promotional "zero fee" offers).
Both the configured spread and fee can be overridden on an individual quote request. When you don't send an override, the corridor's configured values apply.
Amount Types
When requesting a quote, the amountType field controls how fees are applied:
| Type | Behavior | Example (fee = $4, amount = $100) |
|---|---|---|
NET | Fee is added on top of the amount. The full amount is converted. | Sender pays $104. $100 is converted to destination currency. |
GROSS | Fee is deducted from the amount. Only the remainder is converted. | Sender pays $100. $96 is converted to destination currency. |
Requesting a Quote
Endpoint: POST /organizations/{tenant}/payout/quotes
Authentication: Agent-level (x-api-key + x-agent-id + x-agent-api-key)
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
fromCurrency | string | Yes | Source currency (ISO 4217), e.g., USD |
toCurrency | string | Yes | Destination currency (ISO 4217), e.g., BRL |
toCountry | string | No | Destination country (ISO 3166-1 alpha-2) β disambiguates when a currency is used in multiple corridors |
amount | number | Yes | Amount to convert (must be > 0) |
amountType | string | No | GROSS or NET (see above). Defaults to NET. |
spread | object | No | Override the configured FX spread for this quote (see Spread Adjustments) |
spread.rate | number | β | Spread amount, 0β1. For PERCENTAGE it's a fraction (e.g. 0.02 = 2%); for FIXED it's an absolute amount subtracted from the rate |
spread.type | string | β | PERCENTAGE (default) or FIXED |
spreadRate | number | No | Legacy shorthand for a PERCENTAGE spread override, 0β1. Prefer the spread object; ignored if spread.rate is sent |
fee | object | No | Override the default fee (if allowed by your contract) |
fee.amount | number | β | Fee amount |
fee.currency | string | β | Fee currency (typically matches fromCurrency) |
Sample Request
curl --request POST \
--url https://{FQDN}/organizations/$TENANT/payout/quotes \
--header 'Content-Type: application/json' \
--header "x-api-key: $API_KEY" \
--header "x-agent-id: $AGENT_ID" \
--header "x-agent-api-key: $AGENT_KEY" \
--data '{
"fromCurrency": "USD",
"toCurrency": "BRL",
"amount": 1000,
"fee": {
"amount": 4.99,
"currency": "USD"
},
"amountType": "NET"
}'
Sample Response
{
"quotes": [
{
"id": "f28be3f9-ad4d-4a6c-a85d-ae5515a4a158",
"agentId": "8500786a-68e9-45fd-b1d8-c590f1e06450",
"fromAsset": "USD",
"toAsset": "BRL",
"effectiveRate": 5.39023,
"totalCost": {
"amount": 1004.99,
"currency": "USD"
},
"fee": {
"amount": 4.99,
"currency": "USD"
},
"amountType": "NET",
"product": "REMITTANCE",
"expireAt": "2025-09-15T12:07:01Z",
"createdAt": "2025-09-15T11:37:01Z",
"sourceAmount": {
"amount": 1000.00,
"currency": "USD"
},
"destinationAmount": {
"amount": 5390.23,
"currency": "BRL"
}
}
]
}
Response Fields
| Field | Description |
|---|---|
id | Unique quote identifier. Save this β it's required for the transaction. |
fromAsset / toAsset | Source and destination currencies |
effectiveRate | The FX rate applied for this conversion (includes your spread) |
sourceAmount | The amount converted, in the source currency |
destinationAmount | The amount the recipient will receive |
totalCost | Total the sender pays, in the source currency (amount + fee for NET quotes) |
fee | The transaction fee applied to this quote |
amountType | NET or GROSS β how the fee was applied |
product | Quote product β REMITTANCE |
expireAt | ISO 8601 timestamp when the quote becomes invalid |
createdAt | ISO 8601 timestamp when the quote was generated |
Spread Adjustments
Your corridor has a configured FX spread, but if your contract permits it you can override that spread on an individual quote β useful for promotional rates, partner-specific pricing, or negotiated one-off deals. The override only affects the quote you send it on; it doesn't change your corridor configuration.
There are two spread types:
| Type | Formula | Meaning |
|---|---|---|
PERCENTAGE | effectiveRate = baseRate Γ (1 β rate) | rate is a fraction 0β1. 0.02 shaves 2% off the mid-market rate. The default type. |
FIXED | effectiveRate = baseRate β rate | rate is an absolute amount subtracted directly from the rate (floored at 0). |
Send the override as a spread object:
# Percentage spread β 2.5% margin on this quote
curl --request POST \
--url https://{FQDN}/organizations/$TENANT/payout/quotes \
--header 'Content-Type: application/json' \
--header "x-api-key: $API_KEY" \
--header "x-agent-id: $AGENT_ID" \
--header "x-agent-api-key: $AGENT_KEY" \
--data '{
"fromCurrency": "USD",
"toCurrency": "BRL",
"amount": 1000,
"spread": { "rate": 0.025, "type": "PERCENTAGE" }
}'
# Fixed spread β subtract 0.08 from the rate on this quote
curl --request POST \
--url https://{FQDN}/organizations/$TENANT/payout/quotes \
--header 'Content-Type: application/json' \
--header "x-api-key: $API_KEY" \
--header "x-agent-id: $AGENT_ID" \
--header "x-agent-api-key: $AGENT_KEY" \
--data '{
"fromCurrency": "USD",
"toCurrency": "BRL",
"amount": 1000,
"spread": { "rate": 0.08, "type": "FIXED" }
}'
Precedence β the API resolves the spread in this order:
- The
spreadobject (spread.rate+spread.type), if present. - Otherwise
spreadRateβ a legacy shorthand that always means aPERCENTAGEoverride. - Otherwise the corridor's configured spread.
spreadRateand thespreadobject are mutually exclusive in practice β if you sendspread.rate,spreadRateis ignored. Use thespreadobject for new integrations; it's the only way to request aFIXEDspread.
Overriding the Fee
The transaction fee is a separate, independent override β send a fee object with an amount (and optional currency). It applies on top of whatever spread is in effect, and a fee.amount of 0 is how you issue a zero-fee promotional quote.
Example Conversion Walkthrough
Scenario: Convert 1,000 USD β BRL
| Field | Value |
|---|---|
| Source Currency | USD |
| Destination Currency | BRL |
| Source Amount | 1,000.00 USD |
| Effective Rate | 5.39023000 |
| Destination Amount | 5,390.23 BRL |
| Fee | 4.99 USD |
| Total Cost | 1,004.99 USD |
| Product | REMITTANCE |
| Quote Validity | 30 minutes (default) |
Retrieving a Quote
Endpoint: GET /organizations/{tenant}/payout/quotes/{quoteId}
Authentication: Agent-level
curl --request GET \
--url https://{FQDN}/organizations/$TENANT/payout/quotes/$QUOTE_ID \
--header "x-api-key: $API_KEY" \
--header "x-agent-id: $AGENT_ID" \
--header "x-agent-api-key: $AGENT_KEY"
Use this to check if a quote is still valid before submitting a transaction.
Handling Quote Expiration
Quotes are valid for 30 minutes by default. The window is configurable per tenant (up to 24 hours) β check expireAt rather than assuming a duration. Follow these guidelines:
- Always check
expireAtbefore using a quote in a transaction. - Refresh proactively β request a new quote when ~90% of the validity period has elapsed.
- Never cache quotes β unlike destinations and bank lists, quotes are time-sensitive and must be fetched fresh.
- Expired quotes will be rejected β if you submit a transaction with an expired
quoteId, the API returns a400or422error.
Recommended UX Pattern
1. User selects amount and destination β Request quote 2. Display rate, fees, and receive amount 3. Start a countdown timer based on expireAt 4. If timer reaches ~80%, show "Rate expiring" warning 5. If expired, auto-refresh and update the display 6. On "Confirm", immediately submit the transaction with the quoteId
All Endpoints
| Operation | Method | Endpoint |
|---|---|---|
| Request quote | POST | /organizations/{tenant}/payout/quotes |
| Get quote by ID | GET | /organizations/{tenant}/payout/quotes/{quoteId} |
