> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs-v3.openfx.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Execute trade
> Executes a currency exchange against a valid quote ID. Must be called within 3 seconds of quote generation.
**v1 sunsets December 31, 2026.** Migrate to v2 — see the [migration guide](/v1/migration-v1-to-v2).
Executes a currency exchange trade using a valid quote ID. Must be called within 3 seconds of quote generation.
Use this endpoint to:
* Execute currency exchanges
* Lock in quoted rates
* Convert between currencies
* Initiate settlement process
Idempotency is supported on v2 and v3 for this endpoint. v1 does not support idempotency keys — see [Migration guide](/v1/migration-v1-to-v2).
## Errors
| Status | Message | Notes |
| ------ | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 400 | `Query validation failed` | Request didn't match schema (bad quote ID, missing fields, etc.) |
| 401 | `The authorization key provided is either invalid or expired, please try again` | Mint a fresh JWT — see [Authentication](/v1/authentication) |
| 500 | `An internal error has occurred` | Server fault. Writes are non-idempotent in v1 — fetch the trade by ID before retrying to avoid double-execution |
See the full [v1 error reference](/v1/errors).
## OpenAPI
````yaml POST /v1/brokerage/{orgId}/trade
openapi: 3.1.0
info:
title: Overview of OpenFX APIs
description: >-
OpenFX provides a robust and secure API suite engineered for high
performance and reliability, enabling programmatic access to real-time
market data, trade execution, and money movement functionalities. This guide
will walk through the step-by-step process of deposits, quoting, trading,
settlements and monitoring using OpenFX APIs.
version: v1.0.0
termsOfService: https://www.openfx.com/terms
contact:
name: OpenFX Support
email: support@openfx.com
url: https://www.openfx.com
servers:
- url: https://api.openfx.com
description: OpenFX API Server
security:
- bearerAuth: []
tags:
- name: MarketData
description: >-
This endpoint retrieves a complete list of all tradable fiat and
stablecoin currency pairs on the OpenFX platform.
- name: Balances
description: >-
The Balance endpoints enable real-time tracking and management of currency
holdings within an account.
- name: Trade
description: >-
The Trade APIs facilitate programmatic currency exchange through a
quote-then-trade workflow, ensuring price transparency and guaranteed
execution at quoted rates.
- name: Deposits
description: >-
Deposit endpoints enable secure funding of trading accounts across
multiple supported currencies and methods.
- name: Withdrawals
description: >-
The Withdrawal API facilitates secure fund withdrawals for both fiat and
stablecoins.
paths:
/v1/brokerage/{orgId}/trade:
post:
tags:
- Trade
summary: Execute trade
description: >
Executes a currency exchange trade using a valid quote ID. Must be
called within 3 seconds of quote generation.
Use this endpoint to:
- Execute currency exchanges
- Lock in quoted rates
- Convert between currencies
- Initiate settlement process
**Idempotency (V2 only):** This endpoint requires an `Idempotency-Key`
header. Keys are cached for 24 hours. Reusing a key with the same
parameters returns the cached response; different parameters return a
422 error.
operationId: executeTrade
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
description: >-
Unique key to ensure idempotent requests. UUID v4 recommended. Valid
for 24 hours.
- schema:
type: string
in: path
name: orgId
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
quoteId:
type: string
format: uuid
example: d8bc9618-2830-1822-9ae2-414aaf2b2de3
required:
- quoteId
responses:
'200':
description: success
content:
application/json:
schema:
type: object
properties:
status:
type: string
enum:
- success
- error
example: success
data:
type: object
properties:
balances:
type: object
additionalProperties:
type: number
example:
USD: 5000
USDC: 100
description: >-
Updated user balances after the trade, keyed by
currency symbol
trade:
type: object
properties:
id:
type: string
format: uuid
example: 24753ee0-c3e9-4268-a48f-0cef3559f17f
description: Unique identifier of the executed trade
buy:
type: string
example: USDC
description: Currency symbol that user is buying
sell:
type: string
example: USD
description: Currency symbol that user is selling
referencedUnit:
type: string
example: USD
description: >-
Currency symbol used to specify the original trade
input amount
referencedAmount:
type: number
example: 123
description: >-
The amount the trade was based on, in the
referenced currency
amount:
type: number
example: 122
description: The final amount transacted after fees or rounding
status:
type: string
example: EXECUTED
description: Status of the trade execution
transactedAt:
type: string
example: '2025-01-21T17:37:33.074Z'
description: UTC Timestamp when the trade was executed
quoteId:
type: string
format: uuid
example: 75324ee0-a48f-c3e9-4268-0cef3559f17f
description: >-
Unique identifier of the quote associated with
this trade
userCreditLimit:
type: number
example: 10000000
description: Total credit limit available to the user
userCreditUsed:
type: number
example: 8844000.51844473
description: Amount of credit used by the user after this trade
message:
type: string
example: Data fetched successfully
examples:
default_example:
value:
status: success
data:
balances:
USD: -596064.969940321
USDC: -9893214.59296976
USDT: 8654884.42360652
trade:
id: 2c011d8b-1822-4d1c-9b16-414aaf2b2de4
buy: USD
sell: USDC
referencedUnit: USD
referencedAmount: 100
amount: 101
status: EXECUTED
transactedAt: '2025-02-10T07:40:21.300Z'
quoteId: d8bc9618-2830-1822-9ae2-414aaf2b2de3
userCreditLimit: 10000000
userCreditUsed: 8844000.51844473
'400':
description: Bad Request
content:
application/json:
examples:
default_example:
value:
status: error
message: Query validation failed
'401':
description: Unauthorized
content:
application/json:
examples:
default_example:
value:
status: error
message: >-
The authorization key provided is either invalid or
expired, please try again
'409':
description: Conflict
content:
application/json:
examples:
default_example:
value:
status: error
message: Request with this idempotency key is currently processing
error:
code: IDEMPOTENCY_IN_FLIGHT
details: Please wait for the original request to complete
'422':
description: Unprocessable Entity
content:
application/json:
examples:
default_example:
value:
status: error
message: Idempotency key reused with different parameters
error:
code: IDEMPOTENCY_MISMATCH
details: >-
This idempotency key was already used with different
request parameters
'500':
description: Internal Server Error
content:
application/json:
examples:
default_example:
value:
status: error
message: An internal error has occurred
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````