FX Quotes - Nuvion

An FX quote locks in an exchange rate for converting one currency into another. Request a quote, then pass its id as fx_quote_id on a transfer to apply the locked rate. A quote is only valid for a limited window; use it before it expires or request a new one.

The FX Quote object

string

Unique identifier for the FX quote.

string

Source currency code, ISO 4217, uppercase.

string

Destination currency code, ISO 4217, uppercase.

number

The amount converted, in the smallest unit of the source currency.

number

The converted amount, in the smallest unit of the destination currency, after rate is applied.

number

The exchange rate applied to the conversion.

object

Validity and usage details for this quote.

Show quote fields

string

The current status of the quote. One of active, used, or expired.

number

Unix timestamp in milliseconds when the quote expires.

number

Remaining validity, in seconds. Counts down from the value at creation and reaches 0 once the quote is used or expires.

number | null

Unix timestamp in milliseconds when the quote was applied to a transfer. null while unused.

string | null

The ID of the transfer that consumed this quote. null while unused.

number

Unix timestamp in milliseconds when the quote was created.

number

Unix timestamp in milliseconds when the quote was last updated.

Example FX quote object

{
  "status": "success",
  "message": "FX quote created successfully",
  "data": {
    "id": "01HXYZ4680ABCDEFGHJKMNPQRS",
    "from": "USD",
    "to": "GHS",
    "amount_from": 5000,
    "amount_to": 50180,
    "rate": 10.036105,
    "quote": {
      "status": "active",
      "expires_at": 1787286987311,
      "valid_for": 179,
      "used_at": null,
      "used_in_payment_id": null
    },
    "created": 1787286808311,
    "updated": 1787286808311
  }
}

valid_for reflects how long the specific quote you requested remains valid. It varies per quote and per currency pair; don’t treat it as a fixed constant.

Create an FX quote

POST /fx-quotes Requests a quote to convert an amount from one currency into another, locking in a rate for a limited window.

Request parameters

string

required

The currency to convert from. ISO 4217 format, e.g. USD.

string

required

The currency to convert to. ISO 4217 format, e.g. GHS.

number

The amount to convert, in the smallest unit of from_currency. Minimum 100. Conditionally required: pass either amount_from or amount_to, not both.

number

The amount to receive, in the smallest unit of to_currency. Conditionally required: pass either amount_from or amount_to, not both.

string

The ID of the account you intend to debit on the resulting transfer. Used to look up any corridor-specific margin for the account; omit for an indicative quote not tied to a specific account.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl -X POST https://api.nuvion.dev/fx-quotes \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "GHS",
    "amount_from": 5000,
    "account_id": "01HXYZ0059ABCDEFGHJKMNPQRS"
  }'

Response

Returns the created FX Quote object with quote.status: "active".

{
  "status": "success",
  "message": "FX quote created successfully",
  "data": {
    "id": "01HXYZ4680ABCDEFGHJKMNPQRS",
    "from": "USD",
    "to": "GHS",
    "amount_from": 5000,
    "amount_to": 50180,
    "rate": 10.036105,
    "quote": {
      "status": "active",
      "expires_at": 1787286987311,
      "valid_for": 179,
      "used_at": null,
      "used_in_payment_id": null
    },
    "created": 1787286808311,
    "updated": 1787286808311
  }
}

Errors

Code	Description
`422`	`from_currency`/`to_currency` is not a supported conversion pair.
`503`	The exchange rate provider is temporarily unavailable. Retry after a short delay.

Get an FX quote

GET /fx-quotes/{quote_id} Retrieves a single FX quote, including its current status and remaining validity.

Path parameters

string

required

The FX quote ID.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl "https://api.nuvion.dev/fx-quotes/01HXYZ4680ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Returns the FX Quote object. Once a quote is applied to a transfer, quote.status becomes used and quote.used_at/quote.used_in_payment_id are populated.

{
  "status": "success",
  "message": "FX quote retrieved successfully",
  "data": {
    "id": "01HXYZ4680ABCDEFGHJKMNPQRS",
    "from": "USD",
    "to": "GHS",
    "amount_from": 5000,
    "amount_to": 50180,
    "rate": 10.036105,
    "quote": {
      "status": "used",
      "expires_at": 1787286987311,
      "valid_for": 0,
      "used_at": 1787286850000,
      "used_in_payment_id": "01HXYZ0060ABCDEFGHJKMNPQRS"
    },
    "created": 1787286808311,
    "updated": 1787286850000
  }
}

Errors

Code	Description
`404`	No FX quote found for the given `quote_id`.

​The FX Quote object

​Create an FX quote

​Request parameters

​Request

​Response

​Errors

​Get an FX quote

​Path parameters

​Query parameters

​Request

​Response

​Errors

The FX Quote object

Create an FX quote

Request parameters

Request

Response

Errors

Get an FX quote

Path parameters

Query parameters

Request

Response

Errors