Query a Deal

Retrieve the full details of a specific deal by its deal ID. The response includes all available deal information, with certain fields conditionally returned based on the deal type and current status. Use this endpoint to track deal progress, check settlement status, or retrieve margin details for forward deals.
Request Parameters
idstring
required
Deal ID to query. Must be a valid deal created by the current account.
Response Parameters
resultResult
See Result.
idstring
Unique deal identifier assigned by WorldFirst.
requestIdstring
Idempotency ID supplied when the deal was created.
dealTypestring
Deal type, determined by the quote used.

Valid Values:

SPOT — Standard spot deal. Settles automatically.
UNFUNDED_SPOT — Unfunded spot deal. Requires explicit settlement.
FORWARD — Forward deal. Requires margin and settlement period.
quoteQuote
Quote information associated with this deal.
Show child parametersShow child parameters
sellAmountAmount
Amount being sold in the deal. See Data Types for the Amount structure.
buyAmountAmount
Amount being bought in the deal. See Data Types for the Amount structure.
creditSupportCreditSupport
Margin and credit information. Returned only when dealType is FORWARD.
Show child parametersShow child parameters
settlementPeriodSettlementPeriod
Settlement period information. Returned when dealType is UNFUNDED_SPOT or FORWARD.
Show child parametersShow child parameters
unSettleBuyAmountAmount
Unsettled buy amount. Returned when dealType is UNFUNDED_SPOT or FORWARD and status is PROCESSING or CANCELLED. See Data Types for the Amount structure.
unSettleSellAmountAmount
Unsettled sell amount. Returned when dealType is UNFUNDED_SPOT or FORWARD and status is PROCESSING or CANCELLED. See Data Types for the Amount structure.
cancelFeeAmountAmount
Cancellation fee amount. Returned when status is CANCELLED. See Data Types for the Amount structure.
statusstring
Current deal status. See DealStatus.
createdAtdatetime
Timestamp when the deal was created. ISO 8601 format.
settledAtdatetime
Timestamp when the deal was settled. ISO 8601 format. Returned only when the deal is settled.
cancelledAtdatetime
Timestamp when the deal was cancelled. ISO 8601 format. Returned only when the deal is cancelled.
failedAtdatetime
Timestamp when the deal failed. ISO 8601 format. Returned only when status is FAILED.
failureCodestring
Failure code describing the reason for failure. Returned only when status is FAILED.
failureMessagestring
A plain-text description of the failure reason. Returned only when status is FAILED.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSsuccessN/A
FUND_ORDER_NOT_EXISTFFund order does not existVerify the deal ID is correct and belongs to the current account.
Definition
POST /api/open/v1/fx/deals/query
Request
{
"id": "DEAL20260402001"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "DEAL20260402001",
"requestId": "REQ20260402001",
"dealType": "UNFUNDED_SPOT",
"quote": {
  "quoteId": "QT202604021208001",
  "currencyPair": "GBP/EUR",
  "clientRate": 1.162,
  "effectiveAt": "2026-04-02T04:09:30Z",
  "expiresAt": "2026-04-02T04:10:30Z"
},
"sellAmount": {
  "currency": "GBP",
  "value": 5000
},
"buyAmount": {
  "currency": "EUR",
  "value": 5810
},
"settlementPeriod": {
  "endDate": "2026-04-04"
},
"status": "SUCCESS",
"createdAt": "2026-04-02T04:09:35Z",
"settledAt": "2026-04-02T06:09:35Z"
}