Create an order
Trades a quote. With an API key there is no approval step. The order starts as pending and Gravv debits the source at once. Then get the order until it is completed or cancelled. FX orders send no webhooks.
If the error is order source could not be charged, an order may still exist; list your orders before you retry with a new quote.
Headers
1 to 255 printable ASCII characters. A retry with the same key within 24 hours returns the first response, including a 400. After you correct a request, send a new key.
Request Body
A quote from POST /v1/fx/quote that has not expired or been used
Your account or crypto wallet that pays the sold amount. It must hold at least from_amount in the FROM currency. It cannot be external_account.
internal_account or internal_crypto_wallet. For a destination, external_account means a settlement instruction, not a customer's external account.
Possible values: internal_account, internal_crypto_wallet, external_account
ID of your account, crypto wallet or settlement instruction
Where the bought amount goes. It is your account or crypto wallet, or an active settlement instruction (external_account) in the TO currency.
internal_account or internal_crypto_wallet. For a destination, external_account means a settlement instruction, not a customer's external account.
Possible values: internal_account, internal_crypto_wallet, external_account
ID of your account, crypto wallet or settlement instruction
Optional ID to give the order. It becomes order_id.
Your reference. It does not have to be unique.
Your data, returned on the order
Request Examples
{
"quote_id": "GRVOTC_3F9A1C",
"source": {
"type": "internal_account",
"id": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d"
},
"destination": {
"type": "external_account",
"id": "b7e1c2d3-4f5a-4b6c-9d8e-7f6a5b4c3d2e"
},
"client_reference": "inv-2026-1042",
"metadata": {
"desk": "treasury"
}
}
Responses
| Status | Description |
|---|---|
200 |
The order is created |
400 |
The quote is expired or used, a leg is invalid, the source balance is too low, or the debit failed |
403 |
The key lacks fx:order_create, or your business does not have access to the OTC trade desk |
200 response
An order made with an API key starts as pending, and Gravv debits its source at once. It then becomes completed, or cancelled if the debit fails. waiting_approval is for orders made in the Dashboard.
Possible values: waiting_approval, pending, completed, rejected, cancelled
{
"data": {
"order_id": "2d4f6a8c-1b3d-4e5f-8a7b-9c0d1e2f3a4b",
"quote_id": "GRVOTC_3F9A1C",
"status": "pending"
},
"error": null
}
400 response
What went wrong. FX errors carry no code.
{
"data": null,
"error": "quote is invalid or expired"
}
{
"data": null,
"error": "bad source: [400] source balance is not enough for currency: USD, amount: 10000"
}
{
"data": null,
"error": "bad destination: [400] invalid order destination"
}
403 response
Authorization
- ApiKeyAuth