HomeAPI ReferenceToken Operations
API Reference

Token Operations

Run an operation on a token created from a template: POST /integration/tokenization/{id}/operations with the operation name, its params and the wallet that signs. RoxCustody checks the request, dry-runs it on the contract, then creates a transaction of type TOKEN_OPERATION that it signs and sends. Each page below is one operation. Which operations each template has: • erc20-v1: MINT, BURN, PAUSE, UNPAUSE (each only if its capability was enabled at creation). • erc721-v1: MINT, BURN, TRANSFER, PAUSE, UNPAUSE (BURN and PAUSE/UNPAUSE only if enabled at creation). • erc3643-v1: MINT, BURN, FORCED_TRANSFER, RECOVERY_ADDRESS, PAUSE, UNPAUSE, SET_ADDRESS_FROZEN, FREEZE_PARTIAL_TOKENS, UNFREEZE_PARTIAL_TOKENS, ADD_AGENT, REMOVE_AGENT. • title-fraction-v1: the erc3643-v1 operations, plus FRACTIONALIZE, CANCEL_FRACTIONALIZATION and REDEEM. Any other operation returns 422 "<OPERATION> is not supported by <template> tokens". Who signs. Each page says it under "Signer". There are two cases: • RoxCustody finds the signer: the token's owner (ERC-20 and ERC-721 MINT, PAUSE, UNPAUSE; ADD_AGENT, REMOVE_AGENT) or the holder of the NFT (Burn NFT, Transfer NFT). Send no signer; one in params is refused with 422 "property … should not exist". • You name the signer: an agent (every other ERC-3643 and title-fraction operation) or the holder of the tokens (ERC-20 BURN, REDEEM). Put exactly one of signerWalletAddress or signerWalletId inside params. Take an agent from Get Token Roles (its wallet.publicAddress or walletId). signerWalletId is the wallet of the token, not the coin wallet at the same address, so signerWalletAddress is usually simpler. The signer never goes at the body's top level: a top-level signerWalletId is refused with 400 "property signerWalletId should not exist". The network fee is paid by the vault's gas station, or from your corporate balance when the vault is gasless. Amounts are strings in whole units (for example "10.5"), with at most the token's decimals. Addresses must be valid for the token's network. The response is the new transaction: data.transactionId, plus data.data, which says what the operation does: • movements: the tokens it creates (MINT), destroys (BURN) or moves (TRANSFER), with addresses and amounts. Empty when no token moves. • stateChanges: only on freeze operations: FREEZE_ADDRESS, UNFREEZE_ADDRESS, FREEZE_TOKENS or UNFREEZE_TOKENS. The same data is on the transaction in Get Transaction Details and in the transaction webhooks. The operation is done when the transaction is COMPLETED; if it fails on-chain (BLOCKCHAINREJECTED or ERROR), nothing changed. Errors shared by every operation: • 404 "Security token not found": no such token in this vault. • 400 "Security token is not fully deployed yet". • 422 "<OPERATION> is not supported by <template> tokens", or "<OPERATION> is not available for this token: its config does not allow it". • 422 a signer missing (or both fields sent) where you must name one, or a signer sent where RoxCustody finds it. • 403 the named signer is not a wallet of the token in this vault, or is not an ACTIVE agent; or the token's owner is not a wallet of this vault. • 422 with errors.revertCode: the contract refused the dry run, so nothing was sent or charged. Branch on revertCode, which stays stable when messages change. Every code, what it means and how to resolve it: Error Codes, Token Operation Refusals (/docs/errors#token-revert-codes). Each operation page shows the ones it most often returns. • 400 "Security token does not support this operation flow": the token was created without a template (Create Token v1 on Solana): use Mint Tokens and Burn Tokens instead. • 422 E02601 "Gas station wallet does not have enough balance to pay the fees", or 400 "Insufficient corporate balance to cover gas" for a gasless vault. • 409 "Idempotency key does not match": the idempotencyKey was used for a different request. • 422 E00402 for a missing or invalid field, with one key per field in errors.
ERC-20
POSTMint · ERC-20 / ERC-3643 / Title-fractionCreates new tokens and sends them to receiverAddress. erc20-v1: the token must have been created with canMint true; the owner signs. ERC-3643: an agent signs, and the receiver must be verified in the identity registry; a frozen receiver still receives them (frozen only blocks the holder from moving tokens). title-fraction-v1: only while the token is fractionalized. Signer: erc20-v1: RoxCustody signs with the token's owner; do not send a signer. ERC-3643 (erc3643-v1, title-fraction-v1): an agent signs; name one ACTIVE agent in params, as signerWalletAddress or signerWalletId (from Get Token Roles), exactly one of the two. Templates: erc20-v1, erc3643-v1, title-fraction-v1.POSTBurn · ERC-20Destroys tokens from the signer's own balance. The token must have been created with canBurn true. Any wallet of this vault that holds the token can burn its own tokens: it signs. Signer: The holder burns its own tokens: a wallet of this vault that holds the token. Name it in params, as signerWalletAddress or signerWalletId (its wallet of the token). Exactly one of the two. Templates: erc20-v1.POSTPause · ERC-20 / ERC-721 / ERC-3643 / Title-fractionStops every transfer of the token until it is unpaused. erc20-v1 and erc721-v1: the token must have been created with canPause true; the owner signs. ERC-3643: an agent signs; erc3643-v1 tokens start paused. Signer: erc20-v1 and erc721-v1: RoxCustody signs with the token's owner; do not send a signer. ERC-3643 (erc3643-v1, title-fraction-v1): an agent signs; name one ACTIVE agent in params, as signerWalletAddress or signerWalletId (from Get Token Roles), exactly one of the two. Templates: erc20-v1, erc721-v1, erc3643-v1, title-fraction-v1.POSTUnpause · ERC-20 / ERC-721 / ERC-3643 / Title-fractionLets transfers of a paused token resume. Same signer and capability as Pause. Signer: erc20-v1 and erc721-v1: RoxCustody signs with the token's owner; do not send a signer. ERC-3643 (erc3643-v1, title-fraction-v1): an agent signs; name one ACTIVE agent in params, as signerWalletAddress or signerWalletId (from Get Token Roles), exactly one of the two. Templates: erc20-v1, erc721-v1, erc3643-v1, title-fraction-v1.
ERC-721
ERC-3643 · also Title-fraction
POSTBurn · ERC-3643 / Title-fractionAn agent destroys tokens held by any address, inside or outside RoxCustody. Frozen tokens can be burned: the contract unfreezes what the unfrozen balance cannot cover. title-fraction-v1: only while fractionalized, and never the whole supply (at least one fraction must remain so the title can be redeemed). Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTForced Transfer · ERC-3643 / Title-fractionAn agent moves tokens from one address to another without the holder signing, for example to execute a court order. The receiver must be verified in the identity registry and not frozen. Frozen tokens can be moved: the contract unfreezes what the unfrozen balance cannot cover. When from is a RoxCustody wallet, its recorded balance must cover the amount. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTRecovery Address · ERC-3643 / Title-fractionAn agent moves the whole balance of an investor's lost wallet to their new wallet. The lost wallet must be outside RoxCustody and registered in the identity registry; the new wallet must be a management key of the same investor's ONCHAINID and not registered yet. The new wallet takes over the lost wallet's registration and its frozen tokens or frozen status. The token must be an agent of its identity registry. RoxCustody wallets are never recovered: use a forced transfer. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTFreeze or Unfreeze Address · ERC-3643 / Title-fractionAn agent freezes (freeze true) or unfreezes (freeze false) an address. A frozen address can neither send nor receive the token by transfer; agents can still mint to it, burn from it and force-transfer from it. The address's balance stays the same. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTFreeze Tokens · ERC-3643 / Title-fractionAn agent freezes part of an address's balance: the holder cannot transfer the frozen amount, the rest stays free. The amount must not exceed the address's balance that is not frozen yet. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTUnfreeze Tokens · ERC-3643 / Title-fractionAn agent unfreezes part of an address's frozen tokens, so the holder can transfer them again. The amount must not exceed the address's frozen tokens. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: erc3643-v1, title-fraction-v1.POSTAdd Agent · ERC-3643 / Title-fractionThe owner gives the AGENT role to a wallet of this vault. The agent must be a master or client wallet of this vault on the token's network (an EOA or EIP-7702 wallet). Get Token Roles shows it as PENDING_ADDITION until the transaction completes, then ACTIVE. While an addition or removal of the same wallet is pending, a new one is refused (409). Signer: RoxCustody signs with the token's owner (the OWNER role). Do not send a signer: signerWalletAddress or signerWalletId in params is refused. Templates: erc3643-v1, title-fraction-v1.POSTRemove Agent · ERC-3643 / Title-fractionThe owner takes the AGENT role away from a wallet. Get Token Roles shows it as PENDING_REMOVAL until the transaction completes, then REMOVED. While an addition or removal of the same wallet is pending, a new one is refused (409). Signer: RoxCustody signs with the token's owner (the OWNER role). Do not send a signer: signerWalletAddress or signerWalletId in params is refused. Templates: erc3643-v1, title-fraction-v1.
Title-fraction only
POSTFractionalize · Title-fraction onlySplits the title into supply fractions, minted to the depositor, which must be verified in the identity registry. The token must be the title's beneficiary first: the depositor, as beneficiary and holder, calls transferBeneficiary(token contractAddress) on the title escrow. Can happen once; after it, MINT, BURN and REDEEM become available. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: title-fraction-v1.POSTCancel Fractionalization · Title-fraction onlyGives up on a token before it is fractionalized: the token closes for good and nominates the depositor as the title's beneficiary again. The title's holder then confirms it by calling transferBeneficiary(depositor) on the title escrow, as TradeTrust requires. Signer: An agent signs: name one ACTIVE agent of this token in params, as signerWalletAddress or signerWalletId (from Get Token Roles). Exactly one of the two. Templates: title-fraction-v1.POSTRedeem · Title-fraction onlyThe holder of every fraction burns them all, the to address is nominated as the title's new beneficiary, and the token is closed. The title's holder then confirms it by calling transferBeneficiary(to) on the title escrow, as TradeTrust requires. The signer must hold the whole supply, none of it frozen, and the token must not be paused. Signer: The holder of every fraction signs: the wallet of this vault that holds the whole supply. Name it in params, as signerWalletAddress or signerWalletId (its wallet of the token). Exactly one of the two. Templates: title-fraction-v1.

Was this page helpful?