> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# FX Quotes

> Lock in an exchange rate between two currencies before applying it to a transfer.

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

<ResponseField name="id" type="string">
  Unique identifier for the FX quote.
</ResponseField>

<ResponseField name="from" type="string">
  Source currency code, ISO 4217, uppercase.
</ResponseField>

<ResponseField name="to" type="string">
  Destination currency code, ISO 4217, uppercase.
</ResponseField>

<ResponseField name="amount_from" type="number">
  The amount converted, in the smallest unit of the source currency.
</ResponseField>

<ResponseField name="amount_to" type="number">
  The converted amount, in the smallest unit of the destination currency, after `rate` is applied.
</ResponseField>

<ResponseField name="rate" type="number">
  The exchange rate applied to the conversion.
</ResponseField>

<ResponseField name="quote" type="object">
  Validity and usage details for this quote.

  <Expandable title="quote fields">
    <ResponseField name="status" type="string">
      The current status of the quote. One of `active`, `used`, or `expired`.
    </ResponseField>

    <ResponseField name="expires_at" type="number">
      Unix timestamp in milliseconds when the quote expires.
    </ResponseField>

    <ResponseField name="valid_for" type="number">
      Remaining validity, in seconds. Counts down from the value at creation and reaches `0` once the quote is used or expires.
    </ResponseField>

    <ResponseField name="used_at" type="number | null">
      Unix timestamp in milliseconds when the quote was applied to a transfer. `null` while unused.
    </ResponseField>

    <ResponseField name="used_in_payment_id" type="string | null">
      The ID of the transfer that consumed this quote. `null` while unused.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds when the quote was created.
</ResponseField>

<ResponseField name="updated" type="number">
  Unix timestamp in milliseconds when the quote was last updated.
</ResponseField>

```json Example FX quote object theme={null}
{
  "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
  }
}
```

<Note>
  `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.
</Note>

***

## 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

<ParamField body="from_currency" type="string" required>
  The currency to convert from. ISO 4217 format, e.g. `USD`.
</ParamField>

<ParamField body="to_currency" type="string" required>
  The currency to convert to. ISO 4217 format, e.g. `GHS`.
</ParamField>

<ParamField body="amount_from" type="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.
</ParamField>

<ParamField body="amount_to" type="number">
  The amount to receive, in the smallest unit of `to_currency`. Conditionally required: pass either `amount_from` or `amount_to`, not both.
</ParamField>

<ParamField body="account_id" type="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.
</ParamField>

<ParamField body="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

### Request

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```
</CodeGroup>

### Response

Returns the created [FX Quote object](#the-fx-quote-object) with `quote.status: "active"`.

```json theme={null}
{
  "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

<ParamField path="quote_id" type="string" required>
  The FX quote ID.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/fx-quotes/01HXYZ4680ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

Returns the [FX Quote object](#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.

```json theme={null}
{
  "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`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.