---
title: "Foreign Exchange overview"
description: "Retrieve rates, create quotes, and manage FX orders."
---

# Foreign Exchange overview

Use the Foreign Exchange API to discover supported currencies, retrieve rates and quotes, and create, approve, reject, or cancel FX orders.

<CardGroup cols={2}>
  <Card title="Browse FX endpoints" icon="code" href="/api-reference/fx/get-v1-fx-supported-currencies">
    Discover supported currencies or browse the operations in this category.
  </Card>
  <Card title="Foreign exchange guide" icon="book" href="/platform/foreign-exchange/overview">
    Review rates, quotes, and OTC order workflows.
  </Card>
</CardGroup>

## How it works

The FX API has three layers, from informational to transactional:

1. **Rates** — [`GET /v1/fx/supported-currencies`](/api-reference/fx/get-v1-fx-supported-currencies) lists tradable pairs (fiat by default; add `include_crypto=true` for crypto pairs, cached for one hour), and [`GET /v1/fx/rates`](/api-reference/fx/get-v1-fx-rates) returns live rates across enabled providers.
2. **Quotes** — [`POST /v1/fx/quote`](/api-reference/fx/post-v1-fx-quote) returns a rate quote with a `quote_id` and expiry. Pass the `quote_id` when submitting a transfer to lock in the quoted rate.
3. **OTC orders** — for larger conversions, create an order with [`POST /v1/fx/orders`](/api-reference/fx/post-v1-fx-orders). Orders start in `waiting_approval` and only execute after a **second user approves** them (four-eyes principle). A `market` order executes at the current rate once approved; a `limit` order waits until the rate reaches `target_rate`, then executes once approved. `destination_type` controls where converted funds settle: an internal `account`, a crypto `wallet`, or a saved settlement instruction.

## Endpoints

### Rates and quotes

| Endpoint | Description |
|---|---|
| [`GET /v1/fx/supported-currencies`](/api-reference/fx/get-v1-fx-supported-currencies) | List supported currency pairs from all enabled providers |
| [`GET /v1/fx/rates`](/api-reference/fx/get-v1-fx-rates) | Live exchange rates for multiple pairs |
| [`POST /v1/fx/quote`](/api-reference/fx/post-v1-fx-quote) | Create a rate quote with a `quote_id` and expiry |

### OTC orders

| Endpoint | Description |
|---|---|
| [`POST /v1/fx/orders`](/api-reference/fx/post-v1-fx-orders) | Create a market or limit OTC order (starts in `waiting_approval`) |
| [`GET /v1/fx/orders`](/api-reference/fx/get-v1-fx-orders) | List orders, most recent first, with status/type/side/date filters |
| [`GET /v1/fx/orders/pending-approvals`](/api-reference/fx/get-v1-fx-orders-pending-approvals) | List orders waiting on an approve or reject decision |
| [`GET /v1/fx/orders/{order_id}`](/api-reference/fx/get-v1-fx-orders-order-id) | Retrieve a single order |
| [`POST /v1/fx/orders/{order_id}/cancel`](/api-reference/fx/post-v1-fx-orders-order-id-cancel) | Cancel an order that hasn't executed yet |

<Note>
List filters that match nothing (including unknown `status` values or unsupported currency codes) don't error — they return `200` with an empty result array.
</Note>

## Authentication

All requests use `https://api.gravv.xyz/v1/` and authenticate with the `Api-Key` header. Creating quotes, creating orders, and cancelling orders **require** an `Idempotency-Key` header — requests without one are rejected.