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. Four tokenization endpoints (create token, mint, burn, create NFT) accept multipart/form-data instead, since they upload files. |
Response Format
Successful responses share a consistent JSON envelope with a message, a data payload, and 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.
Browse by Category
The API is organized into 10 categories. Each page documents every endpoint's parameters, request body, and example responses.
Authentication
2 endpointsManage authentication and authorization for the RoxCustody API. Generate access tokens using API keys and refresh tokens to maintain secure access to the platform. Authentication is required for all API requests and tokens must be included in the X-ACCESS-TOKEN header.
Clients
4 endpointsClients represent external entities in segregated and consolidated vaults. They are identified by an externalId (your system's ID) and are used to separate funds and transactions by client in RoxCustody. When you create a client, the system automatically creates wallets for each integrated blockchain network. Clients are essential for maintaining separate accounting and transaction history for different customers or entities.
Wallets
4 endpointsManage and query wallet information. Wallets are blockchain addresses associated with clients in RoxCustody. Each client automatically receives wallets for each integrated blockchain network. Wallets store cryptocurrency balances and track transaction history. You can query wallet balances, transaction counts, and filter wallets by various criteria such as client, asset, or network.
Vaults
9 endpointsAccess vault details and configuration. Vaults are the primary organizational unit in RoxCustody that contain clients, wallets, and assets. Each vault represents a separate custody environment with its own configuration, payment policies, gas station categories, and network settings. View vault details, assets, networks, approvals, and payment policies.
Transactions
5 endpointsCreate and manage blockchain transactions. Send cryptocurrencies and tokens from client wallets to external addresses or between clients in RoxCustody. Track transaction status and history with comprehensive filtering options. Transactions support various types including incoming, outgoing, internal transfers, swaps, and allowance operations. Monitor transaction statuses from pending to completed, rejected, or error states.
Assets
2 endpointsManage and query digital assets. Assets represent cryptocurrencies and tokens supported by the RoxCustody platform. Each asset is associated with a blockchain network and includes details such as symbol, decimals, contract address, and current pricing information. Query asset prices and view asset configurations for your vault.
Tokens
7 endpointsManage security tokens and tokenized assets. Create, deploy, and manage fungible tokens on supported blockchains in RoxCustody. Tokenization allows you to represent real-world assets or create new digital assets as blockchain tokens. View token details, supported networks, create tokens, mint or burn tokens, and manage token metadata. Tokens can be transferred between wallets and integrated into your custody operations.
NFTs
5 endpointsManage Non-Fungible Tokens (NFTs). Create, deploy, and manage unique digital assets as NFTs on supported blockchains in RoxCustody. NFTs represent unique items such as digital art, collectibles, or certificates of ownership. View NFT details, supported networks, create NFTs, transfer NFTs between wallets, and track NFT transfer transactions. Each NFT has unique metadata and ownership information.
Payment Vault Order
5 endpointsManage payment vault orders for processing crypto payments. Create payment orders that allow customers to pay in cryptocurrency. Each order generates a unique payment link and assigns a wallet for receiving payments. Orders can be created with a specific asset or the asset can be selected later. Track order status, view order details, and cancel pending orders. Payment orders support fiat amount conversion and automatic wallet assignment.
Fiat Gateway
4 endpointsManage fiat payment links and transactions. The Fiat Gateway allows you to generate payment links for clients to deposit fiat funds (e.g. via credit card, bank transfer) and process refunds for eligible transactions.