Whitelist a wallet for a token

A security token only moves to wallets registered on its on-chain registry. Whitelisting registers an investor’s wallet there, for one token. You can whitelist on the tokens Securitize enabled for your account; Securitize gives you their contract addresses when it sets up your account. The token addresses on this page are examples.

Trading tokenized stocks with the Stocks API (Beta) needs no whitelisting call: the first trade in each stock whitelists the investor’s wallet.

POST /investors/{investorId}/wallets/whitelist                      whitelist a wallet on a token
GET  /investors/{investorId}/wallets/whitelist?tokenAddress=0x…    follow it until it is whitelisted

Before you whitelist

The investor must be ready on both sides:

Requirement	How	If not
Verified	Onboard the investor until its `status` is `verified`	`422 investor_not_verified`
Suitability verified	Send the suitability	`422 suitability_not_verified`, `details.notVerified: ["us"]`
DLT test passed, if the investor’s address is in the European Economic Area	Send the DLT test	`422 suitability_not_verified`, `details.notVerified` includes `"eu"`

The wallet does not need to be registered first: whitelisting registers it with the investor and adds it to your wallet list. EVM wallets only.

Whitelist

curl -X POST "$BASE/investors/$INVESTOR_ID/wallets/whitelist" -H "Authorization: Bearer $ACCESS_TOKEN" -H "content-type: application/json" -d '{
  "tokenAddress": "0x3f5a1b2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a",
  "walletAddress": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
}'

{ "tokenAddress": "0x3f5a1b2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a", "walletAddress": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed", "status": "processing" }

The checks run in this order, and the first one that fails answers; nothing is written:

the token is enabled for your account — else 403 token_not_enabled;
the investor is verified — else 422 investor_not_verified;
the suitability (and the DLT test, in the EEA) is verified — else 422 suitability_not_verified;
the address is not held by another investor — else 409 wallet_conflict;
the token’s issuer accepts investors from the investor’s country — else 422 country_not_allowed.

Repeating the call is safe: it answers 201 with the current status and creates nothing new. If the token’s registry already holds the wallet for this investor, the answer is whitelisted at once (see Tokens that share a registry).

Follow it until it is whitelisted

The answer is immediate; reaching the chain is not. Poll the list for the token until the status leaves processing. There are no notifications.

curl "$BASE/investors/$INVESTOR_ID/wallets/whitelist?tokenAddress=0x3f5a1b2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a" -H "Authorization: Bearer $ACCESS_TOKEN"

`status`	Meaning	What to do
`processing`	On its way to the chain	Keep polling. If it lasts more than a day, contact Securitize with the `correlationId`
`whitelisted`	Registered on-chain; the wallet can receive the token	Done
`rejected`	The address failed Securitize’s risk check	Use another wallet; repeating returns `rejected` again
`failed`	Not registered on-chain	Repeat the whitelisting once; if it still reads `failed`, contact Securitize

The list comes first with the whitelistings you requested, newest first, with the status read live: whitelisted as soon as the token’s on-chain registry holds the wallet. If any status cannot be read at that moment, the whole call answers 502 whitelist_unavailable: call again. Several tokens can read their holders from one on-chain registry. A wallet whitelisted on one of them is whitelisted on all of them, with no further call. After your own whitelistings, the list shows every other token enabled for your account whose registry already holds one of your wallets for the investor, as whitelisted:

{
  "meta": { "length": 2 },
  "data": [
    { "tokenAddress": "0x3f5a1b2c4d6e8f0a1b3c5d7e9f2a4b6c8d0e1f3a", "walletAddress": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed", "status": "whitelisted", "whitelistedAt": "2026-10-13T19:02:11.481Z" },
    { "tokenAddress": "0x7d2c4b9e1f3a5c6d8e0f1a2b3c4d5e6f7a8b9c0d", "walletAddress": "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed", "status": "whitelisted", "whitelistedAt": "2026-10-13T19:02:11.481Z" }
  ]
}

whitelistedAt on such a row is the date of your whitelisting of that wallet on a token of the same registry. It is absent when you never requested one there: the wallet is listed because the registry already holds it, for example after the investor whitelisted it elsewhere.
Only the wallets you registered or whitelisted for this investor are checked. A wallet you never sent is not listed.
?tokenAddress= narrows the list to one token, including these rows.

There is no call to remove a whitelisting. Contact Securitize if one must be removed.

In sandbox

Securitize enables a test token for your sandbox account and gives you its address. Whitelisting in sandbox registers the wallet on a test network.

Get started

Guides

Concepts

Help

API reference

Before you whitelist

Whitelist

Follow it until it is whitelisted

In sandbox