Prepare an investor to trade

An investor can trade once three things are true. Securitize checks the first two on every priced request and every order, so an investor whose status changes stops trading at once, with nothing for you to do.

Requirement	How	If not
The investor is verified	Onboard an individual or a company with the SecId API, until its `status` is `verified`	`403 UNAUTHORIZED_INVESTOR`
Their suitability is verified, and in the European Economic Area their DLT test is passed	Send the suitability and the DLT test with the SecId API	`403 UNAUTHORIZED_INVESTOR`
Their wallet on the stock’s chain is linked, with their signature	Below	Orders cannot be prepared

Onboarding happens once per investor. After that, each order is a handful of calls: see Trade a stock.

Rather not build onboarding? If your investors trade the stock token on chain rather than through this API, send them to hosted onboarding: Securitize’s page verifies them, takes their investment profile and readies their wallet, then returns them to your site. This API’s calls take an investorId, which hosted onboarding does not return.

1. Onboard and verify the investor

Onboard the investor with the SecId API, with the identity data and documents you already hold: Securitize relies on your verification, and runs its own sanctions and PEP screening on top. Poll the investor’s status until it is verified (Statuses). Store the investorId the SecId API returns. It is the id every Stocks API call takes. How quickly an investor reaches verified depends on your agreement with Securitize, not on the API: on submission, or once screening answers.

2. Send the suitability, and the DLT test in the EEA

Securitize Markets has to form its own view of whether trading suits each investor, whoever verified their identity. Send the investor’s suitability with the SecId API, and for an investor whose address is in the European Economic Area, their DLT test. Both are described in Suitability and the DLT test. An investor whose suitability is not verified gets UNAUTHORIZED_INVESTOR on every price and order.

3. Link the trading wallet

The investor trades from one wallet on each chain, linked to them with their own signature: that signature proves they control it, and is kept as the record of their agreement to the Securitize wallet terms. Every order on that chain is built for this wallet. blockchainType names the chain: see Chains.

POST /wallets/{address}/verification-status   can it be linked?
POST /wallets/{address}/prepare-verification   → agreementMessage
     the investor's wallet signs it            no Securitize call
POST /wallets                                  link it, with the signature

Check first. This answers without asking anything of the investor:

curl -X POST "$BASE/wallets/7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV/verification-status" \
  -H "x-api-key: $STOCKS_API_KEY" -H "content-type: application/json" \
  -d '{ "investorId": "6b31c0e9a4f2d17e85c3b904", "blockchainType": "solana" }'

{ "canVerify": true, "alreadyVerified": false }

Answer	What to do
`canVerify: true`	Link it: the steps below
`alreadyVerified: true`	Already linked to this investor. Go to trading
`reason: WALLET_ALREADY_IN_USE`	The address is linked to another investor. Ask for another wallet
`reason: MAX_WALLETS_REACHED`	The investor holds the most wallets allowed. Contact Securitize

Get the message, and have it signed verbatim.

curl -X POST "$BASE/wallets/7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV/prepare-verification" \
  -H "x-api-key: $STOCKS_API_KEY" -H "content-type: application/json" \
  -d '{ "investorId": "6b31c0e9a4f2d17e85c3b904", "blockchainType": "solana" }'

Relay agreementMessage to your frontend and have the investor’s wallet sign its UTF-8 bytes as a message. Never compose or change the text: it is the investor’s agreement to Securitize’s terms, not yours. Send the signature hex-encoded, not in base58; a 0x prefix is optional. With a Solana wallet, for example:

const signatureBytes = await wallet.signMessage(new TextEncoder().encode(agreementMessage));
const signature = Buffer.from(signatureBytes).toString('hex');   // 128 hex characters

Hardware wallets, which sign the message wrapped in Solana’s off-chain message format, are accepted the same way. A signature in base58, or any other encoding, is refused as an invalid signature. Link it. Send the signature back through your backend:

curl -X POST "$BASE/wallets" -H "x-api-key: $STOCKS_API_KEY" -H "content-type: application/json" -d '{
  "investorId": "6b31c0e9a4f2d17e85c3b904",
  "walletAddress": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
  "blockchainType": "solana",
  "signature": "4f1c9a7e2b6d03f58e1a9c4b7d2e6f0a3c8b5e1d9f7a2c4e6b0d8f1a3c5e7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8a0c1e3b5d7f9a2c4e6b8d0f1a3c5e7b9d2f4a",
  "title": "Trading wallet"
}'

The wallet is linked and can trade. Securitize also screens it: a wallet that does not pass answers WALLET_VALIDATION_FAILED on its orders.

There is no whitelisting step

A token only moves to whitelisted wallets, and the first trade in each stock whitelists the investor’s wallet for it, inside the same transaction. The investor signs nothing beyond the order, and needs no funds for network fees: Securitize pays them. The SecId API’s whitelisting call is not part of this flow.

Get started

Guides

Concepts

Help

API reference

1. Onboard and verify the investor

2. Send the suitability, and the DLT test in the EEA

3. Link the trading wallet

There is no whitelisting step