HomeDocsTokenization Guide
Guide

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.

ℹ
Before you start. You need an access token (see Authentication), a webhook for transaction events (see Webhooks), and gas money: the vault's gas station wallets pay deployment and operation fees, unless the vault is gasless (fees are then taken from your corporate balance).

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 is DEPLOYED. Each operation returns a transaction of type TOKEN_OPERATION; the operation has happened only when that transaction is COMPLETED.
  • A deployed token is an asset. Its assetId works 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 params as signerWalletAddress (or signerWalletId). 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.

1

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.

Request
JSON
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"
}
Response: the token is PENDING
JSON
{
"message": "Security token created successfully",
"data": {
"id": 152,
"status": "PENDING",
"contractAddress": null,
"assetId": null,
...
},
"status": 201
}
2

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.

Deployed
JSON
GET /api/integration/tokenization/token/152
 
{
"message": "token",
"data": {
"id": 152,
"status": "DEPLOYED",
"contractAddress": "0x8cc5ca13cd204d0ab7f9c86c13ce81ad9b2dd104",
"assetId": 4466,
...
},
"status": 200
}
3

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:

Request
JSON
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.

Response
JSON
{
"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
}
⚠
A 4xx answer means nothing was sent and no fee was taken. RoxCustody dry-runs every operation on the contract first: when the contract would refuse it, you get a 422 with errors.revertCode (for example RECIPIENT_NOT_VERIFIED or TOKEN_PAUSED). Match on revertCode, not on the message.
4

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.

Roles
JSON
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
}
ERC-3643 MINT, signed by an agent
JSON
POST /api/integration/tokenization/153/operations
{
"operation": "MINT",
"params": {
"receiverAddress": "0x087D3099f42e91F02B1c75AC3CDeCAC815152Cf4",
"amount": "10",
"signerWalletAddress": "0x2165Cd3CC07C3CdEdC0184F8958CE6Aca6828722"
}
}
ℹ
Prefer 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.
5

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.

completed_transaction
JSON
{
"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.
  • BLOCKCHAINREJECTED or ERROR: the operation did not happen and balances are restored. You can send it again.
ℹ
Tokens that reach one of your wallets from outside RoxCustody (for example a transfer made with another wallet app) arrive as an 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 to false can never be turned on; its operation returns 422. With canMint false, initialSupply must be above 0.
  • MINT, PAUSE, UNPAUSE: the owner signs; send no signer.
  • BURN: the holder burns its own tokens. Name it in params with signerWalletAddress (or signerWalletId).

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 new nftTokenId is in movements.
  • 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:

1

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.
2

Create the token

Request
JSON
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.

3

Unpause it

erc3643-v1 tokens are deployed paused, so transfers are blocked until an agent sends UNPAUSE. You can mint while paused.

4

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 params with signerWalletAddress (or signerWalletId).
  • 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_ADDITION in Get Token Roles until the transaction completes, and cannot sign before it is ACTIVE.
  • 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.

1

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.
2

Create the token

Request
JSON
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.

3

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.

4

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.

Request
JSON
POST /api/integration/tokenization/153/operations
{
"operation": "FRACTIONALIZE",
"params": {
"supply": "1000",
"signerWalletAddress": "0x2165Cd3CC07C3CdEdC0184F8958CE6Aca6828722"
}
}
5

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.

Request
JSON
POST /api/integration/tokenization/153/operations
{
"operation": "REDEEM",
"params": {
"to": "0xd0E5634B8bBE5539f7dfc913681db96cf81af403",
"signerWalletAddress": "0xEeC10c60695727E0E44bce4d98f65C36AaFFF7f9"
}
}

Integration checklist

  • Send an idempotencyKey on 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 E02601 means it ran out.
  • Match errors on code and errors.revertCode, not on messages.
  • For ERC-3643, verify every receiver in your identity registry first, and wait for agent changes to be ACTIVE before signing with them.

What's next?