Trades

A trade moves money between two of your currency balances at the rate locked in its quote. This page covers what happens after you execute a trade: the statuses it passes through, what moves it forward, and the two actions you can take on it. How you request a rate and execute against it is on Quotes.

Funds move when a trade reaches EXECUTED, not when you create it. A trade created with a T1 or T2 window waits, and on a per-trade settlement account it then waits for you. Read status before you assume a balance has changed.

Endpoints

Path	Description	Idempotency-Key
`GET /v3/fx/trades/{id}`	Read a trade’s current `status`	—
`GET /v3/fx/trades`	List trades, newest first	—
`POST /v3/fx/trades/{id}/settle`	Finalize a manually settled trade	Required, 24-hr TTL
`POST /v3/fx/trades/{id}/reverse-quote`	Preview the cost of unwinding a trade	Required, 30-min TTL
`POST /v3/fx/trades/{id}/reverse`	Unwind a trade against a reverse quote	Required, 24-hr TTL

State machine

Trade.status is a closed enum, and a trade ends in EXECUTED or REVERSED.

Status	Meaning	What moves it forward
PENDING	Created, funds not yet moved	OpenFX, immediately on execution
LOCKED	A T1 or T2 trade before its settlement window opens	OpenFX, when the window opens
READY_TO_SETTLE	The window opened on a manually settled trade	You: settle or reverse it
EXECUTED	Funds have moved. Terminal	Nothing; the trade is complete
REVERSED	A READY_TO_SETTLE trade was unwound. Terminal	Nothing; the reversal is its own trade

Settlement window

Every trade carries a settlementWindow that you choose on the quote request: IMMEDIATE, T0, T1, or T2. It defaults to T0.

IMMEDIATE and T0 trades settle synchronously, so the execute response already reads EXECUTED.
T1 and T2 trades are future-dated. They sit in LOCKED until the window opens.

What happens when the window opens depends on your organization’s settlement model, an account-level setting rather than a request option.

`tradeSettlementMode`	Model	At window open
AUTO	Netted	The trade settles on its own and reaches EXECUTED. You take no action
MANUAL	Per-trade	The trade reaches READY_TO_SETTLE and waits for you

The models are compared on Settlement models.

Settle a trade

Settling applies only to a trade in READY_TO_SETTLE on a MANUAL account. It completes the trade at the locked rate and populates settledAt and settlementStartTime.

cURL

curl -X POST https://api.openfx.com/v3/fx/trades/tde_5W7guYdHT24JFnRQrZN9y8/settle \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

A successful response wraps a TradeSettlement in data. The trade is now EXECUTED:

{
  "object": "trade",
  "id": "tde_5W7guYdHT24JFnRQrZN9y8",
  "quoteId": "qte_TmHeAhdFLes63uGgDjcJRx",
  "buyCurrency": "USDC",
  "sellCurrency": "USD",
  "executedAmount": "999.25",
  "status": "EXECUTED",
  "clientReferenceId": "order-123",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "settlementWindow": "T0",
  "settledAt": "2026-07-13T10:02:00.000Z",
  "settlementStartTime": "2026-07-13T10:00:30.000Z"
}

Error	Cause
`409` TRADE_NOT_MANUAL	The account settles automatically, so there is nothing to settle
`409` TRADE_NOT_SETTLEABLE	The trade is already settled, not yet executed, or reversed. Read the trade, then decide
`409` TRADE_ALREADY_SETTLED	The trade has already been settled

Reverse a trade

A reversal unwinds a trade in READY_TO_SETTLE instead of settling it. It takes two calls, so you see the cost before you commit.

Generate a reverse quote

POST /v3/fx/trades/{id}/reverse-quote returns a time-limited quote. quoteForSeconds takes the same closed set of durations as a trade quote: 3, 15, 30, 45, or 60.

cURL

curl -X POST https://api.openfx.com/v3/fx/trades/tde_5W7guYdHT24JFnRQrZN9y8/reverse-quote \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "quoteForSeconds": 30 }'

Read reversalDetails before you act. direction says whether the reversal would DEBIT or CREDIT your balance, and differentialAmount is the unsigned magnitude in currency.

{
  "object": "quote",
  "id": "qte_TmHeAhdFLes63uGgDjcJRx",
  "buyCurrency": "USD",
  "sellCurrency": "USDC",
  "quoteAmount": "122.93850769",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "expiresAt": "2026-07-13T10:00:30.000Z",
  "reversalDetails": {
    "direction": "DEBIT",
    "differentialAmount": "0.75",
    "currency": "USD"
  },
  "buyAmount": "122.93850769"
}

Execute the reversal

POST /v3/fx/trades/{id}/reverse names the reverse quote’s id as quoteId. Send it before expiresAt. An optional clientReferenceId labels the reversal.

cURL

curl -X POST https://api.openfx.com/v3/fx/trades/tde_5W7guYdHT24JFnRQrZN9y8/reverse \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "qte_TmHeAhdFLes63uGgDjcJRx", "clientReferenceId": "order-123-reversal" }'

The response is a new trade, created already EXECUTED. Its originalTradeId points at the trade it unwound, and the original trade reads REVERSED.

{
  "object": "trade",
  "id": "tde_8XvH7fKH8hcFyopFF2PFas",
  "quoteId": "qte_TmHeAhdFLes63uGgDjcJRx",
  "buyCurrency": "USD",
  "sellCurrency": "USDC",
  "executedAmount": "999.25",
  "status": "EXECUTED",
  "clientReferenceId": "order-123-reversal",
  "createdAt": "2026-07-13T10:00:00.000Z",
  "settlementWindow": "T0",
  "settlementStartTime": null,
  "originalTradeId": "tde_5W7guYdHT24JFnRQrZN9y8",
  "reversalDetails": {
    "direction": "CREDIT",
    "differentialAmount": "0.75",
    "currency": "USD"
  }
}

A trade that is outside its reversal window, or already reversed or settled, returns 409 TRADE_NOT_REVERSIBLE.

Track a trade

Trade webhooks report each transition, so you don’t need to poll. The three events map one-to-one onto the statuses a trade reaches under your own action or OpenFX’s.

Webhook	Fires when	`data.status`
fx.trade.ready_to_settle	A future-dated, manually settled trade reaches its window and awaits settle	READY_TO_SETTLE
fx.trade.settled	A trade reaches EXECUTED, immediately or once settled	EXECUTED
fx.trade.reversed	A READY_TO_SETTLE trade is unwound	REVERSED

An AUTO account only receives fx.trade.settled. A MANUAL account can receive all three. The webhook data is close to the Trade resource but not identical. It adds tradeSettlementMode and settledAt, and on fx.trade.reversed it adds reversalTradeId and reversalDetails. settledAt is null on a reversal, because a reversal only ever unwinds a trade that was never settled. Webhooks setup covers delivery and signature verification. If you can’t receive webhooks yet, poll GET /v3/fx/trades/{id} and read status.

Effect on balances and exposure

A trade changes your balances when it reaches EXECUTED. Read GET /v3/fx/balances afterward; the trade response does not carry the balance impact. Before then, an open trade counts against your exposure limit. A LOCKED trade counts as settlableLater exposure and a READY_TO_SETTLE trade as settlableNow. See Exposure.

Common mistakes

Expecting EXECUTED from a future-dated trade. A T1 or T2 trade returns before its window opens, so its funds have not moved.
Calling settle on an automatic account. It returns 409 TRADE_NOT_MANUAL. Netted accounts never settle by hand.
Letting a reverse quote lapse. The reversal must reach POST /v3/fx/trades/{id}/reverse before expiresAt; generate a new reverse quote with a new idempotency key.
Reading the reversal as the original. The reversal is a separate trade with its own id. Match it to the original through originalTradeId, or reversalTradeId on the webhook.
Retrying a failed execution blind. After TRADE_EXECUTION_FAILED, call GET /v3/fx/trades/{id} to check state first.

What’s next

Settlement models

Netted and per-trade settlement, side by side.

Balances

What changes in each currency when a trade executes.

Trade webhooks

Ready-to-settle, settled, and reversed events.

Exposure

Exposure-limit usage from trades that have not settled.

Get Started

Convert

Send

Endpoints

State machine

Settlement window

Settle a trade

Reverse a trade

Track a trade

Effect on balances and exposure

Common mistakes

What’s next

Settlement models

Balances

Trade webhooks

Exposure

​Endpoints

​State machine

​Settlement window

​Settle a trade

​Reverse a trade

​Track a trade

​Effect on balances and exposure

​Common mistakes

​What’s next

Settlement models

Balances

Trade webhooks

Exposure

Endpoints

State machine

Settlement window

Settle a trade

Reverse a trade

Track a trade

Effect on balances and exposure

Common mistakes

What’s next