Get All FX Trades (New)

Overview

Fetch all the FX trades initiated by your company. You can filter results by source/target pairs, trade state, date range, and payment IDs. Results are paginated using limit and skip query parameters.

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/fx/list
• 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

Query Parameters

Parameter	Type	Required	Description
limit	integer	Yes	Maximum number of records to return (1–100)
skip	integer	Yes	Number of items to skip for pagination

Request Body

{
  "sourceTargetPairs": [
    {"source": "wallet", "target": "account"},
    {"source": "account", "target": "wallet"},
    {"source": "account", "target": "account"},
    {"source": "wallet", "target": "wallet"}
  ],
  "state": {
    "include": ["inwardSettlementDone"]
  },
  "createdStartDate": "2024-02-20T18:30:00.000Z",
  "createdEndDate": "2024-03-22T18:29:59.999Z",
  "paymentIds": ["88ba34cd-7074-46f4-a006-4fd8c7a5e1e8"]
}

Request Fields

Field	Type	Required	Description
sourceTargetPairs	array	No	Filter by source/target pairs (wallet or account)
state.include	array	No	Filter by trade states (e.g., inwardSettlementDone)
createdStartDate	string	No	Start of creation date range (ISO 8601)
createdEndDate	string	No	End of creation date range (ISO 8601)
paymentIds	array	No	Filter by specific payment IDs

Response

Success Response (200 OK)

{
  "totalCount": 355,
  "items": [
    {
      "id": "20088",
      "reference": "EN-05062024-055",
      "userId": "2289",
      "companyId": "2233",
      "currencyFrom": "USD",
      "amountFrom": 4800,
      "currencyTo": "NGN",
      "amountTo": 4936560,
      "rate": 1028.4456,
      "pricing": {
        "overageFee": 0,
        "usageId": "6660409cc733e0fac55eb97f",
        "subscriptionId": "664b3fc0e8e52032427e0b70"
      },
      "state": "inwardSettlementDone",
      "source": "wallet",
      "sourceId": "11435",
      "target": "account",
      "targetId": "32655",
      "description": null,
      "inwardSettlementTime": "2024-06-05T10:40:44.000Z",
      "outwardSettlementTime": null,
      "purpose": "Professional fees payment",
      "createdAt": "2024-06-05T10:40:29.000Z",
      "updatedAt": "2024-06-05T10:40:51.000Z",
      "paymentId": "064e9219-401e-4cec-a201-6324266bc3cb"
    }
  ]
}

Response Fields

Field	Type	Description
totalCount	number	Total number of FX trades matching the filters
items	array	Array of FX trade objects
items[].id	string	Unique trade identifier
items[].reference	string	Ahrvo reference number
items[].currencyFrom	string	Source currency code
items[].amountFrom	number	Source amount
items[].currencyTo	string	Target currency code
items[].amountTo	number	Target amount
items[].rate	number	Exchange rate applied
items[].state	string	Current trade state
items[].source	string	Source entity type
items[].target	string	Target entity type
items[].createdAt	string (date-time)	Trade creation timestamp
items[].paymentId	string	Associated payment UUID

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

Error Responses

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

Code Examples

cURL

curl -X POST \
  'https://gateway.ahrvo.network/banking/ibans/v2/fx/list?limit=20&skip=0' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "sourceTargetPairs": [
      {"source": "wallet", "target": "account"}
    ],
    "state": {
      "include": ["inwardSettlementDone"]
    },
    "createdStartDate": "2024-02-20T18:30:00.000Z",
    "createdEndDate": "2024-03-22T18:29:59.999Z"
  }'

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/fx/list"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
params = {"limit": 20, "skip": 0}
data = {
    "sourceTargetPairs": [{"source": "wallet", "target": "account"}],
    "state": {"include": ["inwardSettlementDone"]},
    "createdStartDate": "2024-02-20T18:30:00.000Z",
    "createdEndDate": "2024-03-22T18:29:59.999Z"
}

response = requests.post(url, headers=headers, params=params, json=data)
result = response.json()
print(f"Total trades: {result['totalCount']}")

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/fx/list';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Content-Type': 'application/json'
};

axios.post(url, {
  sourceTargetPairs: [{ source: 'wallet', target: 'account' }],
  state: { include: ['inwardSettlementDone'] },
  createdStartDate: '2024-02-20T18:30:00.000Z',
  createdEndDate: '2024-03-22T18:29:59.999Z'
}, {
  headers,
  params: { limit: 20, skip: 0 }
})
  .then(response => {
    console.log('Total trades:', response.data.totalCount);
    console.log('Trades:', response.data.items);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Usage Notes

• Use limit and skip to paginate through large result sets
• All filter fields in the request body are optional; omit them to retrieve all trades
• Date filters use ISO 8601 format
• The totalCount field reflects the total number of matching trades regardless of pagination

Interactive API Explorer