Get FX Rates (New)

Overview

The Get Rates API retrieves current market foreign exchange rates for a specified currency pair.

Upon successful calculation, the response returns the current rate along with a cryptographic vfx_token valid for 30 seconds. This token locks in the quoted price and must be provided when calling POST /banking/ibans/v2/fx/payments to execute the trade.

Rate Lock Window

The vfx_token is valid for precisely 30 seconds. Execute the trade immediately upon receiving the token to avoid expiration exceptions.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/rate
• Authentication: Bearer token required (Authorization: Bearer {access_token})

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Response content type
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	application/json	Yes	Request body content type
x-api-key	string	No	Optional API key

Request Body

{
  "paymentMode": "immediate",
  "currencyFrom": {
    "currencyName": "USD"
  },
  "currencyTo": {
    "currencyName": "NGN"
  }
}

Request Fields

Field	Type	Required	Description
paymentMode	string	No	Settlement option (immediate). Default is immediate.
currencyFrom.currencyName	string	Yes	3-letter ISO code for the source currency to sell (e.g. USD).
currencyTo.currencyName	string	Yes	3-letter ISO code for the target currency to buy (e.g. NGN).

Response

Success Response (200 OK)

{
  "success": true,
  "rate": 1028.4456,
  "vfx_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeUZyb20iOiJVU0QiLCJjdXJyZW5jeVRvIjoiTkdOIiwicmF0ZSI6MTAyOC40NDU2LCJpYXQiOjE3MjExMjAyMDcsImV4cCI6MTcyMTEyMDIzN30.demoToken",
  "expiresAt": "2026-09-15T12:00:30Z"
}

Response Fields

Field	Type	Description
success	boolean	Boolean flag indicating whether the rate quote succeeded (true).
rate	number	The current exchange rate for the requested pair.
vfx_token	string	Rate lock token valid for 30 seconds. Pass to POST /banking/ibans/v2/fx/payments.
expiresAt	string (ISO Date)	Timestamp when the quoted rate and token expire.

Error Responses

• 400 Bad Request: Invalid or unsupported currency pair.
• 401 Unauthorized: Missing or expired Bearer token.
• 500 Internal Server Error: Downstream liquidity provider error.

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/fx/rate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "paymentMode": "immediate",
    "currencyFrom": {"currencyName": "USD"},
    "currencyTo": {"currencyName": "NGN"}
  }'

Python

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/fx/rate"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "paymentMode": "immediate",
    "currencyFrom": {"currencyName": "USD"},
    "currencyTo": {"currencyName": "NGN"}
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"Quoted Rate: {data.get('rate')}")
print(f"Token: {data.get('vfx_token')}")

JavaScript / Node.js

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/fx/rate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    paymentMode: "immediate",
    currencyFrom: { currencyName: "USD" },
    currencyTo: { currencyName: "NGN" }
  })
});

const quote = await response.json();
console.log("Locked Rate:", quote.rate);
console.log("vfx_token:", quote.vfx_token);

Interactive API Explorer