Inyo

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:

TypeBehaviorExample (fee = $4, amount = $100)
NETFee is added on top of the amount. The full amount is converted.Sender pays $104. $100 is converted to destination currency.
GROSSFee 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

FieldTypeRequiredDescription
fromCurrencystringYesSource currency (ISO 4217), e.g., USD
toCurrencystringYesDestination currency (ISO 4217), e.g., BRL
toCountrystringNoDestination country (ISO 3166-1 alpha-2) β€” disambiguates when a currency is used in multiple corridors
amountnumberYesAmount to convert (must be > 0)
amountTypestringNoGROSS or NET (see above). Defaults to NET.
spreadobjectNoOverride the configured FX spread for this quote (see Spread Adjustments)
spread.ratenumberβ€”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.typestringβ€”PERCENTAGE (default) or FIXED
spreadRatenumberNoLegacy shorthand for a PERCENTAGE spread override, 0–1. Prefer the spread object; ignored if spread.rate is sent
feeobjectNoOverride the default fee (if allowed by your contract)
fee.amountnumberβ€”Fee amount
fee.currencystringβ€”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

FieldDescription
idUnique quote identifier. Save this β€” it's required for the transaction.
fromAsset / toAssetSource and destination currencies
effectiveRateThe FX rate applied for this conversion (includes your spread)
sourceAmountThe amount converted, in the source currency
destinationAmountThe amount the recipient will receive
totalCostTotal the sender pays, in the source currency (amount + fee for NET quotes)
feeThe transaction fee applied to this quote
amountTypeNET or GROSS β€” how the fee was applied
productQuote product β€” REMITTANCE
expireAtISO 8601 timestamp when the quote becomes invalid
createdAtISO 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:

TypeFormulaMeaning
PERCENTAGEeffectiveRate = baseRate Γ— (1 βˆ’ rate)rate is a fraction 0–1. 0.02 shaves 2% off the mid-market rate. The default type.
FIXEDeffectiveRate = baseRate βˆ’ raterate 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:

  1. The spread object (spread.rate + spread.type), if present.
  2. Otherwise spreadRate β€” a legacy shorthand that always means a PERCENTAGE override.
  3. Otherwise the corridor's configured spread.

spreadRate and the spread object are mutually exclusive in practice β€” if you send spread.rate, spreadRate is ignored. Use the spread object for new integrations; it's the only way to request a FIXED spread.

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

FieldValue
Source CurrencyUSD
Destination CurrencyBRL
Source Amount1,000.00 USD
Effective Rate5.39023000
Destination Amount5,390.23 BRL
Fee4.99 USD
Total Cost1,004.99 USD
ProductREMITTANCE
Quote Validity30 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 expireAt before 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 a 400 or 422 error.
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

OperationMethodEndpoint
Request quotePOST/organizations/{tenant}/payout/quotes
Get quote by IDGET/organizations/{tenant}/payout/quotes/{quoteId}