---
title: "Create an FX rate"
method: POST
path: "/v1/rates"
tags: ["FXP Rates"]
---

# Create an FX rate

`POST /v1/rates`

Creates a new exchange rate for a currency pair. If a live rate already exists for the same currency pair, it is automatically marked as superseded and kept as a historical record. Quotes already issued against the previous rate remain valid for 10 minutes, known as the NQVT window. Nexus may throttle this endpoint, and an idempotency key header is recommended so that retried submissions are not duplicated. Requires the scope rates.write. Used by: FX Providers (FXPs)

## Headers

- `Idempotency-Key` string, uuid

## Request body

- RateInputDto — Request body for creating a rate. Any live rate that already exists for the same FXP and currency pair is automatically superseded.
  - `sourceCurrency` string, required — ISO 4217 currency code of the source currency, three uppercase letters.
  - `destinationCurrency` string, required — ISO 4217 currency code of the destination currency, three uppercase letters.
  - `rate` number, required — Exchange rate, where UnitCcyAmount multiplied by rate equals QtyCcyAmount. Must be greater than 0.

## Response `200`

The created rate record.

- RateDto — An exchange rate provided by an FXP for a specific currency pair. Each rate applies in one direction only, and the rate for the opposite direction is configured separately. A rate stays live until it is replaced by a newer rate for the same currency pair or withdrawn. Nexus does not expire rates based on time.
  - `id` string, required — Unique ID of the rate record.
  - `sourceCurrency` string, required — ISO 4217 currency code of the source currency, three uppercase letters.
  - `destinationCurrency` string, required — ISO 4217 currency code of the destination currency, three uppercase letters.
  - `rate` number, required — Exchange rate, where UnitCcyAmount multiplied by rate equals QtyCcyAmount. Must be greater than 0.
  - `createdDateTime` string, date-time, required — Timestamp at which the rate record was created.
  - `isExpired` boolean, required — Historical marker set to true when the rate is replaced or withdrawn. It does not mean the rate expired with time.
  - `expiryDateTime` string, date-time, nullable — Timestamp at which the rate was replaced or withdrawn. A historical marker only.

## Other responses

- `400` — Invalid request — syntax, schema, or field-level validation failure.
- `401` — Missing or invalid bearer token.
- `403` — Caller lacks permission for this resource or operation.
- `409` — Update rejected due to conflicting state.
- `429` — Rate limit exceeded. Returned by the API gateway and carries no structured Nexus body. The Retry-After response header indicates when to retry.
- `500` — Unexpected server fault; caller may retry.

---

[API](https://skmtc.net/nexusglobalpayments/apis/nexus-apis.md) · [All operations](https://skmtc.net/nexusglobalpayments/apis/nexus-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nexusglobalpayments/nexus-apis/revisions/b3e625f21841/schema)