API Reference
Complete reference for the Rox Custody REST API. All endpoints are scoped to your corporate subdomain and, apart from the two /auth endpoints, require an X-ACCESS-TOKEN header. Browse the categories below for every endpoint's parameters, request bodies, and responses.
Base URL
Replace YOUR-SUBDOMAIN with your organization's assigned subdomain. Use the sandbox environment for testing before pointing your integration at production.
| # Production |
| https://YOUR-SUBDOMAIN.api.roxcustody.com/api/integration |
| # Sandbox |
| https://YOUR-SUBDOMAIN.api-sandbox.roxcustody.com/api/integration |
Request Headers
| X-ACCESS-TOKEN: YOUR_ACCESS_TOKEN |
| Content-Type: application/json |
| Header | Required | Description |
|---|---|---|
X-ACCESS-TOKEN | Yes | Required on all endpoints except POST /auth/generate-tokens and POST /auth/refresh-token. Obtain it from POST /auth/generate-tokens using your API key. |
Content-Type | Recommended | application/json for request bodies. Two endpoints, Create Token (v1) and Create NFT Token, take multipart/form-data instead, so that you can upload an image. |
Response Format
Successful responses are JSON objects with a message, the result, and a status number. The result is usually under data; a few endpoints use a named key instead (transaction, client, clients, contractCall), and list endpoints add a meta object for pagination. The body's status can differ from the HTTP status (for example a POST may answer HTTP 201 with "status": 200): rely on the HTTP status.
| { |
| "message": "Vault API Keys generated successfully", |
| "data": { |
| "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", |
| "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", |
| "expiresAt": 1767258052423, |
| "vaultId": 1 |
| }, |
| "status": 201 |
| } |
Errors carry a message, an errors object (with per-field validation messages where applicable), and a machine-readable code:
| { |
| "status": 422, |
| "message": "apiKey must be a string", |
| "errors": { |
| "message": "apiKey must be a string", |
| "apiKey": [ |
| "apiKey must be a string", |
| "The apiKey must not exceed 255 characters", |
| "apiKey should not be empty" |
| ] |
| }, |
| "code": "E00402" |
| } |
See Error Codes for the errors that are common to all endpoints; endpoint-specific errors are documented with each endpoint below.
Core Concepts
If you are new to RoxCustody, these are the objects the API works with:
| Concept | What it is |
|---|---|
| Vault | A custody account in your company's RoxCustody workspace. Your API key belongs to one vault, and every request only sees that vault. The vault type (segregated, consolidated, payment, fiat, …) decides which endpoints you can use. |
| Client | One of your own customers. You register them with your own id (returned as externalId), and RoxCustody keeps their funds separate. |
| Network | A blockchain, such as Ethereum, Tron or Solana, enabled in the vault. |
| Asset | A coin or token on a network, such as ETH or USDT. Most endpoints refer to it by assetId. |
| Wallet | One address holding one asset, owned by a client (CLIENT), by the vault (MASTER), or used to pay fees (GAS_STATION). RoxCustody creates and secures them; you never handle private keys. |
| Transaction | A movement of an asset on a blockchain. You create outgoing ones; incoming ones are detected automatically. They go from PENDING to BROADCASTING to COMPLETED. |
| Approvals | Depending on the vault's payment policy, outgoing transactions may wait for approval by vault admins before they are sent. |
| Webhook | An HTTPS endpoint on your server that RoxCustody calls when something happens, so you don't need to poll. |
A typical first integration
- Create an API key for your vault in the dashboard, then call Generate Tokens.
- Call Get Vault Details, Get Vault Networks and Get Vault Assets to see what the vault supports, and note the
assetIds you need. - Register your webhook with Verify Webhook and choose events with Create Webhook Events.
- Create a client with Create New Client. Their wallets are created in the background; list them with Get All Clients' Wallets (
clientId= your id). Show the deposit address to your customer. - Deposits appear as Incoming transactions and trigger
create_transactionandcompleted_transactionwebhooks. - Send funds with Create Transaction using an
idempotencyKey, and follow it by webhook or with Get Transaction Details.
Conventions
- Amounts are strings in the asset's normal unit (for example
"0.25"ETH, not wei), so no precision is lost. Send amounts as strings too. - Dates in API responses look like
"09 November, 2026 10:15:02"(in the API server's time zone). Webhook payloads may use ISO 8601. - Enum values are returned as names, for example
"status": "COMPLETED". Each endpoint lists the possible values. - Unknown fields are rejected: sending a field that an endpoint does not document returns 422.
- Idempotency: endpoints that move funds or create tokens accept
idempotencyKey(max 100 characters). Repeating a request with the same key returns the original result instead of doing it twice, so you can retry safely after a timeout. - Pagination comes in two kinds. Cursor pagination (transactions, wallets, payment orders): pass
limit(up to 100) and thencursor=meta.nextCursorfrom the previous response. Page pagination (assets, networks, approvals, tokens, NFTs): passpageandlimit;metahastotalItemsandtotalPages. - Filters and sorting:
filters[field]=value,sortKeyandorder(ASC or DESC). Each list endpoint documents which fields are accepted; others return 422. - Versioning: endpoints are unversioned (
/api/integration/…) unless marked v2, which live under/api/v2/integration/…. - Rate limits: 500 requests per second per vault; Generate Tokens 10 per minute; Refresh Token 2 per second. Over the limit you get HTTP 429.
Browse by Category
The API is organized into 13 categories. Each page documents every endpoint's parameters, request body, and example responses.
Authentication
2 endpointsEvery API call is made on behalf of one vault. Your vault has an API key, which you create in the RoxCustody dashboard (Vault settings, API keys). Exchange it for a short-lived access token with Generate Tokens, then send the token in the X-ACCESS-TOKEN header of every other request. Token lifetimes: the access token is valid for 30 minutes (expiresAt is its expiry as a Unix timestamp in milliseconds); the refresh token is valid for 180 days. When the access token expires, requests fail with HTTP 498 and code E01403: call Refresh Token to get a new pair. Each refresh token can be used once, and the new pair replaces the old one. If the refresh token is no longer valid, start a new session with Generate Tokens. Rate limits: Generate Tokens accepts 10 requests per minute; Refresh Token accepts 2 requests per second. All other endpoints accept up to 500 requests per second per vault. Beyond these limits, the API returns HTTP 429 with code E00404.
Clients
4 endpointsA client is one of your own customers or users. You register them with the id you use in your system (called externalId in responses), and RoxCustody keeps their funds separate from everyone else's. Clients exist only in API vaults (segregated or consolidated crypto vaults, and fiat vaults). Crypto clients: creating a client starts the creation of their wallets, one per blockchain network enabled in the vault, in the background. Fetch them with the Wallets endpoints, or subscribe to the sync_client_wallets webhook to know when they are ready. Fiat clients: created in fiat vaults. They need a legal name, and an IBAN if you want to refund their deposits. Client ids must be unique per vault. Creating a client whose id already exists returns 422 with code E03401 and lists the existing clients.
Wallets
6 endpointsA wallet is one blockchain address holding one asset. RoxCustody creates them for you; you never handle keys. Wallet types (the "type" field): MASTER (the vault's own wallets), CLIENT (one per client and asset), GAS_STATION (pays network fees on behalf of other wallets), ORDER (receives one payment order) and SYSTEM_FEES. Balances are strings in the asset's normal unit (for example "1.5" ETH), so very large or precise amounts are never rounded. pendingBalance is the part reserved by transactions that are not completed yet. List endpoints use cursor pagination: read meta.nextCursor and pass it as the cursor query parameter.
Vaults
9 endpointsA vault is a separate custody account inside your company's RoxCustody workspace. Your API key belongs to one vault, and every request only sees that vault's data. Vault types (vaultType): api_segregated (each client gets their own wallets), api_consolidated (client balances are tracked separately but funds are held together), internal, escrow, payment (crypto payment orders), fiat_segregated and fiat_payment (fiat clients and fiat payment orders). The type decides which endpoints you can use: for example payment orders need a payment vault, and fiat endpoints need a fiat vault. Approvers: outgoing transactions may need approval by vault admins, according to the vault's payment policy. Get Vault Approvals lists these admins and Get Vault Payment Policy shows the rules. This section also covers webhooks, which push events to your server (see the Webhooks guide).
Transactions
3 endpointsA transaction moves an asset on a blockchain. You create outgoing transactions; incoming ones are detected automatically and appear in the same list. Lifecycle (status): PENDING (created, possibly waiting for approvers) → BROADCASTING (signed and sent to the network) → COMPLETED (confirmed on-chain). It can end instead as REJECTED (an approver refused it), CANCELLED, BLOCKCHAINREJECTED (the network refused it), INSUFFICIENTGASFEES (the gas station could not pay the fee), ERROR, or COMPLIANCE_RULE (held by a compliance rule). Types (type): Incoming, Outgoing, Internal (between two wallets of your vault), Swap, Allowance, TOKEN_DEPLOYMENT, MINT_TOKEN, BURN_TOKEN, NFT_TRANSFER, CONTRACT_CALL and TOKEN_OPERATION. Creating a transaction only queues it: the response comes back with status PENDING. Follow it with the transaction webhooks (create_transaction, broadcasted_transaction, completed_transaction, …) or by polling Get Transaction Details. Use idempotencyKey so that a retried request never sends the money twice. Amounts are strings in the asset's normal unit (for example "0.1" ETH). dollarAmount and fiatAmount are the value at creation time. The data field. Some types carry details in data. For a TOKEN_OPERATION (an operation run through Token Operations), data says exactly what the operation does, so you can rely on it instead of decoding the blockchain transaction: • data.operation and data.securityToken.id: which operation, on which token. • data.movements: every token it creates (MINT: to), destroys (BURN: from) or moves (TRANSFER: from and to), with amount in the token's whole units, or nftTokenId for an NFT. Empty when no token moves. • data.stateChanges: only on freeze operations: FREEZE_ADDRESS, UNFREEZE_ADDRESS, FREEZE_TOKENS or UNFREEZE_TOKENS, with the address (and amount for tokens). The same data is in the operation's response, in Get Transaction Details, in Get Transactions and in every transaction webhook, and never changes after creation. Treat it as done only when status is COMPLETED; if the transaction ends BLOCKCHAINREJECTED or ERROR, none of it happened. For a TOKEN_OPERATION, amount is null (use movements), asset is the token, senderAddress is the wallet that signed, receiverAddress is the token contract, and fees are in the network's coin (coinSymbol).
Assets
2 endpointsAn asset is a coin or token that the vault can hold, for example ETH on Ethereum or USDT on Tron. Every wallet, transaction and payment order refers to an asset by its id; list the vault's assets with Get Vault Assets. Asset types: COIN (the network's native currency, which also pays fees), TOKEN, and CUSTOM_TOKEN (a token your company created, for which you can set a price).
Tokens
9 endpointsCreate and run your own tokens. RoxCustody deploys the contract from a vault wallet, keeps the keys in custody and signs every later operation. Templates. Create Token from Template deploys an audited contract template: • erc20-v1 (standard ERC20): a fungible token. You choose its capabilities at creation (canMint, canBurn, canPause). • erc721-v1 (standard ERC721): an NFT collection. Each NFT is minted later with its own metadata. • erc3643-v1 (standard ERC3643): a permissioned security token (T-REX). Only addresses verified in your ERC-3643 identity registry can hold it, and agents can freeze, force-transfer and recover balances. It starts paused. • title-fraction-v1 (standard ERC3643): an ERC-3643 token backed by a TradeTrust title. The title is handed to the token, then split into fractions; holding every fraction lets you redeem the title. Create Token (v1) is the original flow for plain ERC-20 and Solana tokens. Deployment is asynchronous: the token comes back with status PENDING and moves to DEPLOYED once the contract is on-chain (or REVERTED, INSUFFICIENT_GAS, ERROR or NONCE_TOO_LOW). Follow it with the token_created_with_asset webhook or Get Token by ID. Once deployed, the token is also an asset (assetId): wallets of that asset hold it. Roles. The owner (OWNER role) is the wallet set at creation. ERC-3643 tokens also have agents (AGENT role), added and removed by the owner; the owner starts as the first agent. Get Token Roles lists who holds which role, and each operation says which role signs it. Fees. The deployment fee is paid by the vault's gas station wallets, by payerPublicAddress when given, or from your corporate balance when the vault is gasless.
Token Operations
18 endpointsRun 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.
NFTs
7 endpointsNFTs are unique tokens: each one has its own token ID and metadata (name, image, attributes). In RoxCustody you create an NFT collection, then each NFT inside it is tracked individually with its current holder (see Get Collection NFTs and Get Wallet NFTs). Like fungible tokens, creation is asynchronous (status PENDING, then DEPLOYED) and network fees are paid by the vault's gas station wallets. For collections created from a template (v2), use Token Operations (Mint NFT, Burn NFT, Transfer NFT).
Crypto Payment Orders
6 endpointsAccept crypto payments from your customers. A payment order is an invoice in fiat (amountInFiat, in your vault's currency) that the customer pays in crypto. Available in payment vaults. Flow: 1) Create the order. 2) If you did not give an assetId, the customer picks a coin and you call Select Asset; RoxCustody then assigns a dedicated receiving wallet and calculates amountInAsset at the current price. 3) The customer pays to the wallet address, or through paymentLink, before expiration. 4) RoxCustody detects the payment and marks the order PAID; you receive the paid_payment_vault_order webhook. Statuses: INITIALIZING (being created), PENDING (waiting for payment), PAID, EXPIRED, CANCELLED, REFUNDED. Order ids: you can give your own id (up to 42 characters); otherwise a ULID is generated.
Fiat Payment Orders
5 endpointsAccept bank and card payments in fiat (currently SAR). Available in fiat payment vaults. Flow: create the order; RoxCustody opens a dedicated virtual account for it and returns a hosted checkout link (paymentLink). Send the customer to that link. When the payment arrives, the order becomes PAID and you receive the fiat_payment_vault_order_paid webhook. If you stored the customer's IBAN, the order can be refunded (REFUNDED, webhook fiat_payment_vault_order_refunded). Statuses: INITIALIZING, PENDING, PAID, EXPIRED, CANCELLED, REFUNDED.
Fiat Gateway
7 endpointsFiat operations for fiat vaults: let a client deposit money with a payment link, look up fiat accounts and transactions, refund deposits, and pay out your collected balance to your company bank account. Each fiat client has a fiat account (a virtual IBAN, VIBAN). Deposits create fiat transactions (type DEPOSIT); refunds and payouts create transactions of type REFUND and PAYOUT. Transaction statuses: PENDING, PROCESSING, SUCCESS, FAILED. Follow them with the fiat_transaction_created, fiat_transaction_completed, fiat_transaction_failed and fiat_refund_created webhooks. Currency: currently SAR only.
Contract Calls
1 endpointCall any smart contract function on an EVM network (Ethereum, Polygon, BSC, …) from a client wallet, with the transaction signed in custody. You prepare the ABI-encoded call data yourself (for example with ethers.js interface.encodeFunctionData). The call is sent from the network's coin wallet of the client, and is tracked as a transaction of type CONTRACT_CALL.