Swap Callback

StraitsX sends a swapUpdated callback to your registered URL when a swap transaction status changes. Swaps are currency conversions between stablecoins (e.g., XSGD ↔ XUSD).

When this callback fires

Trigger	Description
Swap executed	A swap quote is executed and enters processing
Swap completed	Currency conversion is successfully settled
Swap failed	Swap could not be completed

Status values

Status	Meaning
`pending`	Swap is being processed
`completed`	Conversion settled — target currency credited to your account
`failed`	Swap could not be completed

Payload structure

{
  "data": {
    "id": "contract_f6a7b8c9-d0e1-2345-f012-456789012345",
    "type": "swapTransaction",
    "attributes": {
      "idempotencyId": "swap-unique-key-001",
      "quoteId": "quote-uuid-abc123",
      "status": "completed",
      "swapPair": "XSGDXUSD",
      "sourceCurrency": "XSGD",
      "targetCurrency": "XUSD",
      "fixedSide": "source",
      "totalSourceCurrencyAmount": "1350.0",
      "sourceCurrencyAmount": "1350.0",
      "targetCurrencyAmount": "1000.0",
      "rate": "0.7407",
      "fees": [
        {
          "type": "TransactionFee",
          "amount": "0.0",
          "currency": "XSGD"
        }
      ],
      "createdAt": "2026-05-11T10:00:00+08:00",
      "updatedAt": "2026-05-11T10:00:05+08:00",
      "customerProfileId": null
    }
  }
}

Field Reference

Top-level fields

Field	Type	Description
`data.id`	String	Unique swap contract ID.
`data.type`	String	Always `swapTransaction`.
`data.attributes.idempotencyId`	String	Your idempotency key from the swap execution request.
`data.attributes.quoteId`	String	The quote ID that was executed.
`data.attributes.status`	String	Swap contract status.
`data.attributes.swapPair`	String	Currency pair (e.g., `XSGDXUSD`, `XUSDXSGD`).
`data.attributes.sourceCurrency`	String	Source currency code.
`data.attributes.targetCurrency`	String	Target currency code.
`data.attributes.fixedSide`	String	Which side was fixed when quoting: `source` or `target`.
`data.attributes.totalSourceCurrencyAmount`	String	Total source amount deducted (including fees).
`data.attributes.sourceCurrencyAmount`	String	Source amount (excluding fees).
`data.attributes.targetCurrencyAmount`	String	Target amount credited.
`data.attributes.rate`	String	Exchange rate applied.
`data.attributes.fees`	Array of objects	Fee breakdown. Empty array if no fees.
`data.attributes.createdAt`	String	ISO 8601 timestamp when the swap was created.
`data.attributes.updatedAt`	String	ISO 8601 timestamp when the status last changed.
`data.attributes.customerProfileId`	String	Customer profile ID if the swap was executed on behalf of a customer. `null` for direct swaps.

`fees[]` items

Field	Type	Description
`type`	String	Fee type (e.g., `TransactionFee`).
`amount`	String	Fee amount.
`currency`	String	Currency the fee is charged in.

Understanding `fixedSide`

The fixedSide field indicates which amount was locked when the quote was created:

`fixedSide`	Meaning	Example
`source`	You specified how much to sell	"I want to sell exactly 1350 XSGD" → receive variable XUSD
`target`	You specified how much to receive	"I want to receive exactly 1000 XUSD" → sell variable XSGD

This affects how you reconcile: if fixedSide is source, the sourceCurrencyAmount is your known input and targetCurrencyAmount is the computed output (and vice versa).

Updated 2 months ago

Did this page help you?