OTC Deals

Retrieve OTC deals for reconciliation, operations review, or customer support by filtering the deal list and paging through the results.

Before you start

Complete these steps first:

Authenticate with Verto and include the JWT in the Authorization header. See Authentication.
Choose the filters your workflow needs, such as deal status, currency pair, reference ID, date range, or amount range.
Set a pagination strategy using limit and skip so your integration can retrieve the full result set.
Decide whether your workflow needs active deals only or archived deals as well.

When to use OTC deals

Use the OTC Deals API when you need to retrieve OTC deal records for operational workflows.

Common use cases include:

listing OTC deals created for a company
finding a deal by referenceId
reviewing deals by status, such as clientAccepted, expired, or settled
filtering deals by sell currency, buy currency, settlement date, creation date, or amount
including archived deals when you need a historical operational view

1. Retrieve the first page of deals

Call GET /deals with a limit and skip value. Use limit to control how many deals are returned and skip to choose where the result page starts.

curl --request GET 'https://api-otc-sandbox.vertofx.com/deals?limit=50&skip=0' \
  --header 'Authorization: Bearer <JWT>'

A successful response returns the total number of matching deals and an items array containing the current page of deal records.

{
  "totalCount": 1,
  "items": [
    {
      "id": "9f1f6c22-2d7d-4e71-a1a5-3a1d7f0c8a10",
      "createdAt": "2026-05-19T13:54:47.584Z",
      "modifiedAt": "2026-05-19T14:02:10.000Z",
      "companyId": "9134",
      "sellAmount": {
        "currency": "USD",
        "amount": 10000
      },
      "buyAmount": {
        "currency": "GBP",
        "amount": 7850
      },
      "sellToBuyFxRate": 0.785,
      "referenceId": "OTC-REF-001",
      "status": "clientAccepted",
      "isArchived": false,
      "inwardSettlementTime": {
        "date": "2026-05-20T10:00:00.000Z"
      },
      "outwardSettlementTime": {
        "date": "2026-05-20T14:00:00.000Z"
      }
    }
  ]
}

2. Filter deals for your workflow

Add query parameters to narrow the result set. You can combine filters to retrieve the exact deal records your workflow needs.

For example, this request returns client-accepted USD to GBP deals and sorts them by newest creation date first:

curl --request GET 'https://api-otc-sandbox.vertofx.com/deals?limit=50&skip=0&sellCurrency=USD&buyCurrency=GBP&status=clientAccepted&orderBy=createdDateDesc' \
  --header 'Authorization: Bearer <JWT>'

Common filters

Filter	Type	Use it to
`includeArchived`	boolean	Include archived deals. By default, archived deals are excluded.
`sellCurrency`	string	Return deals where this is the currency being sold.
`buyCurrency`	string	Return deals where this is the currency being bought.
`referenceId`	string	Return deals matching a specific reference ID.
`status`	string	Return deals with a specific deal status.
`createdStartDate`	date-time	Return deals created on or after this value.
`createdEndDate`	date-time	Return deals created on or before this value.
`minimumAmount`	number	Return deals with an amount greater than or equal to this value.
`maximumAmount`	number	Return deals with an amount less than or equal to this value.
`baseCurrency`	string	Return equivalent amounts in the specified currency.
`orderBy`	string	Sort by creation date. Supported values are `createdDateAsc` and `createdDateDesc`. Defaults to `createdDateDesc`.

For the complete parameter list, see the GET /deals API reference.

3. Page through all matching deals

Use skip to move through each page of results. Keep the same limit and increase skip by the number of records already requested.

To retrieve the first 50 deals, set:

limit=50&skip=0

To retrieve the next page, set:

limit=50&skip=50

Continue requesting pages until your integration has processed the matching records returned by the API.

4. Reconcile deal status

Store id, referenceId, status, and settlement timestamps in your internal system. These fields help you match OTC deal state changes with your own records.

The status filter accepts these values:

Status	Meaning
`awaitingClientResponse`	The deal is waiting for the client to accept or reject it.
`clientAccepted`	The client accepted the deal.
`clientRejected`	The client rejected the deal.
`expired`	The deal expired before acceptance.
`inwardSettlementDone`	The inward settlement has been completed.
`outwardSettlementDone`	The outward settlement has been completed.
`settled`	The deal has completed the settlement flow.

Use createdStartDate and createdEndDate when reconciling recently created deals. Use inward and outward settlement date filters when reconciling settlement activity rather than deal creation.

Troubleshooting

Issue	What to check
The API returns `400`	Check query parameter names, date-time formatting, currency codes, status values, and pagination parameters.
Expected deals are missing	Confirm whether archived deals should be included and set `includeArchived` if needed.
Pagination returns repeated records	Increase `skip` by the number of records already requested while keeping `limit` consistent.
Date filters return unexpected records	Use ISO 8601 date-time values, such as `2026-05-19T13:54:47.584Z`.

Next steps

Review the full GET /deals API reference.
Set up authentication in Authentication.
Review retry guidance in Errors and Retries.