API Documentation
This section provides detailed information about the available API endpoints for managing wallets, handling transactions, and accessing asset information within RoxCustody. Each endpoint is described
Endpoints
Clients
Create Client Wallets
Creates a new client linked to this vault and creates new wallets for each of the integrated blockchains.
URL
/clients/create
Method:
POST
Headers
Content-Type: application/json
X-API-KEY:
YOUR-API-KEY
Body
{
"id": "string"
}
Success Response:
Code: 201
Content:
{
"message": "Client created successfully.", // string
"data": { // object
"external_id": "133", // string
"id": 3 // number
},
"status": 201 // number
}
Error Response:
Client ID Already Exists:
Code: 422
Content
{
"status": 422,
"message": "Unprocessable Entity Exception",
"errors": {
"id": "Client with this Id already exists",
}
}
Wallets
Get All Clients' wallets
Returns all the clients' wallets for each of the integrated blockchains.
URL
/wallets/client-wallets
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
,balance
.search
: string (optional) - Searches bypublic_address
orasset.name
.filters
(optional)public_address
: string - public address of the wallet.client_id
: nullable number - The ID of the client that owns the wallet. (Usenull
for master wallets).asset_id
: number - The ID of the associated asset.parent_id
: number - The ID of the parent wallet.
Success Response:
Code: 200
Content
{
"message": "Clients' Wallets",
"data": [
{
"id": 47,
"balance": 10,
"pending_balance": 0,
"public_address": "0x3f5eF0c2896bB9E8F29CD9aDA8d682024A1d6642",
"transactions_count": "0",
"asset": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"contract_address": null,
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"type": "PUBLIC",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"type": "COIN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
}
},
{
"id": 56,
"balance": 10,
"pending_balance": 0,
"public_address": "0x204fec71c0C532616d1606F45BfEECf652451583",
"transactions_count": "0",
"asset": {
"id": 5,
"name": "CHAINLINK TOKEN",
"symbol": "LINK",
"contract_address": "0x514910771af9ca656af840dff83e8264ecf986ca",
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"type": "PUBLIC",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"type": "TOKEN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/chainlink.png"
}
},
],
"meta": {
"totalItems": 122,
"itemsPerPage": 2,
"totalPages": 61,
"currentPage": 1,
"hasPreviousPage": false,
"hasNextPage": true
},
"status": 200
}
Get Wallet Details
Returns the details of one wallet.
URL
/wallets/:wallet_id
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYURL Parameters
wallet_id = number
Success Response:
Code: 200
Content:
{
"message": "Wallet balance",
"data": {
"id": 54,
"balance": 10,
"pending_balance": 0,
"public_address": "0xaE76F4a4603C1CA2384B26CF4a14794634a55d82",
"transactions_count": "0",
"created_at": "17 November, 2024 13:19:03",
"updated_at": "17 November, 2024 13:44:01"
},
"status": 200
}
Error Response:
Not Existing Wallet:
Code: 404
Content
{
"status": 404,
"message": "Can't find this wallet",
"errors": {
"message": "Can't find this wallet",
"error": "Not Found",
}
}
Get Gas Station Wallets
Returns the gas station wallets info.
URL
/wallets/gas-station-wallets
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
,balance
.search
: string (optional) - Searches bypublic_address
orasset.name
.filters
(optional)public_address
: string - public address of the wallet.asset_id
: number - The ID of the associated asset.
Success Response:
Code: 200
Content:
{
"message": "Gas station wallets",
"data": [
{
"id": 1,
"balance": 9.96380792,
"pending_balance": 0,
"public_address": "0x07f847a5B325Bb07e7795A10B717Dc29070bb7D3",
"transactions_count": "1",
"asset": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"contract_address": null,
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"type": "PUBLIC",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 December, 2024 11:02:59",
"type": "COIN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"created_at": "10 November, 2024 10:22:39",
"updated_at": "11 December, 2024 12:30:28"
},
{
"id": 33,
"balance": 9.97999999,
"pending_balance": 0,
"public_address": "0x07f847a5B325Bb07e7795A10B717Dc29070bb7D3",
"transactions_count": "1",
"asset": {
"id": 62,
"name": "Sepolia Ether",
"symbol": "ETH",
"contract_address": null,
"network": {
"id": 2,
"name": "Sepolia",
"symbol": "ETH",
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"type": "PUBLIC",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"type": "COIN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"created_at": "12 November, 2024 08:05:33",
"updated_at": "24 November, 2024 10:38:31"
}
],
"meta": {
"totalItems": 5,
"itemsPerPage": 2,
"totalPages": 3,
"currentPage": 1,
"hasPreviousPage": false,
"hasNextPage": true
}
}
Transactions
Create Transaction
Creates a new transaction from the specified wallet.
URL
/transactions
Method:
POST
Headers
Content-Type: application/json
X-API-KEY:
YOUR-API-KEY
Body
{
"wallet_id": "number",
"receiver_address": "string",
"amount": "number"
}
Success Response:
Code: 200
Content:
{
"message": "Your transaction is pending",
"data": {
"amount": 0.01,
"dollar_amount": 0.2961,
"wallet_id": 58,
"sender_address": "0xf3a29715411357eA165d3282Ba81CA784B0e8741",
"receiver_address": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
"payment_policy_range": {
"id": 4,
"from": 0,
"to": 10000,
"dailyLimit": 100000,
"created_at": "17 November, 2024 13:47:09",
"updated_at": "18 November, 2024 17:15:00",
"paymentPolicyRangeType": "approvals",
"minimumNumberOfApprovals": 1
},
"asset": {
"id": 5,
"name": "CHAINLINK TOKEN",
"symbol": "LINK",
"contract_address": "0x514910771af9ca656af840dff83e8264ecf986ca",
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"type": "PUBLIC",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"type": "TOKEN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/chainlink.png"
},
"encoded_payload": null,
"note": null,
"call_method": null,
"error_message": null,
"id": "439",
"created_at": "16 December, 2024 13:24:22",
"updated_at": "16 December, 2024 13:24:22",
"markup": "1.8998842488623792e-7 ETH",
"fees": "0.0025060584338 ETH",
"type": "Outgoing",
"transaction_hash": null,
"status": "PENDING"
},
"status": 201
}
Error Response:
Insufficient Balance in Gas station Wallet:
Code: 403
Example:
{
"status": 422,
"message": "Gas station wallet does not have enough balance to pay the fees",
"errors": {
"message": "Gas station wallet does not have enough balance to pay the fees",
"gas_station_wallet": "Gas station wallet does not have enough balance to pay the fees"
}
}
Illegal Transaction for Master Wallet
Code: 422
Example:
{
"status": 422,
"message": "this is illegal transaction for master wallet",
"errors": {
"message": "this is illegal transaction for master wallet",
"wallet_id": "this is illegal transaction for master wallet"
}
}
Unauthorized wallet access:
Code: 422
Example:
{
"status": 422,
"message": "Wallet does not belong to the vault",
"errors": {
"message": "Wallet does not belong to the vault",
"wallet_id": "Wallet does not belong to the vault"
}
}
Insufficient Balance for the wallet:
Code: 422
Example :
{
"status": 422,
"message": "Insufficient balance",
"errors": {
"message": "Insufficient balance",
"amount": "Insufficient balance"
}
}
Inactive asset for current vault:
Code: 422
Example:
{
"status": 422,
"message": "Asset is not active for this vault",
"errors": {
"message": "Asset is not active for this vault",
"asset_id": "Asset is not active for this vault"
}
}
Get One Transaction
Retrieves details about a specific transaction.
URL
/transactions/:transaction_id
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYURL Parameters
Required:
transaction_id=[string]
Success Response:
Code: 200
Content:
{
"message": "Transaction",
"data": {
"id": "439",
"amount": "0.01000000000000000000",
"dollar_amount": "0.29610000000000000000",
"wallet_id": "58",
"sender_address": "0xf3a29715411357eA165d3282Ba81CA784B0e8741",
"receiver_address": "0x95222290dd7278aa3ddd389cc1e1d165cc4bafe5",
"encoded_payload": null,
"note": null,
"call_method": null,
"error_message": null,
"asset": {
"id": 5,
"name": "CHAINLINK TOKEN",
"symbol": "LINK",
"contract_address": "0x514910771af9ca656af840dff83e8264ecf986ca",
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/chainlink.png"
},
"payment_policy_range": {
"id": 4,
"paymentPolicyRangeType": "approvals",
"minimumNumberOfApprovals": 1
},
"admin": null,
"created_at": "16 December, 2024 13:24:22",
"updated_at": "16 December, 2024 13:24:22",
"markup": "1.8998842488623792e-7 ETH",
"fees": "0.00250605843380000000 ETH",
"approvals": [
{
"action": "PENDING",
"admin": {
"id": 1,
"name": "super admin",
"photo": "https://dafa-projects.nyc3.digitaloceanspaces.com/admin_1732186643269.jpeg"
},
"updated_at": "2024-12-16T13:24:22.464Z"
},
{
"action": "PENDING",
"admin": {
"id": 2,
"name": "Beshoyy",
"photo": "https://dafa-projects.nyc3.digitaloceanspaces.com/binance-logo_1733318287799.png"
},
"updated_at": "2024-12-16T13:24:22.464Z"
},
{
"action": "PENDING",
"admin": {
"id": 3,
"name": "Mhmd",
"photo": "https://dafa-projects.nyc3.digitaloceanspaces.com/-1x-1xMQ_IMG-20241211-WA0003_1733914671678.jpg"
},
"updated_at": "2024-12-16T13:24:22.464Z"
},
{
"action": "PENDING",
"admin": {
"id": 4,
"name": "test"
},
"updated_at": "2024-12-16T13:24:22.464Z"
}
],
"backupStorage": {
"id": 22,
"name": "Bosh"
},
"type": "Outgoing",
"transaction_hash": null,
"status": "PENDING"
},
"status": 200
}
Error Response:
Not Existing Transaction:
Code: 404
Example:
{
"status": 404,
"message": "This transaction does not exist",
"errors": {
"message": "This transaction does not exist"
}
}
Get All Transactions
Retrieves details about all transactions.
URL
/transactions
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
,amount
,dollar_amount
,fees
.search
: string (optional) - Searches bysender_address
,receiver_address
, orasset name
.filters
(optional)client_id
: number - ID of the client associated with the transaction..wallet_id
: number - ID of the wallet associated with the transaction.asset_id
: number - ID of the asset used in the transaction.vault_id
: number - ID of the vault involved in the transaction.gasStationCategoryId
: number - Gas station category ID associated with the wallet.type
: enum - Transaction type, one ofIncoming
,Outgoing,
Internal
.status
: enum - Approval actions for the transaction, one ofPENDING, COMPLETED, REJECTED, ERROR, INSUFFICIENTGASFEES, BROADCASTING, BLOCKCHAINREJECTED
.approvalTransactionActions
: number - ID of the vault involved in the transaction.
Success Response:
Code: 200
Content:
{
"message": "vaults", // string
"data": [ // array of objects
{
"id": "15", // string
"amount": "0.10000000000000000000", // string
"dollar_amount": "0.00000000000000000000", // string
"fees": "0.00000000246612892600", // string
"sender_address": "0xCDc1c9B8E1A8B0e1533B0e4587454C2dd76f4A88", // string
"receiver_address": "0xQABAkAgkuLEHLaqkWhLgNKagSajeobLS3rPT0Agm0f7k55FXVt743ha", // string
"encoded_payload": null, // string
"note": null, // string
"call_method": null, // string
"error_message": null, // string
"gas_station_category_wallet_id": "1", // string
"asset": { // object
"id": 2, // number
"name": "TETHER USD", // string
"symbol": "USDT", // string
"network": { // object
"id": 1, // number
"name": "Ethereum", // string
"symbol": "ETH", // string
"logo": "https://api-super-admin-custody-test.roxcustody.io/public/files/biconomy-assets/ethereum.png" // URL (string)
},
"logo": "https://api-super-admin-custody-test.roxcustody.io/public/files/biconomy-assets/tether.png" // URL (string)
},
"created_at": "2024-08-04T08:36:13.098Z", // string (ISO 8601 date)
"updated_at": "2024-08-04T08:36:13.098Z", // string (ISO 8601 date)
"approvals": [ // array of objects
{
"id": 3, // number
"name": "test", // string
"logo": null // string
}
],
"type": "TRANSFER", // string
"created_by": "Eslam", // string
"transaction_hash": null, // string
"status": "PENDING" // string
}
],
"meta": { // object
"totalItems": 1, // number
"itemsPerPage": 10, // number
"totalPages": 1, // number
"currentPage": 1, // number
"hasPreviousPage": false, // boolean
"hasNextPage": false // boolean
},
"status": 200 // number
}
Approvals
Get All Approvals
Returns the current admins (approvals) that are linked and responsible for the transactions of this vault.
URL
/vaults/approvals
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
,name
,email
, status.search
: string (optional) - Searches byname
,email
, orphone
.filters
(optional)name
: string - Name of the admin.email
: string - Email address of the admin.role_id
: number, In, NotIn - Role ID of the admin.status
: enum - Status of the admin, one ofactive, hold
.vaults
: number, In, NotHave - ID of the vault associated with the admin.
Success Response:
Code: 200
Content:
{
"message": "Vault Approvals", // string
"data": [ // array of objects
{
"id": 4, // number
"phone": null, // string
"name": "Approval", // string
"email": "[email protected]", // string
"is_two_factor_enabled": false,
"created_at": "10 November, 2024 10:19:27",
"updated_at": "16 December, 2024 13:30:30",
"vaults": [ // array of objects
{
"id": 17, // number
"name": "alaa11" // string
}
],
"status": "active", // string
"photo": "https://dafa-projects.nyc3.digitaloceanspaces.com/-1x-1xMQ_IMG-20241211-WA0003_1733914671678.jpg",
"role_assign_date": "04 August, 2024 at 10:23 AM" // string
}
],
"meta": { // object
"totalItems": 1, // number
"itemsPerPage": 3, // number
"totalPages": 1, // number
"currentPage": 1, // number
"hasPreviousPage": false, // boolean
"hasNextPage": false // boolean
},
"status": 200 // number
}
Assets
Get Vault Assets
URL
/vaults/assets
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
,network_id
.search
: string (optional) - Searches byname
,symbol
.filters
(optional)network_id
: number - Network ID associated with the asset.type
: enum - Type of the asset, one ofCOIN, TOKEN, CUSTOM_TOKEN.
status
: enum - Status of the asset, one ofACTIVE, HOLD, PENDING
.vaultsAssets
: number, In, NotHave - Vault ID associated with the asset.vaultAssetsStatus
: enum - Status of the vault assets, one ofactive, deactivated.
Success Response:
Code: 200
Content:
{
"message": "Vault Assets",
"data": [
{
"id": 1,
"name": "Ethereum",
"symbol": "ETH",
"contract_address": null,
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH"
},
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 December, 2024 11:02:59",
"vaultStatus": "deactivated",
"type": "COIN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png"
},
{
"id": 5,
"name": "CHAINLINK TOKEN",
"symbol": "LINK",
"contract_address": "0x514910771af9ca656af840dff83e8264ecf986ca",
"network": {
"id": 1,
"name": "Ethereum",
"symbol": "ETH"
},
"created_at": "10 November, 2024 10:15:30",
"updated_at": "10 November, 2024 10:15:30",
"vaultStatus": "active",
"type": "TOKEN",
"status": "ACTIVE",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/chainlink.png"
}
],
"meta": {
"totalItems": 2,
"itemsPerPage": 10,
"totalPages": 1,
"currentPage": 1,
"hasPreviousPage": false,
"hasNextPage": false
}
}
Get One Asset Gas Price
Returns the current gas price for transactions of the specified asset.
URL
/
transactions/gas-price/:asset_id
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYURL Parameters
asset_id=[integer]
Success Response:
Code: 200
Content:
{
"message": "Asset gas price", // string
"data": { // object
"gas_price": 1.315127193e-9 // number
}
}
Error Response:
Code: 404
Content:
{
"status": 404,
"message": "This asset doesn't exist.",
"errors": {
"message": "This asset doesn't exist.",
}
}
Get All Networks
Returns the networks supported in the vault.
URL
/vaults/networks
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEYParameters
limit
: integer (optional) - Limits the number of results returned.page
: integer (optional) - Specifies the page number of results to return.sort_key
: string (optional) - Sort results by one of the following:id
.search
: string (optional) - Searches byname
,symbol
.filters
(optional)type
: enum - Type of the network, one ofPUBLIC, PRIVATE.
status
: enum - Status of the network, one ofACTIVE, HOLD
.is_testnet
: boolean - Indicates if the network is a testnet.
Success Response:
Code: 200
Content
Example:
{
"message": "Vault Networks",
"data": [
{
"name": "Ethereum",
"logo": "https://api-super-admin-custody-dev.roxcustody.io/public/files/biconomy-assets/ethereum.png",
"symbol": "ETH",
"id": 1
}
],
"meta": {
"totalItems": 1,
"itemsPerPage": 10,
"totalPages": 1,
"currentPage": 1,
"hasPreviousPage": false,
"hasNextPage": false
}
}
Payment Policy
Get Payment Policy
Returns the current payment policy of the vault and its ranges and assigned approvals per range.
URL
/vaults/payment-policy
Method:
GET
Headers
X-API-KEY:
YOUR-API-KEY
Success Response:
Code: 200
Content:
{
"message": "Vault Payment Policy",
"data": {
"paymentPolicy": {
"id": 7,
"ranges": [
{
"id": 4,
"from": 0,
"to": 10000,
"dailyLimit": 100000,
"created_at": "17 November, 2024 13:47:09",
"updated_at": "18 November, 2024 17:15:00",
"paymentPolicyRangeType": "approvals",
"minimumNumberOfApprovals": 1
}
],
"created_at": "17 November, 2024 13:47:09",
"updated_at": "17 November, 2024 13:47:09"
}
}
}
Error Codes
400 Bad Request
: The request was invalid or cannot be served. Check the error message for more details.401 Unauthorized
: The request requires authentication.403 Forbidden
: The request was valid, but the server is refusing action. You might not have the necessary permissions.404 Not Found
: The requested resource could not be found.422 Unprocessible entity
: The request was well-formed but could not be followed due to semantic errors.500 Internal Server Error
: An error occurred on the server.
Support
If you have any questions or need further assistance, please contact our support team at [email protected].
Last updated