Create an FX Trade (Legacy)

Overview

This service is used to convert money between different currencies within wallets. You must include the vfx_token obtained from the Get FX Rate endpoint within its 30-second validity window. Specify side as SELL or BUY as well as the transaction amount.

Resource Access

• HTTP Method: POST
• Endpoint: /orders/v2.1/fx
• 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

{
  "vfx_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeUZyb20iOiJVU0QiLCJjdXJyZW5jeVRvIjoiTkdOIiwiY29tcGFueUlkIjoiNTI1IiwicmF0ZSI6NTcxLjQ4ODM4MTI1LCJzcHJlYWQiOjkuNjYxNjE4NzUsImlhdCI6MTcyMTAzODkwMiwiZXhwIjoxNzIxMDM4OTMyfQ.pI2LSZ8ulaWVuxqGVRe_ORv8yyXepx771glEVFcIluo",
  "side": "SELL",
  "amount": 100,
  "clientReference": "Test 100"
}

Request Fields

Field	Type	Required	Description
vfx_token	string	Yes	Token returned by the Get FX Rate API. Valid for 30 seconds.
side	string	Yes	SELL to sell source currency, or BUY to purchase fixed target currency.
amount	number	Yes	The amount to BUY or SELL.
clientReference	string	No	Custom tracking reference (max 35 alphanumeric characters).

Response

Success Response (200 OK)

{
  "success": true,
  "order": {
    "id": 3009,
    "reference": "EN-15072024-002",
    "amountFrom": 100,
    "amountTo": 57148.84,
    "rate": "571.4883812500",
    "transactionState": "inward_remittance_confirmed",
    "status": "deposit_recorded",
    "clientReference": "Test100",
    "currencyFrom": "USD",
    "currencyTo": "NGN"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates whether the trade order creation was successful.
order.id	number	Unique identifier for the FX trade order.
order.reference	string	Internal transaction reference number.
order.amountFrom	number	Source amount debited.
order.amountTo	number	Target amount credited.
order.rate	string	Executed exchange rate.
order.transactionState	string	State of the remittance (e.g. inward_remittance_confirmed).
order.status	string	Current status of deposit/order (e.g. deposit_recorded).
order.clientReference	string	Client reference provided in the request.
order.currencyFrom	string	Source currency code.
order.currencyTo	string	Target currency code.

Error Responses

• 400 Bad Request: Invalid parameters or malformed request
• 401 Unauthorized: Missing or invalid Bearer authentication token
• 403 Forbidden: Insufficient account permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: An internal server error occurred

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/orders/v2.1/fx' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "vfx_token": "YOUR_VFX_TOKEN",
    "side": "SELL",
    "amount": 100,
    "clientReference": "Test 100"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/orders/v2.1/fx"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "vfx_token": "YOUR_VFX_TOKEN",
    "side": "SELL",
    "amount": 100,
    "clientReference": "Test 100"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/orders/v2.1/fx';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  vfx_token: 'YOUR_VFX_TOKEN',
  side: 'SELL',
  amount: 100,
  clientReference: 'Test 100'
};

axios.post(url, data, { headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response ? error.response.data : error.message));

Usage Notes

• If side is BUY, amount specifies the fixed units of target currency to receive.
• If side is SELL, amount specifies the fixed units of source currency to exchange.
• Store order.id and order.reference to query status via Get FX Trade.

Interactive API Explorer