Create a Deal

Execute an FX deal using a valid quote obtained from the Quote API. The deal type (SPOT, UNFUNDED_SPOT, or FORWARD) is determined by the quote used. SPOT deals settle automatically, while UNFUNDED_SPOT and FORWARD deals require explicit settlement via the Settlement API. Forward deals additionally require margin management.
Request Parameters
requestIdstring
required
Idempotency ID used to prevent duplicate submissions. Must be unique per deal creation request.
quoteIdstring
required
Quote ID obtained from the Quote API. The quote must be valid and not expired at the time of deal creation.
Response Parameters
resultResult
See Result.
idstring
Unique deal identifier assigned by WorldFirst.
requestIdstring
Echoes the requestId submitted in the request.
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 for FORWARD deals.
Show child parametersShow child parameters
settlementPeriodSettlementPeriod
Settlement period information. Returned for UNFUNDED_SPOT and FORWARD deals.
Show child parametersShow child parameters
unSettleBuyAmountAmount
Unsettled buy amount. Returned for UNFUNDED_SPOT and FORWARD deals when status is PROCESSING or CANCELLED. See Data Types for the Amount structure.
unSettleSellAmountAmount
Unsettled sell amount. Returned for UNFUNDED_SPOT and FORWARD deals when 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
FX_QUOTE_EXPIREDFFX quote has expiredObtain a new quote from the Quote API and retry.
FX_FORWARD_LEI_CHECK_FAILEDFForward LEI check failedEnsure a valid Legal Entity Identifier (LEI) is registered for forward deals.
FX_DEAL_INITIAL_MARGIN_FREEZE_FAILEDFInitial margin freeze failedEnsure sufficient funds are available for the margin freeze and retry.
REPEAT_REQ_INCONSISTENTFInconsistent parameters for repeated requests.Recheck the request parameters.
Definition
POST /api/open/v1/fx/deals/create
Request
{
"requestId": "REQ20260402001",
"quoteId": "QT202604021208001"
}
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": "PROCESSING",
"createdAt": "2026-04-02T04:09:35Z"
}