Blockchain Callbacks

StraitsX sends callbacks to your registered URL when blockchain/stablecoin transactions change status. These events cover on-chain movements of XSGD and XUSD tokens.

When these callbacks fire

This page covers the following events:

Event	Description
`stablecoinWithdrawalStatusUpdated`	A withdrawal (sending tokens from your StraitsX account to an external address) is submitted or confirmed on-chain.
`stablecoinDepositStatusUpdated`	A deposit (receiving tokens from an external address into your StraitsX account) is detected or confirmed on-chain.

Status values

Both events share the same status values:

Status	Meaning
`pending`	Transaction submitted/detected, awaiting on-chain confirmation
`completed`	Transaction confirmed on-chain
`failed`	Transaction could not be processed

Supported networks and tokens

Token	Networks
XSGD	Ethereum, Polygon, Avalanche, Arbitrum, Hedera, Ripple, Zilliqa, Solana
XUSD	Ethereum, Bnbsmart (BSC), Solana

Payload structure

Both events share the same payload structure. The only differences are:

Field	Withdrawal	Deposit
`data.type`	`stablecoin_withdraw_contract`	`stablecoin_deposit_contract`
`blocked_reasons`	Not present	Present (array)
`transaction_hash` when pending	May be `pending` (not yet broadcast)	Always the actual hash (already detected on-chain)

{
  "data": {
    "attributes": {
      "amount": "1.0",
      "blockchain": "XSGD_ERC20",
      "created_at": "2026-01-23T11:07:45.693Z",
      "idempotency_id": "e8b7c6d5a4f3e2d1c0b9a8f7e6d5c4b3",
      "network": "Ethereum",
      "network_fees": "0.0",
      "status": "completed",
      "token": "xsgd",
      "total_amount": "1.0",
      "transaction_hash": "0x7f3e8b2a1c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e",
      "transaction_source": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "id": "contract_0d151e28146d42aabf9115ee3f6c6926",
    "type": "stablecoin_deposit_contract"
  }
}

{
  "data": {
    "attributes": {
      "amount": "2.0",
      "blockchain": "XSGD_MATIC",
      "created_at": "2024-06-11T04:48:39.912Z",
      "idempotency_id": "testing",
      "network": "Polygon",
      "network_fees": "0.02",
      "status": "completed",
      "token": "xsgd",
      "total_amount": "2.02",
      "transaction_hash": "0x658043f80b1684cce02a0f4c0ed5449589eef495492bae5a849e47e80c46dd4d",
      "transaction_source": "0x4fd0f684dcf7c6c862114db8cebfe8bf6bb175c3"
    },
    "id": "contract_7afa75105cad43579f9589ebe30b6784",
    "type": "stablecoin_withdraw_contract"
  }
}

Field reference

Field	Scope	Type	Description
`data.id`	Common fields	String	Unique contract ID.
`data.type`	Common fields	String	`stablecoin_withdraw_contract` or `stablecoin_deposit_contract`
`data.attributes.transaction_hash`	Common fields	String	Blockchain transaction hash. For withdrawals, may be `pending` if not yet broadcast.
`data.attributes.amount`	Common fields	String	Token amount (sent for withdrawals, received for deposits).
`data.attributes.network_fees`	Common fields	String	Network/gas fees. Typically "0.0" for deposits (sender pays gas).
`data.attributes.total_amount`	Common fields	String	Total amount. For withdrawals: amount + network fees deducted. For deposits: amount credited.
`data.attributes.transaction_source`	Common fields	String	For deposits: the sender's blockchain address. For withdrawals: the destination blockchain address (where tokens are sent to).
`data.attributes.status`	Common fields	String	Contract status.
`data.attributes.idempotency_id`	Common fields	String	Your idempotency key (withdrawals) or external reference ID (deposits).
`data.attributes.network`	Common fields	String	Blockchain network name.
`data.attributes.token`	Common fields	String	Token/currency.
`data.attributes.blockchain`	Common fields	String	Token standard identifier (e.g., `XSGD_ERC20`, `XSGD_AVAX`, `XUSD_SPL`).
`data.attributes.created_at`	Common fields	String	ISO 8601 timestamp.
`data.attributes.blocked_reasons`	Deposit only	Array of objects	Compliance reasons the deposit is held for review. Each object contains a code field. Empty array if not blocked. Example: `[{"code": "travel_rule_check"}]`

`blockchain` value reference

Token	Network	`blockchain` value
XSGD	Ethereum	XSGD_ERC20
XSGD	Polygon	XSGD_MATIC
XSGD	Avalanche	XSGD_AVAX
XSGD	Arbitrum	XSGD_ARB
XSGD	Hedera	XSGD_HTS
XSGD	Ripple	XSGD_XRP
XSGD	Zilliqa	XSGD_ZRC2
XSGD	Solana	XSGD_SPL
XUSD	Ethereum	XUSD_ERC20
XUSD	BNB Smart Chain	XUSD_BEP20
XUSD	Solana	XUSD_SPL

Updated 2 months ago

Did this page help you?