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 never show a whitelist gate. 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/transaction/detail, 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 — DEPOSIT_ORDER_NOTIFICATION arrives with status
PROCESSING and whiteListStatus init. Supply the payer details. You can also poll
GET /v1/wallet/transaction/list?whiteListStatus=init (or rejected) for the work queue.

Source address already ACTIVE — the deposit does not enter the whitelist flow and never shows a
gate; it credits as an ordinary deposit. Wait for DEPOSIT_ORDER_NOTIFICATION at SUCCESS, or poll
GET /v1/wallet/transaction/detail.

For a deposit that did go through the whitelist flow, whiteListStatus turning approved is what
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/transaction/list or GET /v1/wallet/transaction/detail.

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. DEPOSIT_ORDER_NOTIFICATION arrives with whiteListStatus init; you can also read
GET /v1/wallet/transaction/list?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. A 200 means the submission was accepted, not that
the whitelist passed: read whiteListStatus and failMessage in the response data, since the channel
can come straight back as rejected.

GET /v1/wallet/transaction/detail — track progress, including whiteListStatus.

On approval whiteListStatus becomes approved and the available balance of the receiving wallet
increases. With auto-collection enabled the order is usually still PROCESSING.

On rejection whiteListStatus comes back as rejected on DEPOSIT_ORDER_NOTIFICATION. 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 never come
back with whiteListStatus init or rejected; the only notification is DEPOSIT_ORDER_NOTIFICATION
when the order closes. Do not gate booking a repeat deposit on a whitelist signal that will never arrive.

3. One payer per sub-wallet: store a profile

Use this when a sub-wallet always receives from the same payer, but that payer may send from more than
one source address. Rather than registering every address, or answering a whitelist gate once
per new address, you store the payer once against the sub-wallet.

POST /v1/wallet/create/sub — create the sub-wallet and take its walletId.

POST /v1/wallet/deposit-whitelist/wallets/{walletId}/profile — store the payer details.

PUT /v1/wallet/deposit-whitelist/wallets/{walletId}/profile — replace them when they change. Send the
complete payer object; this is a replace, not a patch.

GET /v1/wallet/deposit-whitelist/wallets/{walletId}/profile — read them back. data is null when
nothing has been stored yet, which is a normal 200, not an error.

Nothing address-shaped goes in the body — no walletAddress, network, memo or symbol. That is the
point of this path: the payer is fixed, the address set is not. The platform pairs the stored payer with
whatever address the money actually arrived from.

What you see at deposit time:

A deposit from an address this sub-wallet has not seen before still goes through review, but nothing is
asked of you — the details are already on file, so the order never comes back with whiteListStatus
init. It moves to approved when the review passes, or rejected if it does not.

Once an address has been approved this way it behaves like any other approved address: later deposits from
it skip the whitelist flow entirely and never show a gate.

A stored profile can be replaced but not switched off. Storing or replacing one does not re-open source
addresses that are already ACTIVE, and it does not retroactively clear a deposit already sitting at init
or rejected — handle those one at a time with the path 2 submit call.

The payer field rules below apply to the profile body exactly as they do to the other two paths.

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/transaction/list, GET /v1/wallet/transaction/detail 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 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.

There is no dedicated whitelist webhook. The gate is carried on the order webhook you already consume,
as data.whiteListStatus.

Event	Gate — payer details needed	Order finished
`DEPOSIT_ORDER_NOTIFICATION`	`status` `PROCESSING` with `whiteListStatus` `init` or `rejected`	`status` `SUCCESS`, normally `whiteListStatus` `approved`
`Collect Order Updated`	`orderStatus` `PROCESSING` with `whiteListStatus` `init` or `rejected`	`orderStatus` `SUCCESS`
`WALLET_ADDRESS_UPDATED`	—	Source address moved to `ACTIVE` or `FAILED`

A deposit from an address that is already ACTIVE never shows a gate. It does not enter the whitelist
flow, so whiteListStatus arrives as approved or null and the only notification you receive is the
ordinary completion event.

On a gate, work the queue with GET /v1/wallet/transaction/list?whiteListStatus=init|rejected and call the
submit endpoint.

Whitelist approval is not announced on its own, and neither is the moment the funds become spendable. Read
creditStatus for spendability; completion is the order webhook reaching SUCCESS.

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`
Whitelist case for one deposit	GET	`/v1/wallet/deposit-whitelist/cases/{transactionId}`
Store sub-wallet payer profile	POST	`/v1/wallet/deposit-whitelist/wallets/{walletId}/profile`
Replace sub-wallet payer profile	PUT	`/v1/wallet/deposit-whitelist/wallets/{walletId}/profile`
Read sub-wallet payer profile	GET	`/v1/wallet/deposit-whitelist/wallets/{walletId}/profile`
Transaction detail	GET	`/v1/wallet/transaction/detail`

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/transaction/list`	New: `whiteListStatus` filter and response field. Replaces the pending list
GET	`/v1/wallet/transaction/detail`	New: transaction detail carrying `whiteListStatus`
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.

Reading the payer behind a gated deposit

GET /v1/wallet/deposit-whitelist/cases/{transactionId} returns the whitelist gate of one deposit in a
single call: the gate status, the receiving sub-wallet, and payerWhitelist — the payer's Travel Rule
record, including the source address, who owns it, and the address-side failMessage when it was sent
back.

Use it when you need the payer side. GET /v1/wallet/transaction/detail tells you the transaction
and its whiteListStatus; it does not carry the payer's whitelist record.

payerWhitelist is null until payer details have been submitted or matched. A deposit that never went
through the whitelist gate has no case at all and returns 10000100 — read that one with
GET /v1/wallet/transaction/detail.

Removed and withdrawn

Item	Replacement
`GET /v1/wallet/deposit-whitelist/pending-list`	`GET /v1/wallet/transaction/list` with `whiteListStatus`
`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/transaction/list?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`
`10000107`	Wallet invalid, or the sub-wallet has not been created	No — create the sub-wallet first

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#

3. One payer per sub-wallet: store a profile#

Payer fields#

Statuses#

Deposit order status#

Whitelist progress whiteListStatus#

Crediting creditStatus#

Source address status#

Webhooks#

API index#

Reading the payer behind a gated deposit#

Removed and withdrawn#

Error codes#