Wallet · Deposit whitelist

A payer sending crypto into your wallet must have their source address registered and their payer details
reviewed before the money becomes usable. Until that clears, the deposit order is PROCESSING and the
funds sit in the unavailable balance of the receiving wallet — not withdrawable, not convertible.

Once the review passes, the funds move into the available balance of that receiving wallet. After an
address has been approved, later deposits from the same address skip the whitelist flow entirely:
they credit as ordinary deposits and emit no DEPOSIT_WHITELIST_* webhook at all — neither
DEPOSIT_WHITELIST_REQUIRED nor DEPOSIT_WHITELIST_CREDITED. You are notified by the ordinary
DEPOSIT_ORDER_NOTIFICATION when the deposit completes.

If auto-collection is enabled on the wallet, the funds are then swept to the main account by the existing
transfer flow. The deposit order stays PROCESSING until that sweep finishes, and becomes SUCCESS
afterwards. Without auto-collection the order becomes SUCCESS as soon as the review passes.

Authentication is the same as every other Wallet endpoint. Send an Idempotency-Key header on writes. All
amounts are strings.

The one rule that matters

SUCCESS is not the signal that funds are spendable.

A deposit order can be PROCESSING with the money already available (auto-collection still running), and it
can be PROCESSING with the money locked (review not finished). To know whether funds are usable, read
creditStatus from GET /v1/wallet/transactions/{transactionId}, or read the available balance from
GET /v1/wallet/asset-balance.

Order `status`	`whiteListStatus`	`creditStatus`	Money spendable?
`PROCESSING`	`init`	`PENDING`	No — submit payer details
`PROCESSING`	`pending`	`PENDING`	No — under review
`PROCESSING`	`rejected`	`PENDING`	No — resubmit
`PROCESSING`	`approved`	`CREDITED`	Yes — sweep still running
`SUCCESS`	`approved`	`CREDITED`	Yes

Which path applies to you

1. Address known: register it first

Use this when you already know which address the payer will send from.

GET /v1/wallet/deposit-whitelist/options — fetch the VASP / provider list. That is the endpoint's
only purpose.

POST /v1/wallet/deposit-whitelist/addresses — submit the address and the payer details. Send the
country as an ISO 3166-1 alpha-2 two-letter code (SG). There is no country enum to look up.

GET /v1/wallet/deposit-whitelist/addresses/{id} — check the outcome:

PROCESSING — under review

ACTIVE — approved

FAILED — rejected. Call POST /v1/wallet/deposit-whitelist/addresses/{id}/disable, then register a
new record.

A record cannot be edited after submission. Correcting anything means disable + register again.

Then the payer sends to your deposit address (GET /v1/wallet/deposit-address):

After on-chain confirmation the order is PROCESSING and the funds are in the unavailable balance of the
receiving wallet.

Source address not whitelisted yet — you receive DEPOSIT_WHITELIST_REQUIRED. Supply the payer
details. You can also poll GET /v1/wallet/history?whiteListStatus=init (or rejected) for the work
queue.

Source address already ACTIVE — the deposit does not enter the whitelist flow. No
DEPOSIT_WHITELIST_* webhook is sent, and the deposit credits as an ordinary one. Wait for
DEPOSIT_ORDER_NOTIFICATION, or poll GET /v1/wallet/transactions/{transactionId}.

For a deposit that did go through the whitelist flow, DEPOSIT_WHITELIST_CREDITED tells you the
available balance of that receiving wallet in GET /v1/wallet/asset-balance has increased. With
auto-collection enabled the order is usually still PROCESSING while the funds are swept to the main
account.

When the deposit is fully complete — including auto-collection where enabled — the order becomes
SUCCESS and you receive DEPOSIT_ORDER_NOTIFICATION, whose payload now carries whiteListStatus. You
can also confirm with GET /v1/wallet/history or GET /v1/wallet/transactions/{transactionId}.

2. Address unknown: submit after the deposit arrives

After the payer sends, the order is PROCESSING and the funds are in the unavailable balance of the
receiving wallet. You receive DEPOSIT_WHITELIST_REQUIRED; you can also read
GET /v1/wallet/history?whiteListStatus=init for the deposits awaiting details.

Optionally call GET /v1/wallet/deposit-whitelist/options for the provider list.

POST /v1/wallet/deposit-whitelist/transactions/{transactionId}/submit — submit the payer details. Do
not send the source address, network, memo or transaction hash; those come from the on-chain
transaction. Country goes in as a two-letter code.

GET /v1/wallet/transactions/{transactionId} — track progress, including whiteListStatus.

On approval you receive DEPOSIT_WHITELIST_CREDITED and the available balance of the receiving
wallet increases. With auto-collection enabled the order is usually still PROCESSING.

On rejection you receive DEPOSIT_WHITELIST_FAILED with whiteListStatus rejected. The order stays
PROCESSING and the funds stay in the unavailable balance. Fix what failMessage reports and submit
again.

When the deposit is fully complete the order becomes SUCCESS and you receive
DEPOSIT_ORDER_NOTIFICATION.

Once an address is approved, later deposits from it never enter the whitelist flow. They emit no
DEPOSIT_WHITELIST_* webhook whatsoever — not REQUIRED, not CREDITED. The only notification is
DEPOSIT_ORDER_NOTIFICATION when the order closes. Do not gate booking a repeat deposit on a whitelist
event that will never arrive.

Payer fields

`correspondentType`	Mandatory	Must NOT be sent
`ENTITY`	`fullName`, `countryCode`, `companyAddress`	`firstName`, `lastName`, `birthday`, `residentialAddress`
`INDIVIDUAL`	`firstName`, `lastName`, `birthday` (`yyyy-MM-dd`), `countryCode`, `residentialAddress`	`fullName`

`walletType`	Also mandatory
`VASP`	`provider` — must be a `name` from `GET /v1/wallet/deposit-whitelist/options`
`OTHERS`	`othersPleaseSpecify`, max 255 characters
`SELF_HOSTED`	—

Other constraints: walletLabel max 50 characters; symbol may be empty when addressType is UNIVERSAL;
memo only where the network uses one.

countryCode is an ISO 3166-1 alpha-2 code such as SG. The platform converts it to whatever country
name the downstream channel requires. countryInfo was withdrawn — do not send it. An unrecognised code
or an unknown provider returns 10000103.

Statuses

Deposit order `status`

Appears in GET /v1/wallet/history, GET /v1/wallet/transactions/{transactionId} and the deposit webhooks.

Value	Meaning
`PROCESSING`	Deposit in progress — awaiting whitelist, under review, or credited but not yet swept
`SUCCESS`	Deposit fully complete, including auto-collection where enabled
`FAIL`	Deposit failed

Do not read this field to decide whether the money is spendable. Read creditStatus, or
GET /v1/wallet/asset-balance.

Whitelist progress `whiteListStatus`

Appears in order queries — history, transaction detail, collection order status — and in
DEPOSIT_ORDER_NOTIFICATION, DEPOSIT_WHITELIST_* and Collect Order Updated. Values are lowercase.

Value	Meaning
`init`	Travel Rule details not submitted yet
`pending`	Submitted, under review
`approved`	Passed — the gate is cleared. The order may still be `PROCESSING`
`rejected`	Rejected, resubmit required

submitStatus was withdrawn. Use whiteListStatus everywhere.

Crediting `creditStatus`

Appears in the transaction detail and related endpoints.

Value	Meaning
`PENDING`	Not yet in the available balance of the receiving wallet
`CREDITED`	In the available balance of the receiving wallet. The order may still be `PROCESSING`
`BLOCKED`	Could not be credited — contact support

Source address `status`

Appears on the address endpoints.

Value	Meaning
`PROCESSING`	Submitted, under review
`ACTIVE`	Approved
`FAILED`	Rejected

Webhooks

Configured exactly like the existing Stable webhooks. Deduplicate on eventId.

Event	Meaning	Order `status`	Notes
`WALLET_ADDRESS_UPDATED`	Source address changed state	—
`DEPOSIT_WHITELIST_REQUIRED`	Payer details needed	`PROCESSING`	Sent only while the source address is not yet whitelisted
`DEPOSIT_WHITELIST_FAILED`	Review rejected, resubmit; funds still unavailable	`PROCESSING`	Payload carries `whiteListStatus` `rejected`
`DEPOSIT_WHITELIST_CREDITED`	Review passed for this deposit; funds now in the available balance of the receiving wallet	usually `PROCESSING`; can be `SUCCESS` without auto-collection	Only for deposits that went through the whitelist flow
`DEPOSIT_ORDER_NOTIFICATION`	Deposit fully complete (existing event)	`SUCCESS`	New: carries `whiteListStatus`, normally `approved`
`Collect Order Updated`	Collection / payment-link order updated (existing event)	as today	New: carries `whiteListStatus`

A deposit from an address that is already ACTIVE emits none of the three DEPOSIT_WHITELIST_* events.
It never enters the whitelist flow, so there is nothing for them to report; the ordinary
DEPOSIT_ORDER_NOTIFICATION is the only notification you receive.

The three DEPOSIT_WHITELIST_* events are delivered by a single entry — Deposit Whitelist Notification —
under API Reference · Webhooks. Branch on eventType; the envelope and data shape are identical, and only
failMessage (on FAILED) and creditTime (on CREDITED) are conditional.

After DEPOSIT_WHITELIST_REQUIRED or DEPOSIT_WHITELIST_FAILED, work the queue with
GET /v1/wallet/history?whiteListStatus=init|rejected and call the submit endpoint. No
DEPOSIT_ORDER_NOTIFICATION is emitted during on-chain confirmation.

Only DEPOSIT_ORDER_NOTIFICATION is terminal — treat DEPOSIT_WHITELIST_CREDITED as "the money is
spendable now", not as "the deposit is finished".

API index

Success returns HTTP 200 and business status 200:

{
  "status": 200,
  "code": null,
  "msg": "OK",
  "traceId": "…",
  "data": {}
}

Business failures return status 500 with a code from the table at the bottom of this page.

Scenario	Method	Path
Provider list	GET	`/v1/wallet/deposit-whitelist/options`
Register source address	POST	`/v1/wallet/deposit-whitelist/addresses`
List source addresses	GET	`/v1/wallet/deposit-whitelist/addresses`
Source address detail	GET	`/v1/wallet/deposit-whitelist/addresses/{id}`
Disable source address	POST	`/v1/wallet/deposit-whitelist/addresses/{id}/disable`
Submit for a received deposit	POST	`/v1/wallet/deposit-whitelist/transactions/{transactionId}/submit`
Transaction detail	GET	`/v1/wallet/transactions/{transactionId}`

APIs you are already using, and what changed:

Method	Path	Purpose / change
GET	`/v1/wallet/deposit-address`	Deposit address
POST	`/v1/wallet/create/sub`	Create a sub-wallet
GET	`/v1/wallet/asset-balance`	Available / unavailable balance
GET	`/v1/wallet/history`	New: `whiteListStatus` filter and response field. Replaces the pending list
GET	`/v1/wallet/transactions/{transactionId}`	New: transaction detail carrying `whiteListStatus`. Replaces the case endpoint
GET	`/v2/stable/collect/order-status`	New: `whiteListStatus` in the response
Webhook	`DEPOSIT_ORDER_NOTIFICATION`	New: `whiteListStatus`
Webhook	`Collect Order Updated`	New: `whiteListStatus`

Withdrawal whitelisting is unchanged — keep using POST /v1/wallet/add-withdraw-whitelist. This page is
about incoming funds only.

Removed and withdrawn

Item	Replacement
`GET /v1/wallet/deposit-whitelist/pending-list`	`GET /v1/wallet/history` with `whiteListStatus`
`GET /v1/wallet/deposit-whitelist/cases/{transactionId}`	`GET /v1/wallet/transactions/{transactionId}`
`submitStatus`	`whiteListStatus`, with lowercase `init` / `pending` / `approved` / `rejected`
Country enum in `/options`	Send `countryCode` as an ISO 3166-1 alpha-2 code
`countryInfo` in requests	Not needed — derived from `countryCode` server-side

Error codes

Same convention as the rest of Wallet: code is an 8-digit string from WalletErrorCode.

`code`	Meaning	Safe to retry unchanged?
`10000100`	Transaction not found, or not owned by the caller	No — re-read `GET /v1/wallet/history?whiteListStatus=init`
`10000101`	Review already completed for this deposit	No — nothing left to do
`10000102`	Payer details incomplete	No — add the missing fields
`10000103`	Field value not accepted, including an invalid `countryCode` or unknown `provider`	No — use an ISO 3166-1 alpha-2 code and a `provider` from `/options`
`10000104`	Cannot submit right now	Yes, later — poll the status. Do not edit the details and retry immediately
`10000105`	Duplicate request	No — read the original result
`10000106`	Source address supplied or changed for a received deposit	No — drop `walletAddress` / `network` / `memo` / `symbol` / `txHash`

Wallet · Deposit whitelist

The one rule that matters#

Which path applies to you#

1. Address known: register it first#

2. Address unknown: submit after the deposit arrives#

Payer fields#

Statuses#

Deposit order status#

Whitelist progress whiteListStatus#

Crediting creditStatus#

Source address status#

Webhooks#

API index#

Removed and withdrawn#

Error codes#