Exchange (New) - Overview
Introduction
The Exchange (New) API provides a comprehensive set of endpoints for managing FX (foreign exchange) trades across developed and emerging markets. This API enables seamless cross-border payment experiences with support for wallet-to-wallet and wallet-to-account conversions.
Features
- FX Trade Management: Create and retrieve individual or bulk FX trades
- Real-Time Rates: Get live exchange rates with a short-lived token for executing trades
- Flexible Payment Modes: Choose between immediate and deferred settlement
- Markup Configuration: Set and retrieve FX markup configurations per currency pair or universally
- Sender Information: Pass underlying sender details for compliance and AML requirements
- POBO Support: Pay on behalf of another entity
Authentication
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer <your_jwt_token>
Base URL
Production: https://api.ahrvo.network
Staging: https://gateway.ahrvo.network
Common Headers
| Header | Value | Required | Description |
|---|---|---|---|
Authorization | Bearer {token} | Yes | JWT authentication token |
Content-Type | application/json | Yes | Request content type |
Accept | application/json | Yes | Response content type |
x-api-key | string | No | API key for additional authentication |
Getting Started
- Get FX Rate: Call the Get Rates endpoint to receive a real-time exchange rate and a
vfx_token - Create FX Trade: Use the
vfx_token(valid for 30 seconds) to execute a currency conversion - Track Trades: Use the Get an FX Trade or Get All FX Trades endpoints to monitor trade status
- Configure Markup: Optionally configure per-company FX markup using the markup configuration endpoints
API Endpoints
Rate
- Get Rates (New) - Get live FX rate with a token for trade execution
Trade
- Get All FX Trades (New) - Fetch all FX trades with filters
- Create FX Trade (New) - Create a new currency exchange trade
- Get an FX Trade (New) - Retrieve a specific trade by reference
Markup Configuration
- FX Markup Configuration - Set and retrieve FX markup settings
Trade States
| State | Description |
|---|---|
confirmed | Trade confirmed and pending settlement |
inwardSettlementDone | Sender's account has been debited |
outwardSettlementDone | Receiver's account has been credited |
inwardSettlementPending | Awaiting inward settlement |
outwardSettlementPending | Awaiting outward settlement |
Payment Modes
| Mode | Description |
|---|---|
immediate | Funds are deducted from your wallet instantly |
later | Settle within up to 24 hours |
Support
For API support and questions, please contact the Ahrvo FX support team.