Tokenization Guide
Create a token, find the wallet that signs for it, run operations and know when they are done. Start with the common flow, then follow the section for your template.
How it works
Three ideas explain every request in this guide:
- Everything is asynchronous. Creating a token returns it as
PENDING; it can be used once it isDEPLOYED. Each operation returns a transaction of typeTOKEN_OPERATION; the operation has happened only when that transaction isCOMPLETED. - A deployed token is an asset. Its
assetIdworks like any other asset: wallets of that asset hold the token and show its balance. A wallet of the token is a different wallet from the ETH wallet at the same address. - RoxCustody finds the signer when there is only one. Operations signed by the token's owner, or by the holder of an NFT, take no signer at all. You name the signer only when several wallets could sign: an ERC-3643 agent, or the holder of fungible tokens (ERC-20 BURN, REDEEM). You put it inside
paramsassignerWalletAddress(orsignerWalletId). Each operation page says which case it is.
Common flow (every template)
This example creates an ERC-20 token owned by one of your clients and mints to an address.
Create the token
Call Create Token from Template. Set the owner with ownerClientId (your client's wallet on that network) or ownerAddress. Always send an idempotencyKey: if the request times out, sending it again returns the same token instead of deploying a second one.
| POST /api/integration/tokenization/deploy |
| { |
| "standard": 1, |
| "template": "erc20-v1", |
| "networkId": 14, |
| "name": "Example Coin", |
| "symbol": "EXC", |
| "decimals": 18, |
| "initialSupply": "1000000", |
| "ownerClientId": "customer-1001", |
| "config": { "canMint": true, "canBurn": true, "canPause": true }, |
| "idempotencyKey": "create-exc-001" |
| } |
| { |
| "message": "Security token created successfully", |
| "data": { |
| "id": 152, |
| "status": "PENDING", |
| "contractAddress": null, |
| "assetId": null, |
| ... |
| }, |
| "status": 201 |
| } |
Wait until it is DEPLOYED
Listen for the token_created_with_asset webhook, or poll Get Token by ID every few seconds. Deployment usually takes under a minute. When status is DEPLOYED, contractAddress and assetId are set. Any other final status (REVERTED, INSUFFICIENT_GAS, ERROR, NONCE_TOO_LOW) means nothing was deployed: fix the cause (often gas station funds) and create again with a new idempotencyKey.
| GET /api/integration/tokenization/token/152 |
| { |
| "message": "token", |
| "data": { |
| "id": 152, |
| "status": "DEPLOYED", |
| "contractAddress": "0x8cc5ca13cd204d0ab7f9c86c13ce81ad9b2dd104", |
| "assetId": 4466, |
| ... |
| }, |
| "status": 200 |
| } |
Run an operation
Each operation has its own page under Token Operations, with its params, signer and errors. Amounts are strings in whole units ("250.5"), with at most the token's decimals. An ERC-20 MINT is signed by the owner, so RoxCustody finds the signer and the request names none:
| POST /api/integration/tokenization/152/operations |
| { |
| "operation": "MINT", |
| "params": { |
| "receiverAddress": "0x087D3099f42e91F02B1c75AC3CDeCAC815152Cf4", |
| "amount": "250.5" |
| }, |
| "idempotencyKey": "mint-exc-001" |
| } |
The response is the transaction, with data.movements saying exactly which tokens it will create, destroy or move.
| { |
| "message": "Token operation transaction has been created successfully", |
| "data": { |
| "transactionId": 1317, |
| "data": { |
| "operation": "MINT", |
| "securityToken": { "id": 152 }, |
| "movements": [ |
| { "type": "MINT", "to": "0x087D3099f42e91F02B1c75AC3CDeCAC815152Cf4", "amount": "250.5" } |
| ] |
| } |
| }, |
| "status": 201 |
| } |
422 with errors.revertCode (for example RECIPIENT_NOT_VERIFIED or TOKEN_PAUSED). Match on revertCode, not on the message.Name the signer when you must
Operations signed by an agent (ERC-3643) or by the holder of fungible tokens (ERC-20 BURN, REDEEM) need the signer inside params: exactly one of signerWalletAddress or signerWalletId. Take agents from Get Token Roles: its rows give each role holder's wallet.publicAddress and walletId. Only an ACTIVE agent can sign.
| GET /api/integration/tokenization/token/153/roles?filters[role]=AGENT |
| { |
| "message": "Token roles", |
| "data": { |
| "data": [ |
| { |
| "id": 261, |
| "securityTokenId": 153, |
| "walletId": "70867", |
| "wallet": { |
| "id": 70867, |
| "publicAddress": "0x2165Cd3CC07C3CdEdC0184F8958CE6Aca6828722", |
| "type": "MASTER" |
| }, |
| "role": "AGENT", |
| "status": "ACTIVE", |
| ... |
| } |
| ], |
| "meta": { ... } |
| }, |
| "status": 200 |
| } |
| POST /api/integration/tokenization/153/operations |
| { |
| "operation": "MINT", |
| "params": { |
| "receiverAddress": "0x087D3099f42e91F02B1c75AC3CDeCAC815152Cf4", |
| "amount": "10", |
| "signerWalletAddress": "0x2165Cd3CC07C3CdEdC0184F8958CE6Aca6828722" |
| } |
| } |
signerWalletAddress. signerWalletId is the wallet of the token, not the ETH wallet at the same address. A signer where RoxCustody finds it itself, or a missing one where you must name it, is refused with 422.Know when it is done
Follow the transaction with the transaction webhooks or Get Transaction Details. It goes PENDING → BROADCASTING → COMPLETED. The webhook carries the same data as the response.
| { |
| "event": "completed_transaction", |
| "vaultId": 50, |
| "transaction": { |
| "id": "1317", |
| "type": "TOKEN_OPERATION", |
| "status": "COMPLETED", |
| "data": { |
| "operation": "MINT", |
| "securityToken": { "id": 152 }, |
| "movements": [ ... ] |
| }, |
| ... |
| } |
| } |
COMPLETED: done. Balances of RoxCustody wallets in the movements are updated.BLOCKCHAINREJECTEDorERROR: the operation did not happen and balances are restored. You can send it again.
Incoming transaction. Until it is COMPLETED, operations that take tokens from that wallet are refused with "has no recorded balance of this token yet": wait for the incoming transaction, then retry.ERC-20 (erc20-v1)
- Choose capabilities at creation:
canMint,canBurn,canPause. A capability set tofalsecan never be turned on; its operation returns422. WithcanMintfalse,initialSupplymust be above 0. - MINT, PAUSE, UNPAUSE: the owner signs; send no signer.
- BURN: the holder burns its own tokens. Name it in
paramswithsignerWalletAddress(orsignerWalletId).
ERC-721 collections (erc721-v1)
- Mint NFT: the owner signs; send no signer. Send the metadata as a URL you host (
metadataUrl) or as JSON RoxCustody hosts (metadata). The newnftTokenIdis inmovements. - Transfer NFT and Burn NFT: RoxCustody signs with the wallet of your vault that holds the NFT; send no signer. An NFT held outside RoxCustody cannot be operated on.
ERC-3643 permissioned tokens (erc3643-v1)
ERC-3643 tokens can only be held by verified investors. The rules live in two contracts you deploy and manage yourself, on the same network, before creating the token:
Prepare the identity registry and compliance (outside RoxCustody)
- An identity registry (ERC-3643 / T-REX): every address that will receive the token must be registered and verified in it, with an ONCHAINID carrying the claims your trusted issuers require.
- A compliance contract, not bound to another token: the token binds to it at deployment.
- To use RECOVERY_ADDRESS later, add the token's contract address as an agent of the identity registry once it is deployed.
Create the token
| POST /api/integration/tokenization/deploy |
| { |
| "standard": 2, |
| "template": "erc3643-v1", |
| "networkId": 14, |
| "name": "Example Fund Share", |
| "symbol": "EFS", |
| "decimals": 0, |
| "ownerClientId": "issuer-01", |
| "config": { |
| "identityRegistryAddress": "0x6C3B2693C3e35fEc04E44b26b7260d26c4AB8826", |
| "complianceAddress": "0x2C98C58fCea7aC88d2A7F63afed3688387c3dE8a" |
| } |
| } |
decimals is 0 to 18; there is no initialSupply. The owner is also the first agent.
Unpause it
erc3643-v1 tokens are deployed paused, so transfers are blocked until an agent sends UNPAUSE. You can mint while paused.
Operate
- Agents sign MINT, BURN (from any address), FORCED_TRANSFER, RECOVERY_ADDRESS, PAUSE/UNPAUSE and the freezes (SET_ADDRESS_FROZEN, FREEZE_PARTIAL_TOKENS, UNFREEZE_PARTIAL_TOKENS). Name the agent in
paramswithsignerWalletAddress(orsignerWalletId). - The owner signs ADD_AGENT and REMOVE_AGENT; send no signer. An agent must be a master or client wallet of your vault. It shows as
PENDING_ADDITIONin Get Token Roles until the transaction completes, and cannot sign before it isACTIVE. - Before minting or force-transferring to an address, verify it in the identity registry; otherwise the request is refused with
RECIPIENT_NOT_VERIFIED.
Title-backed fractions (title-fraction-v1)
A title-fraction token is an ERC-3643 token backed by one TradeTrust title (for example an electronic bill of lading). The title is handed to the token, split into fractions, and whoever collects every fraction can redeem the title. Everything in the ERC-3643 section applies, except that the token is not deployed paused.
Prepare (outside RoxCustody)
- An ERC-3643 identity registry, as above.
- The TradeTrust title in an active title escrow, whose beneficiary and holder are both the depositor: the party that hands the title over and receives the fractions.
- The depositor verified in the identity registry, since the fractions are minted to it.
Create the token
| POST /api/integration/tokenization/deploy |
| { |
| "standard": 2, |
| "template": "title-fraction-v1", |
| "networkId": 14, |
| "name": "Harbor Warehouse Title", |
| "symbol": "HWT", |
| "decimals": 0, |
| "ownerClientId": "issuer-01", |
| "config": { |
| "escrowAddress": "0x1b5577477543E0eb3a8863a4D268981dE1Cb0486", |
| "depositorAddress": "0xd0E5634B8bBE5539f7dfc913681db96cf81af403", |
| "identityRegistryAddress": "0x6C3B2693C3e35fEc04E44b26b7260d26c4AB8826" |
| } |
| } |
decimals must be 0. RoxCustody checks that the escrow is active, holds the title, and that depositorAddress is its beneficiary.
Hand the title to the token (outside RoxCustody)
Once the token is DEPLOYED, the depositor (as beneficiary and holder) calls transferBeneficiary(contractAddress, "0x") on the title escrow, with the token's contractAddress. Until then FRACTIONALIZE is refused with TOKEN_NOT_TITLE_BENEFICIARY. While the token is the beneficiary, the title's ownership is locked to it.
Fractionalize
An agent, named in params, sends FRACTIONALIZE. The fractions are minted to the depositor, which then distributes them to verified investors. Before this step you can still CANCEL_FRACTIONALIZATION: the token closes and nominates the depositor as beneficiary again; the title's holder then confirms it with transferBeneficiary(depositor, "0x") on TradeTrust.
| POST /api/integration/tokenization/153/operations |
| { |
| "operation": "FRACTIONALIZE", |
| "params": { |
| "supply": "1000", |
| "signerWalletAddress": "0x2165Cd3CC07C3CdEdC0184F8958CE6Aca6828722" |
| } |
| } |
Operate, then redeem
While fractionalized, the ERC-3643 operations work as usual. BURN can never destroy the whole supply. When one wallet of your vault holds every fraction, none frozen and the token not paused, send REDEEM with that wallet as the signer in params: all fractions are burned, to is nominated as the title's new beneficiary, and the token is closed. As TradeTrust requires, the title's holder then confirms it by calling transferBeneficiary(to, "0x") on the escrow.
| POST /api/integration/tokenization/153/operations |
| { |
| "operation": "REDEEM", |
| "params": { |
| "to": "0xd0E5634B8bBE5539f7dfc913681db96cf81af403", |
| "signerWalletAddress": "0xEeC10c60695727E0E44bce4d98f65C36AaFFF7f9" |
| } |
| } |
Integration checklist
- Send an
idempotencyKeyon every create and operation, and retry with the same key after a timeout. - Treat an operation as done only on
completed_transaction, never on the 201. - Keep the gas station funded; a 422
E02601means it ran out. - Match errors on
codeanderrors.revertCode, not on messages. - For ERC-3643, verify every receiver in your identity registry first, and wait for agent changes to be
ACTIVEbefore signing with them.