Get FX Quote

Overview

Retrieve real-time foreign exchange rate quotes for currency conversions. The quote you receive is valid for a specified period (default 15 seconds), during which you can execute a transaction at the quoted rate using the returned rate_id.

Resource Access

• HTTP Method: GET
• Endpoint: /banking/iban/api/fx/v2/rate/query
• 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
on-behalf-of	string	No	Customer ID for on-behalf-of operations

Query Parameters

Parameter	Type	Required	Description
buy_currency	string	Yes	The currency to buy (3-letter ISO code)
sell_currency	string	Yes	The currency to sell (3-letter ISO code)
buy_amount	number	Conditional	Amount of buy currency (specify either buy_amount OR sell_amount)
sell_amount	number	Conditional	Amount of sell currency (specify either buy_amount OR sell_amount)
value_date	string	No	Settlement date (yyyy-MM-dd, not required for instant FX)
valid_time	string	No	Quote validity period (default: 15S)

Request Example

GET /banking/iban/api/fx/v2/rate/query?buy_currency=CNH&sell_currency=USD&sell_amount=100&valid_time=15S

Response

Success Response (200 OK)

{
  "rate_id": "8457823465836486583",
  "buy_currency": "CNH",
  "sell_currency": "USD",
  "buy_amount": 725.00,
  "sell_amount": 100.00,
  "exchange_rate": 7.25,
  "inverse_rate": 0.1379,
  "valid_until": "2026-01-14T10:00:15.000Z",
  "value_date": "2024-12-02",
  "created_at": "2026-01-14T10:00:00.000Z"
}

Response Fields

Field	Type	Description
rate_id	string	Unique rate identifier for executing transaction
buy_currency	string	Currency being bought
sell_currency	string	Currency being sold
buy_amount	number	Amount to receive in buy currency
sell_amount	number	Amount to pay in sell currency
exchange_rate	number	Exchange rate (buy/sell)
inverse_rate	number	Inverse exchange rate (sell/buy)
valid_until	string (date-time)	Quote expiration timestamp
value_date	string (date)	Settlement date
created_at	string (date-time)	Quote creation timestamp

Error Responses

• 400 Bad Request: Invalid parameters or unsupported currency pair
• 401 Unauthorized: Invalid or missing authentication token
• 404 Not Found: Currency pair not supported

Code Examples

cURL

curl -X GET \
  'https://gateway.ahrvo.network/banking/iban/api/fx/v2/rate/query?buy_currency=CNH&sell_currency=USD&sell_amount=100&valid_time=15S' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Python

import requests

url = "https://gateway.ahrvo.network/banking/iban/api/fx/v2/rate/query"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
params = {
    "buy_currency": "CNH",
    "sell_currency": "USD",
    "sell_amount": 100,
    "valid_time": "15S"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/iban/api/fx/v2/rate/query';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = {
  buy_currency: 'CNH',
  sell_currency: 'USD',
  sell_amount: 100,
  valid_time: '15S'
};

axios.get(url, { headers, params })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Amount Specification: Specify EITHER buy_amount OR sell_amount, not both
• Rate Validity: Default validity is 15 seconds; use valid_time parameter to adjust
• Rate ID: Use the returned rate_id to execute conversions at the quoted rate
• Expiration: Quotes expire after the validity period; obtain a new quote if expired
• Currency Pairs: Not all currency pairs may be supported; check with your account manager

Valid Time Format

The valid_time parameter accepts the following formats:

• 15S - 15 seconds (default)
• 30S - 30 seconds
• 1M - 1 minute
• 5M - 5 minutes

Best Practices

1. Request quotes just before executing conversions
2. Store rate_id temporarily for immediate use
3. Implement error handling for expired quotes
4. Monitor rate movements for optimal timing
5. Use appropriate valid_time based on your workflow

Workflow Example

1. Get Quote: Call this endpoint to receive a rate
2. Review Rate: Check if the rate is acceptable
3. Execute Conversion: Use the rate_id to create FX conversion within validity period
4. Handle Expiration: If quote expires, request a new one

Interactive API Explorer