List OTC Deals (Specs)

Overview

The GET /banking/ibans/v2/deals endpoint retrieves a paginated collection of Over-The-Counter (OTC) deals.

It supports extensive query filters to locate deals by reference ID, status, currencies bought or sold, settlement date ranges, and volume amounts, with sorting by creation timestamp (createdDateAsc or createdDateDesc).

Resource Access

• HTTP Method: GET
• Endpoint: /banking/ibans/v2/deals
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Accept	application/json	Yes	Response payload format

Query Parameters

Parameter	Type	Required	Description	Example
limit	integer	No	Maximum number of deals to return (for pagination).	20
skip	integer	No	Number of deals to skip before returning results.	0
status	string	No	Filter by deal status: awaitingClientResponse, clientAccepted, clientRejected, expired, inwardSettlementDone, outwardSettlementDone, settled.	settled
sellCurrency	string	No	3-letter ISO code of sold currency (e.g. USD).	USD
buyCurrency	string	No	3-letter ISO code of bought currency (e.g. EUR).	EUR
referenceId	string	No	Unique external deal reference ID.	OTC-2024-001
baseCurrency	string	No	Currency in which equivalent amounts are calculated.	USD
minimumAmount	number	No	Minimum deal amount threshold.	50000
maximumAmount	number	No	Maximum deal amount threshold.	5000000
orderBy	string	No	Sort order: createdDateDesc (default) or createdDateAsc.	createdDateDesc
includeArchived	boolean	No	If true, includes archived deals (default is false).	false
createdStartDate	string	No	Filter by creation start date (ISO 8601).	2024-01-01T00:00:00Z
createdEndDate	string	No	Filter by creation end date (ISO 8601).	2024-12-31T23:59:59Z
inwardStartDate	string	No	Filter by inward settlement start date.	2024-01-01T00:00:00Z
inwardEndDate	string	No	Filter by inward settlement end date.	2024-12-31T23:59:59Z
outwardStartDate	string	No	Filter by outward settlement start date.	2024-01-01T00:00:00Z
outwardEndDate	string	No	Filter by outward settlement end date.	2024-12-31T23:59:59Z

---

Response

Success Response (200 OK)

{
  "totalCount": 1,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "referenceId": "OTC-2024-001",
      "companyId": "comp-3046",
      "status": "settled",
      "sellAmount": {
        "currency": "USD",
        "amount": 250000.00
      },
      "buyAmount": {
        "currency": "EUR",
        "amount": 230000.00
      },
      "sellToBuyFxRate": 0.92,
      "baseEquiSellAmount": {
        "currency": "USD",
        "amount": 250000.00
      },
      "inwardSettlementTime": {
        "date": "2024-01-15T12:00:00Z",
        "hint": "Same-day Fedwire",
        "actual": "2024-01-15T11:45:00Z"
      },
      "outwardSettlementTime": {
        "date": "2024-01-15T16:00:00Z",
        "hint": "SEPA Instant",
        "actual": "2024-01-15T15:30:00Z"
      },
      "expirationPeriodMins": 60,
      "inwardSettlementReference": "IN-SETTLE-8899",
      "outwardSettlementTxnId": "OUT-TXN-1122",
      "clientAcceptedDate": "2024-01-15T10:15:00Z",
      "isArchived": false,
      "createdAt": "2024-01-15T10:00:00Z",
      "modifiedAt": "2024-01-15T15:30:00Z"
    }
  ]
}

Key Response Fields

Field	Type	Description
totalCount	integer	Total number of deals matching the query filter.
items[].id	string	Unique UUID identifier for the deal.
items[].referenceId	string	Human-readable deal reference ID.
items[].status	string	Current deal status (awaitingClientResponse, clientAccepted, settled, etc.).
items[].sellAmount	object	Sell currency and principal amount.
items[].buyAmount	object	Buy currency and converted target amount.
items[].sellToBuyFxRate	number	Negotiated foreign exchange rate.
items[].inwardSettlementTime	object	Scheduled and actual timestamps for the inward sell leg.
items[].outwardSettlementTime	object	Scheduled and actual timestamps for the outward buy leg.
items[].clientAcceptedDate	string	Timestamp when counterparty confirmed the trade.

---

Error Codes

Status Code	Description	Reason
400 Bad Request	Unacceptable request	Malformed query parameters or invalid date-time format.
401 Unauthorized	Authentication required	Missing or invalid Bearer token.
500 Server Error	Server error	Internal system error.

---

Code Examples

cURL

curl -X GET "https://api.ahrvo.network/banking/ibans/v2/deals?status=settled&sellCurrency=USD&buyCurrency=EUR&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

JavaScript (Fetch)

const params = new URLSearchParams({
  status: 'settled',
  sellCurrency: 'USD',
  buyCurrency: 'EUR',
  limit: '10'
});

const response = await fetch(`https://api.ahrvo.network/banking/ibans/v2/deals?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(`Found ${data.totalCount} deals:`);
data.items.forEach(deal => {
  console.log(`${deal.referenceId} | Sold ${deal.sellAmount.amount} ${deal.sellAmount.currency} -> Bought ${deal.buyAmount.amount} ${deal.buyAmount.currency} | Status: ${deal.status}`);
});

Python (requests)

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/deals"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
params = {
    "status": "settled",
    "sellCurrency": "USD",
    "buyCurrency": "EUR",
    "limit": 10
}

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

print(f"Total deals: {data.get('totalCount')}")
for deal in data.get("items", []):
    print(f"Deal {deal['referenceId']}: Rate {deal['sellToBuyFxRate']} | Status: {deal['status']}")

---

Interactive API Console

Test the endpoint directly in your browser: