Execute trade

Use the Execute trade endpoint to complete a currency exchange. There are two trade directions:

buy
sell

For example, you can buy USD with ZAR by setting the direction in your request body to buy:

curl --request POST \
     --url https://api.gravv.xyz/v1/fx/trade \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "direction": "buy",
  "from_currency": "ZAR",
  "to_currency": "USD",
  "amount": 1000,
  "provider": "standard-bank"
}
'

The following fields are required in the request body:

Fields	Type	Description
from_currency	string	The currency you want to trade (3-letter ISO 4217 code)
to_currency	string	The currency you want to trade to (3-letter ISO 4217 code)
amount	number	Amount to trade (must be greater than 0)
direction	string	Trade direction can either be `buy` or `sell`

The following fields are optional:

Fields	Type	Description
provider	string	Specific provider to use for the trade
quote_id	string	Quote ID to lock in a specific rate

The endpoint returns a confirmation showing your executed trade details:

{
  "data": {
    "provider_id": "standard-bank",
    "trade_id": "trade_xyz789",
    "status": "EXECUTED",
    "from_currency": "ZAR",
    "to_currency": "USD",
    "executed_rate": 0.058,
    "executed_amount": 58,
    "direction": "buy",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "error": null
}

Lock in a rate with quote_id

When you request an exchange rate, the response includes a quote_id. Use this ID in your trade request to execute at that specific rate:

curl --request POST \
     --url https://api.gravv.xyz/v1/fx/trade \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "direction": "buy",
  "from_currency": "ZAR",
  "to_currency": "USD",
  "amount": 1000,
  "provider": "standard-bank",
  "quote_id": "quote_abc123"
}
'