Get Rates (New)

Overview

Get the current actual FX rate for a given currency pair using the currencyFrom, currencyTo, and paymentMode parameters. The paymentMode specifies the settlement option for the trade.

In the response, you'll receive a vfx_token with an expiry of 30 seconds. Use this token to create an FX trade before it expires.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/rate
• Authentication: Bearer token required

Request Headers

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

Request Body

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

Request Fields

Field	Type	Required	Description
paymentMode	string	No	Settlement option: immediate or later. Default: immediate
currencyFrom	object	Yes	The currency you are selling to Ahrvo
currencyFrom.currencyName	string	Yes	3-character ISO 4217 currency code (e.g., USD)
currencyTo	object	Yes	The currency you are buying from Ahrvo
currencyTo.currencyName	string	Yes	3-character ISO 4217 currency code (e.g., NGN)

Payment Modes

Mode	Description
immediate	Funds are deducted from your wallet instantly at the time of the trade
later	You intend to settle within up to 24 hours of the trade

Response

Success Response (200 OK)

{
  "success": true,
  "rate": "571.48838125",
  "vfx_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiry": "2024-07-16T11:12:08.343Z"
}

Response Fields

Field	Type	Description
success	boolean	Indicates whether the request was successful
rate	string	The current exchange rate for the currency pair
vfx_token	string	Rate token to use for trade execution (valid 30 seconds)
expiry	string (date-time)	Timestamp when the token expires

Error Responses

• 400 Bad Request: Invalid currency codes or parameters
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Insufficient permissions
• 500 Internal Server Error: Server error

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

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

Python

import requests

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

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Rate: {result['rate']}, Token: {result['vfx_token']}")

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/fx/rate';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  paymentMode: 'immediate',
  currencyFrom: { currencyName: 'AUD' },
  currencyTo: { currencyName: 'USD' }
};

axios.post(url, data, { headers })
  .then(response => {
    console.log('Rate:', response.data.rate);
    console.log('Token expires:', response.data.expiry);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• The vfx_token is valid for 30 seconds from the time of issue
• Always use the token within its validity period to lock in the quoted rate
• Request a new rate token if the previous one has expired
• Store the vfx_token temporarily and use it immediately to create an FX trade

Workflow

1. Get Rate: Call this endpoint with your desired currency pair
2. Review Rate: Confirm the rate is acceptable for your transaction
3. Create Trade: Use the vfx_token within 30 seconds to execute the trade via Create FX Trade
4. Handle Expiry: If the token expires, request a new rate

Interactive API Explorer