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:

Code: 422
Content

{
    "status": 422,
    "message": "Client with Id X already exists",
    "errors": {
        "message": "Client with Id X already exists",
        "error": "Client with Id X already exists"
    }
}

Wallets

Get All Clients' wallets

Returns all the clients' wallets for each of the integrated blockchains.

URL
/vaults/client-wallets
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

Success Response:

Code: 200
Content

{
    "message": "Clients' Wallets",
    "data": [
        {
            "id": 74,
            "balance": 1,
            "public_address": "0xCDc1c9B8E1A8B0e1533B0e4587454C2dd76f4A88",
            "client": {
                "external_id": "eslam",
                "id": "eslam"
            },
            "asset": {
                "id": 1,
                "name": "Ethereum",
                "symbol": "ETH",
                "contract_address": null,
                "type": "COIN",
                "status": "ACTIVE",
                "logo": "https://api-super-admin-custody-test.roxcustody.io/public/files/biconomy-assets/ethereum.png"
            },
            "formatted_balance": 1
        },
        {
            "id": 73,
            "balance": 0.9,
            "public_address": "0xCDc1c9B8E1A8B0e1533B0e4587454C2dd76f4A88",
            "client": {
                "external_id": "eslam",
                "id": "eslam"
            },
            "asset": {
                "id": 2,
                "name": "TETHER USD",
                "symbol": "USDT",
                "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
                "type": "TOKEN",
                "status": "ACTIVE",
                "logo": "https://api-super-admin-custody-test.roxcustody.io/public/files/biconomy-assets/tether.png"
            },
            "formatted_balance": 0.9
        },
    ]
}

Get One Wallet Balance

Returns the balance of one wallet.

URL
/wallets/balance/:wallet_id
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
URL Parameters
wallet_id = number

Success Response:

Code: 200
Content:

{
    "message": "Wallet balance",
    "data": 222,            //number
    "status": 200
}

Error Response:

Invalid API Key:

Code: 403

Example:

{
    "status": 403,
    "message": "Invalid API Key",
    "errors": {
        "message": "Invalid API Key",
        "error": "Forbidden",
        "statusCode": 403
    }
}

Error Response:

Not Existing Wallet:

Code: 422

Example:

{
    "status": 422,
    "message": "Can't find wallet with id 553",
    "errors": {
        "message": "Can't find wallet with id 553"
    }
}

Error Response:

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"
    }
}

Get Vault Master Wallets Balances

Returns the balances of the vault's master wallets.

URL
/wallets/master-wallets
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

Success Response:

Code: 200
Content:

{
    "data": [ // array of objects
        {
            "id": 54, // number
            "balance": 0, // number
            "public_address": "0x467b9d8320BDb778117E750327877CC18ed50030", // string
            "transactions_count": "0", // string
            "gas_station_category_id": null, // string
            "client": null, // string
            "formatted_balance": 0 // number
        },
        {
            "id": 55, // number
            "balance": 222, // number
            "public_address": "0x467b9d8320BDb778117E750327877CC18ed50030", // string
            "transactions_count": "0", // string
            "gas_station_category_id": null, // string
            "client": null, // string
            "formatted_balance": 222 // number
        },
        {
            "id": 53, // number
            "balance": 0, // number
            "public_address": "0x467b9d8320BDb778117E750327877CC18ed50030", // string
            "transactions_count": "0", // string
            "gas_station_category_id": null, // string
            "client": null, // string
            "formatted_balance": 0 // number
        }
    ],
    "meta": { // object
        "totalItems": 3, // number
        "itemsPerPage": 10, // number
        "totalPages": 1, // number
        "currentPage": 1, // number
        "hasPreviousPage": false, // boolean
        "hasNextPage": false // boolean
    }
}

Error Response:

Invalid API Key:

Code: 403

Example:

{
    "status": 403,
    "message": "Invalid API Key",
    "errors": {
        "message": "Invalid API Key",
        "error": "Forbidden",
        "statusCode": 403
    }
}

Get Gas Station Wallets Balances

Returns the gas station wallets balances and addresses.

URL
/wallets/gas-station-wallets
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

Success Response:

Code: 200
Content:

{
    "message": "Gas station wallets", // string
    "data": [ // array of objects
        {
            "id": 52, // number
            "balance": 0, // number
            "public_address": "0xdEbEa0D4053BD874804272d878e453888aD3E803", // string
            "asset": { // 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)
            },
            "formatted_balance": 0 // number
        }
    ],
    "meta": { // object
        "totalItems": 1, // number
        "itemCount": 1, // number
        "itemsPerPage": 1, // number
        "totalPages": 1, // number
        "currentPage": 1 // number
    },
    "status": 200 // number
}

Error Response:

Invalid API Key:

Code: 403

Example:

{
    "status": 403,
    "message": "Invalid API Key",
    "errors": {
        "message": "Invalid API Key",
        "error": "Forbidden",
        "statusCode": 403
    }
}

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"    //string
}

Error Response:

Invalid API Key:

Code: 403

Example:

{
    "status": 403,
    "message": "Invalid API Key",
    "errors": {
        "message": "Invalid API Key",
        "error": "Forbidden",
        "statusCode": 403
    }
}

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-KEY
URL Parameters
Required:
transaction_id=[string]

Success Response:

Code: 200
Content:

{
    "message": "Transaction", // string
    "data": { // object
        "id": "15", // string
        "amount": "0.10000000000000000000", // string
        "fees": "0.00000000246612892600", // string
        "sender_address": "0xCDc1c9B8E1A8B0e1533B0e4587454C2dd76f4A88", // string
        "receiver_address": "0xQABAkAgkuLEHLaqkWhLgNKagSajeobLS3rPT0Agm0f7k55FXVt743ha", // string
        "encoded_payload": null, // string
        "note": null, // string
        "call_method": null, // string
        "asset": { // object
            "id": 2, // number
            "name": "TETHER USD", // string
            "symbol": "USDT", // string
            "network": { // object
                "id": 1, // number
                "name": "Ethereum", // string
                "symbol": "ETH", // string
                "type": "PUBLIC", // string
                "logo": "https://api-super-admin-custody-test.roxcustody.io/public/files/biconomy-assets/ethereum.png" // URL (string)
            },
            "type": "TOKEN", // 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
        "transaction_hash": null, // string
        "status": "PENDING" // string
    },
    "status": 200 // number
}

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-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

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-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

Success Response:

Code: 200
Content:

{
    "message": "Vault Approvals", // string
    "data": [                    // array of objects
        {
            "id": 4,             // number
            "name": "Approval",  // string
            "email": "approval@rox.com", // string
            "role": {           // object
                "id": 2,       // number
                "name": "Approval", // string
                "isSystemRole": true, // boolean
                "permissions": {} // object (empty)
            },
            "vaults": [         // array of objects
                {
                    "id": 17, // number
                    "name": "alaa11" // string
                }
            ],
            "status": "active", // string
            "logo": null,       // string
            "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
}

URL
/vaults/assets
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
URL Parameters
filters[network_id] = Integer

Success Response:

Code: 200
Content:

{
    "message": "Vault Assets", // string
    "data": [                  // array of objects
        {
            "id": 1,           // number
            "name": "Ethereum", // string
            "symbol": "ETH",   // 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.io/public/files/biconomy-assets/ethereum.png" // URL (string)
        },
        {
            "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.io/public/files/biconomy-assets/ethereum.png" // URL (string)
            },
            "logo": "https://api-super-admin-custody.io/public/files/biconomy-assets/tether.png" // URL (string)
        }
    ],
    "meta": {                  // object
        "totalItems": 2,       // number
        "itemsPerPage": 10,    // number
        "totalPages": 1,       // number
        "currentPage": 1,      // number
        "hasPreviousPage": false, // boolean
        "hasNextPage": false   // boolean
    },
    "status": 200              // number
}

Assets

Get One Asset Gas Price

Returns the current gas price for transactions of the specified asset.

URL
/assets/gas-price/:asset_id
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
URL Parameters
asset_id=[integer]

Success Response:

Code: 200
Content:

{
  "message": "Asset gas price", // string
  "data": {                     // object
    "gas_price": 1.315127193e-9 // number
  },
  "status":

Error Response:

Code: 404
Content:

{
    "status": 404,
    "message": "Can't find asset with id 992",
    "errors": {
        "message": "Can't find asset with id 992"
    }
}

Get All Networks

Returns the current networks.

URL
/vaults/networks
Method:
GET
Headers
X-API-KEY: YOUR-API-KEY
Parameters
- limit: integer (optional) - Limits the number of results returned.
- page: integer (optional) - Specifies the page number of results to return.

Success Response:

Code: 200
Content

Example:

{
    "message": "Vault Networks",           // String
    "data": [                              // Array of objects
        {
            "vault_id": 2,                 // Integer
            "network_id": 1,               // Integer
            "name": "Ethereum",            // String
            "logo": "URL link",            // URL (String)
            "symbol": "ETH"                // String
        },
        {
            "vault_id": 3,                 // Integer
            "network_id": 1,               // Integer
            "name": "Ethereum",            // String
            "logo": "URL link",            // URL (String)
            "symbol": "ETH"                // String
        }
    ],
    "meta": {                              // Object
        "totalItems": 23,                  // Integer
        "itemsPerPage": 2,                 // Integer
        "totalPages": 12,                  // Integer
        "currentPage": 1,                  // Integer
        "hasPreviousPage": false,          // Boolean
        "hasNextPage": true                // Boolean
    },
    "status": 200                          // Integer
}

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", // string
  "data": {                        // object
    "paymentPolicy": {             // object
      "id": 15,                   // number
      "vault_id": 17,             // number
      "ranges": [                 // array
        {
          "id": 15,              // number
          "payment_policy_id": 15, // number
          "from": 0,             // number
          "to": 100000,          // number
          "dailyLimit": 2000000, // number
          "paymentPolicyRangeType": "approvals", // string
          "minimumNumberOfApprovals": 1 // number
        }
      ]
    }
  },
  "status": 200 // number
}

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 support@custodyprovider.com.

PreviousGet Started

Last updated 1 month ago