Get exchange rates

You can check which currency pairs Gravv supports and retrieve current exchange rates before executing trades.

Check supported currency pairs

Use the Get supported currencies endpoint to see all available currency pairs:

curl --request GET \
     --url https://api.gravv.xyz/v1/fx/supported-currencies \
     --header 'Api-Key: <Api Key>'

You will receive a response showing available currency pairs and their providers:

{
  "data": {
    "currencies": [
      {
        "from_currency": "USD",
        "to_currency": "ZAR",
        "currency_pair": "USD/ZAR",
        "providers": [
          "standard-bank"
        ],
        "from_currency_name": "United States Dollar",
        "to_currency_name": "South African Rand"
      },
      {
        "from_currency": "EUR",
        "to_currency": "GBP",
        "currency_pair": "EUR/GBP",
        "providers": [
          "standard-bank"
        ],
        "from_currency_name": "Euro",
        "to_currency_name": "British Pound"
      }
    ]
  },
  "error": null
}

Request an exchange rate

Use the Request rate quote endpoint to get a current exchange rate for a specific currency pair. Include your Api-Key and the x-tenant-id header:

curl --request POST \
     --url https://api.gravv.xyz/v1/fx/rate \
     --header 'Api-Key: <Api Key>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'x-tenant-id: <tenant id>' \
     --header 'content-type: application/json' \
     --data '
{
  "from_currency": "USD",
  "to_currency": "ZAR",
  "amount": 100.00
}
'

The response includes a rate quote with an expiration time. Save the quote_id if you want to lock in this rate for your trade:

{
  "data": {
    "provider_id": "standard-bank",
    "quote_id": "quote_abc123xyz",
    "from_currency": "USD",
    "to_currency": "ZAR",
    "rate": 18.5432,
    "amount": 100.00,
    "expires_at": "2024-01-15T10:35:00Z"
  },
  "error": null
}

Specify a provider

You can request a rate from a specific provider by including the provider field:

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

Get all exchange rates

Use the Get all currency pair rates endpoint to retrieve current rates for multiple currency pairs:

curl --request GET \
     --url https://api.gravv.xyz/v1/fx/rates \
     --header 'Api-Key: <Api Key>'

You will receive rates for all available currency pairs:

{
  "data": {
    "rates": [
      {
        "provider_id": "standard-bank",
        "currency_pair": "USD/ZAR",
        "from_currency": "USD",
        "to_currency": "ZAR",
        "rate": 18.5432,
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "provider_id": "standard-bank",
        "currency_pair": "EUR/GBP",
        "from_currency": "EUR",
        "to_currency": "GBP",
        "rate": 0.8521,
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "error": null
}

Filter exchange rates

You can filter rates by source currency, target currency, or specific currency pairs:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/fx/rates?from_currency=USD' \
     --header 'Api-Key: <Api Key>'

curl --request GET \
     --url 'https://api.gravv.xyz/v1/fx/rates?to_currency=ZAR' \
     --header 'Api-Key: <Api Key>'

curl --request GET \
     --url 'https://api.gravv.xyz/v1/fx/rates?currency_pairs=USD/ZAR,EUR/GBP' \
     --header 'Api-Key: <Api Key>'