Skip to main content
Every movement can be followed two ways: poll the read APIs, or subscribe to webhooks for event-driven updates.

​
Read APIs

Transfers and withdrawals use different status vocabularies. Transfers move through QUEUED, IN_PROGRESS, COMPLETED, and FAILED. Withdrawals move through NEEDS APPROVAL, INPROGRESS, SUCCESS, FAILURE, REJECTED, and EXPIRED. See Transfer and Withdraw for the full lifecycles.

​
Webhooks

Subscribe to webhooks to receive updates as operations and transactions change state, instead of polling. For digital assets, delivery waits on on-chain confirmation, typically around two confirmations; USD events fire once the transfer or wire settles. See Webhooks.

​
Correlate a webhook to its transaction

Webhook events are lightweight—each carries the identifier of the affected record, not its full detail. On receipt, fetch the record and inspect it:
1

Receive the event

A deposit.*, transfer.*, or withdrawal.* event arrives with the transaction identifier. See Webhooks for the event catalog and payload fields.
2

Fetch the full record

Look it up with the matching read API: transfers via GET /v2/transfers/{transferId}; deposits and withdrawals via GET /v2/transactions/{id}.
3

Interpret the movement

Read transactionType (DEPOSIT, WITHDRAW, or TRANSFER) together with sourceAddresses and destinationAddresses to classify what happened and where the funds moved.

​
Tell an internal deposit from an external one

An internal transfer between your own wallets lands as a DEPOSIT on the destination wallet, the same shape as a deposit from an outside sender. To distinguish them, compare the deposit’s sourceAddresses against the addresses you manage (from GET /v2/wallets and the addresses API): a match means the funds came from one of your own wallets; otherwise the sender is external.
The transfers API identifies records by transferId, which isn’t always a UUID. Match on the value exactly as returned rather than assuming a format.

​
Idempotency and retries

Provide an idempotentId per request so an interrupted call can be retried safely without double-spending. For status codes, rate limits, and cursor pagination, see Handling errors, retries, and pagination.