Rest API

The CoKeeps Hot Wallet base URL will be provided to you during the integration phase. Throughout this document, we refer to this value as <ck_hotwallet_url>.

All requests sent to and responses received from <ck_hotwallet_url> must use the encryption scheme described in the Data Encryption section. Please ensure you follow those instructions when encrypting request payloads and decrypting response payloads.

Utilities

Get Available Chains

This REST API returns the list of all supported networks and their associated assets (network-native assets and tokens) that can be used across most CoKeeps Hot Wallet operations.

Please note that the desired networks must first be enabled by an Authoriser via the CoKeeps Client Administration platform before they can be used with the Hot Wallet.

Endpoint: <ck_hotwallet_url>/service/utility/chains

Request payload:

{} // Empty object

Response payload example:

{
    "success": true,
    "message": "Available chains",
    "ciphertext": {
        "chains": [
            // -- Snip --
            {
                "id": "bitcoin",
                "name": "Bitcoin Mainnet",
                "base": "bitcoin",
                "currency": "Bitcoin",
                "symbol": "BTC",
                "decimals": 8,
                "token": null
            }
            // -- Snip --
        ]
    }
}

Validate Address

You can use this REST API to validate whether a given address is valid for a specific supported network.

Endpoint: <ck_hotwallet_url>/service/utility/validate

Request payload:

{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "chain_id": "bitcoin"
}

Response payload example:

{
  "success": true,
  "message": "OK"
}

Monitor Address

Use this REST API to register an address for activity monitoring. Once registered, you will receive webhook notifications whenever new incoming or outgoing transactions occur on that address.

IMPORTANT

Only addresses generated within the CoKeeps platform are eligible for monitoring.

Endpoint: <ck_hotwallet_url>/service/utility/monitor

Request payload:

NOTE

The alert options operate independently of the confirmation count.

{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "chain_id": "bitcoin",
    "webhookUrl": "https://ck-webhook.example.com",
    "options": {
        "confirmations": 3,
        "alert": {
            "lowerThan": "10.0",
            "higherThan": "0.1"
        }
    }
}

• To update a configuration: Resubmit the monitoring configuration with the same address and chain_id, including any updated parameters.
• To disable monitoring: Set the status field to "inactive".
• To re-enable monitoring: Set the status field to "active" and include all required monitoring parameters in your request.

Example update request payload to deactivate monitoring:

{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "chain_id": "bitcoin",
    "status": "inactive"
}

Example response payload:

{
  "success": true,
  "message": "Monitor address",
  "rdata": {
    "monitor_id": "6842a1800243eec797c9b840"
  }
}

Example notification payload:

{
    "chain": {
        "address": "0x51B2057D2216e7f741728C058635E3524A5E6A5C",
        "name": "Optimism Sepolia",
        "id": "optimismsepolia",
        "symbol": "OPETH"
    },
    "balances": {
        "hex": "0x497407837458612564",
        "int": "497407837458612564",
        "opeth": "0.497407837458612564"
    },
    "balance": "0.497407837458612564",
    "options": {
        "confirmations": 3,
        "alert": {
            "higherThan": "0"
        }
    }
}

Check API Usage

This REST API allows you to query your current Hot Wallet API usage and remaining balance.

Endpoint: <ck_hotwallet_url>/service/utility/usage

Request payload:

{} // Empty object

Response payload example:

{
  "success": true,
  "message": "OK",
  "ciphertext": {
      "quota": 10000,
      "balance": 9990
  }
}

• quota: Total API call allocation for your plan or period.
• balance: Remaining number of API calls available.

Lookup Address

This REST API lets you query the on-chain balance and transaction history of an address.

NOTE

Only addresses generated within the CoKeeps platform can be queried, and this endpoint consumes API usage.

Endpoint: <ck_hotwallet_url>/service/utility/lookup/address

Request payload:

{
    "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "chain_id": "bitcoin"
}

• address: The on-chain address you want to inspect.
• chain_id: The network identifier (e.g. bitcoin, optimismsepolia).

Response payload example:

{
  "success": true,
  "message": "Address lookup",
  "ciphertext": {
    "address": "0x56F17393Ad0Ebf06A10c5B13c4bc9b3E86E4a3",
    "chain_id": "optimismsepolia",
    "data": {
      "balances": {
        "hex": "0x313032333930363234303139353438383036",
        "int": "102390624019548806",
        "opeth": "0.102390624019548806"
      },
      "txs": 5,
      "balance": "0.102390624019548806",
      "transactions": [
        // -- Snip --
        {
          "txid": "0x7f1cf619fb6de2b8784b0ba0b36c9cd310377c866ec41ba2e07224d039872aad",
          "ts": 1725216058000,
          "ago": "10 hours ago",
          "confirmations": 17367,
          "from": "0x1450ac98fbd4EA6C4DFF1257eD8958210b07a8a1",
          "to": "0x56F17393Ad0Ebf06A10c5B13c4bc9b3E86E4a3Cb",
          "incoming": true,
          "outgoing": false,
          "value": "0.0",
          "fee": "0.000126490612667234",
          "block": 16706759,
          "values": {
            "int": "0",
            "hex": "30",
            "opeth": "0.0"
          },
          "fees": {
            "int": "126490612667234",
            "hex": "313236343930363132363637323334",
            "opeth": "0.000126490612667234"
          }
        },
        // -- Snip --
    }
  }
}

Lookup Transaction

This REST API allows you to retrieve on-chain transaction details for a specific transaction hash.

NOTE

This endpoint consumes API usage.

Endpoint: <ck_hotwallet_url>/service/utility/lookup/tx

Request payload:

{
    "hash": "0x31c13576a11ba5bb8c068e48c35bcbeffc2306aafbfe8700cf4804909f75acaf",
    "chain_id": "optimismsepolia"
}

• hash: The transaction hash (txid) you want to look up.
• chain_id: The network identifier (e.g. optimismsepolia, bitcoin, etc.).

Response payload example:

{
  "success": true,
  "message": "Transaction lookup",
  "ciphertext": {
    "hash": "0x7f1cf619fb6de2b8784b0ba0b36c9cd310377c866ec41ba2e07224d039872aad",
    "chain_id": "optimismsepolia",
    "data": {
      "_type": "TransactionResponse",
      "accessList": [],
      "blockNumber": 16706759,
      "blockHash": "0x482987bff5a8bc08b96d8f674a617f8cc3c724fa183ea7823c430c29df60e832",
      "blobVersionedHashes": null,
      "chainId": "11155420",
      "data": "0xa0ab96530000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000001c0000000000000000000000000eebc79003a9f623a63d77a43276781fbf464bd0c0000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000002200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c3500000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001b000000000000000000000000000000000000000000000000000000000000001c000000000000000000000000000000000000000000000000000000000000000291d0444645be4e6ccf2d6f2b9b7f6453a5db792053fbde4fde8d51cf551c5c6ac1f9e71bcb2e6d88a25045b32a367a289021e773805f264221ee684224ba403900000000000000000000000000000000000000000000000000000000000000027c75eca3d527450039acff2ca099b18a38b5d7915f403e792a361dc65f40ad1505f76160bdc927bd780548dfc0aefc8ee0e259331bb8d8966bc90bc5536c14a40000000000000000000000000000000000000000000000000000000000000000",
      "from": "0x1450ac98fbd4EA6C4DFF1257eD8958210b07a8a1",
      "gasLimit": "108964",
      "gasPrice": "1000000272",
      "hash": "0x7f1cf619fb6de2b8784b0ba0b36c9cd310377c866ec41ba2e07224d039872aad",
      "maxFeePerGas": "1000000542",
      "maxPriorityFeePerGas": "1000000000",
      "maxFeePerBlobGas": null,
      "nonce": 9,
      "signature": {
        "_type": "signature",
        "networkV": null,
        "r": "0xb897078e943011fefba85687bf0e33ad3182058cec0012ebfb28025f279310ee",
        "s": "0x29f99dd074c070904200657dbccc371068057aca9e97a8a5966eaf7d7b5c2127",
        "v": 28
      },
      "to": "0x56F17393Ad0Ebf06A10c5B13c4bc9b3E86E4a3Cb",
      "index": 1,
      "type": 2,
      "value": "0"
    }
  }
}

Smart Contract Information Lookup

Use this REST API to retrieve all readily available metadata and basic information about a smart contract without providing any function inputs.

IMPORTANT

Only smart contracts that have been deployed or imported within the CoKeeps platform can be queried.

Endpoint: <ck_hotwallet_url>/service/utility/lookup/smart-contract/info

Request payload:

{
  "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
  "chain_id": "eth"
}

• address: The on-chain address of the smart contract.
• chain_id: The network identifier where the contract is deployed.

Response payload example:

{
  "success": true,
  "message": "Smart Contract Info",
  "ciphertext": {
    "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
    "chain_id": "662131dc4d81090013d9fdd4",
    "data": [
      // -- Snip --
      {
        "name": "decimals",
        "value": "18",
        "text": "Decimals"
      },
      {
        "name": "name",
        "value": "Uniswap",
        "text": "Name"
      },
      {
        "name": "symbol",
        "value": "UNI",
        "text": "Symbol"
      },
      {
        "name": "totalSupply",
        "value": "1000000000000000000000000000",
        "text": "Total Supply"
      }
      // -- Snip --
    ]
  }
}

The contents are derived from the smart contract's ABI.

Smart Contract Read Method

Use this REST API to call a read-only function on a smart contract and retrieve its return value.

IMPORTANT

Only smart contracts that have been deployed or imported within the CoKeeps platform can be queried.

Endpoint: <ck_hotwallet_url>/service/utility/lookup/smart-contract/read

Request payload:

{
  "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
  "chain_id": "eth",
  "functionName": "balanceOf",
  "inputs": [ "0x1426f9c9CD9532D4Fdb66D4EE88d6Df94CDa436a" ]
}

• address: Smart contract address.
• chain_id: Network identifier where the contract is deployed.
• functionName: Name of the read method to call (for example, balanceOf).
• inputs: Array of function arguments in the order defined by the contract ABI.

NOTE

Valid functionName values (and their inputs) can be obtained via the Smart Contract Lookup Interface endpoint.

Response payload example:

{
  "success": true,
  "message": "Smart Contract Read",
  "ciphertext": {
    "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
    "chain_id": "eth",
    "data": {
      "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
      "chain_id": "662131dc4d81090013d9fdd4",
      "result": {
        "name": "balanceOf",
        "value": "5490000000000000000",
        "text": "Balance Of"
      }
    }
  }
}

The structure and meaning of result are derived from the smart contract's ABI and the function you have called.

Smart Contract Lookup Interface

Use this REST API to retrieve the available methods of a smart contract, separated by type (read or write).

IMPORTANT

Only smart contracts that have been deployed or imported within the CoKeeps platform can be queried.

Endpoint: <ck_hotwallet_url>/service/utility/lookup/smart-contract/interface/<method>

Where <method> is either:

• read: to list read-only / view functions, or
• write: to list state-changing functions.

Request payload:

{
  "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
  "chain_id": "eth"
}

• address: Smart contract address.
• chain_id: Network identifier where the contract is deployed.

Response payload example:

{
  "success": true,
  "message": "Smart Contract Interface",
  "ciphertext": {
    "address": "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984",
    "chain_id": "eth",
    "data": [
      // -- Snip --
      {
        "inputs": [
          {
            "internalType": "address",
            "name": "account",
            "type": "address"
          }
        ],
        "name": "balanceOf",
        "outputs": [
          {
            "internalType": "uint256",
            "name": "",
            "type": "uint256"
          }
        ],
        "type": "function",
        "text": "Balance Of"
      }
      // -- Snip --
    ]
  }
}

The entries are derived directly from the contract's ABI, and describe each available function's:

• name: Function name (e.g. balanceOf)
• inputs: Parameter types and names
• outputs: Return value types
• type: Typically function for standard ABI entries
• text: A human-readable label suitable for UI display

Information

List Hot Wallet Users

This REST API returns a paginated list of all users registered in the CoKeeps Hot Wallet system.

Endpoint: <ck_hotwallet_url>/service/information/users

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Users",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "_id": "65d9e68190c3fe00139e2dff",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "created": "2024-02-24T12:52:17.068Z",
        "lastModified": "2024-03-10T08:53:52.041Z",
        "resetCount": 0
      },
      // -- Snip --
    ],
    "found": 3,
    "total": 3
  }
}

• data: Array of user records returned for the current page.
• found: Number of records returned in this page.
• total: Total number of matching users in the system (across all pages).

List Destinations

This REST API returns a paginated list of all destination addresses that have been set by Hot Wallet users (including their approval and Travel Rule metadata, where applicable).

Endpoint: <ck_hotwallet_url>/service/information/destinations

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Destinations",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "_id": "65f29d1aa3db1a0013e9653f",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "data": {
          "chain_id": "bitcoin",
          "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
          "approval": {
            "uid": "65abefd6f6539a0018798e74",
            "signature": "637b9be6f950135997306976c6dea4d1bc956c17b985194ee7398697949e8b07798eba71eb37becca027ceacd55c1ebc67131a98bf0f30fa8b6ae9c7df42ae0762326431356331376431663263646530343564373331336461616666396437663437613962386364343336373133313661663430633734663330613931643539",
            "remark": "Compliance ID: 123-ABC",
            "destination_id": "65f29d1aa3db1a0013e9653f",
            "ts": "2024-03-15T19:43:21.514Z",
            "sbdv": true
          },
          "rejection": null,
          "travelRuleId": "65f29d1aa3db1a0013e9653e",
          "travelRule": {
            "type": "self-hosted",
            "typeName": "Ledger",
            "name": "Satoshi Nakamoto",
            "country": "Unknown",
            "caddress": false,
            "contact": false,
            "email": false,
            "reference": false
          }
        },
        "created": "2024-03-14T06:45:46.178Z",
        "lastModified": "2024-03-15T19:43:21.518Z",
        "sbdv": true
      },
      // -- Snip --
    ],
    "found": 3,
    "total": 3
  }
}

• data: Array of destination records for the current page. Each entry includes:
  • The owning user (uid),
  • The destination address and chain_id,
  • Approval details (who approved, when, and associated SBDV status), and
  • Travel Rule information (where collected).
• found: Number of records returned in this page.
• total: Total number of matching destination records across all pages.

List Travel Rules

This REST API returns a paginated list of all Travel Rule records submitted by Hot Wallet users.

Endpoint: <ck_hotwallet_url>/service/information/travel-rule

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Travel Rules",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "_id": "65f29d1aa3db1a0013e9653e",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "created": "2024-03-14T06:45:46.175Z",
        "data": {
          "chain_id": "bitcoin",
          "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
          "signature": "810d8c8a98780ae17281c96af89e5f02d44bdd29326b4ecdbcaeb51c672466cdeb1af990a9c2269f08d4576fcca2dda6709ed46871c3570ab1ca31e252daed0137306165393035366337656363326238656332643834306562626633306430353639383137616132663463316664343563343732356236636665353139313433",
          "type": "self-hosted",
          "typeName": "Ledger",
          "addressSignature": "KMB9hTRwUt0vc+Nkal/zgPTQxVT/OmcUPq3YylCMq2leU/qV36UxSItLlzXPuH27VWkKwfNgI3DQ6kGdws0SiZE=",
          "addressSignatureInput": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
          "name": "Satoshi Nakamoto",
          "country": "Unknown",
          "caddress": false,
          "contact": false,
          "email": false,
          "reference": false,
          "approval": {
            "uid": "5d9aa207-d44f-4913-8d68-ec27be30e841",
            "signature": "637b9be6f950135997306976c6dea4d1bc956c17b985194ee7398697949e8b07798eba71eb37becca027ceacd55c1ebc67131a98bf0f30fa8b6ae9c7df42ae0762326431356331376431663263646530343564373331336461616666396437663437613962386364343336373133313661663430633734663330613931643539",
            "remark": "Compliance ID: 123-ABC",
            "destination_id": "65f29d1aa3db1a0013e9653f",
            "ts": "2024-03-15T19:43:21.514Z",
            "sbdv": true
          },
          "rejection": null
        },
        "hash": "332bd95e63dee5b7e85aa4bcb776579555f31d3c8eb0930e758fa6ba3005284a",
        "lastModified": "2024-03-15T19:43:21.516Z",
        "sbdv": true
      },
      // -- Snip --
    ],
    "found": 3,
    "total": 3
  }
}

• data: Array of Travel Rule records for the current page, including:
  • The owning user (uid),
  • Network and address details,
  • Collected Travel Rule attributes (e.g. type, name, country, proofs),
  • Approval / rejection metadata and SBDV status.
• found: Number of records returned in this page.
• total: Total number of matching Travel Rule records across all pages.

List Pending Reviews

This REST API returns a paginated list of all Pending Review entries that have been created by users and are subject to administrative or compliance review (e.g. transfers, or other reviewable actions).

Endpoint: <ck_hotwallet_url>/service/information/reviews

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Reviews",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
          "rid": "682281461ff5d617d2eae8c0",
          "from": "0x43103e8b26f04915d22C24F5A1c1BCC62d1A65e3",
          "to": "0x1450ac98fbd4EA6C4DFF1257eD8958210b07a8a1",
          "uid": "5d9aa207-d44f-4913-8d68-ec27be30e841",
          "chain_id": "78ef6ee84c3764df81a7a6325a7aa1a9d0588f5038ed1bfbfb717ddf45a2b249",
          "status": "rejected",
          "amount": "30.12",
          "scope": "signer-wallet",
          "reference_id": "abc123",
          "allocationName": "transfer-tx",
          "reviewerUid": "c80df78a-95ef-4717-8c0d-081fcb352994",
          "created": "2025-05-08T23:16:22.439Z",
          "lastModified": "2025-05-08T23:16:55.509Z",
          "expiry": "2025-05-11T23:16:22.438Z"
      },
      // -- Snip --
    ],
    "found": 3,
    "total": 3
  }
}

Typical fields in each review record include:

• rid: Review ID.
• from / to: Source and destination addresses involved in the operation.
• uid: UUID of the user who initiated the request.
• chain_id: Network associated with the request.
• status: Current review status (e.g. pending, approved, rejected).
• amount: Requested amount for the operation.
• scope: Context of the operation (e.g. signer-wallet, omnibus).
• reference_id / allocationName: Identifiers used to correlate with your internal records or flows.
• reviewerUid: UUID of the reviewer (if already processed).
• created / lastModified / expiry: Timestamps for creation, last update, and optional expiry of the review.

List Accounts

This REST API returns a paginated list of accounts for a given account type.

Endpoint: <ck_hotwallet_url>/service/information/accounts/<type>

Where <type> can be:

• wallet: for Signer Wallet accounts
• deposit: for Deposit accounts

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Deposit accounts",
  "ciphertext": {
    "data": [
      // -- Snip -- 
      {
        "_id": "65d9e68190c3fe00139e2dff",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "role": "signer",
        "deposit": {
          "bitcoin": {
            "address": "bc1qmq9yj7gs69p7d0v67df7cfxlgpu8vm68s9m8m4",
            "balances": {
              "hex": "0x0",
              "int": "0",
              "btc": "0"
            },
            "pending": {
              "hex": "0x0",
              "int": "0",
              "btc": "0"
            },
            "txs": 0,
            "balance": "0"
          }
        }
      }
      // -- Snip -- 
    ],
    "found": 3,
    "total": 3
  }
}

• data: Array of account records for the current page (structure varies slightly by type, e.g. wallet vs deposit).
• found: Number of records returned in this page.
• total: Total number of matching account records across all pages.

List Transactions

This REST API returns a paginated list of service transactions recorded by the CoKeeps Hot Wallet.

Endpoint: <ck_hotwallet_url>/service/information/transactions/<type>

Where <type> can be one of:

• transfer
• interact
• sweep-deposit
• sweep-withdrawal
• sweep-gas-station
• sweep-signer-wallet-bases
• gas-station
• rebalance

Request payload:

{
  "params": {
    // Obtain from SDK, eg:
    reference_id: "abc-123"
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Sweep deposits",
  "ciphertext": {
    "data": [
      // -- Snip -- 
    {
        "tid": "665860b206e4170013a10f85",
        "from": "0xcDD721f711D952A0DA6e7C53AeD034152e0dE772",
        "to": "0x27F34B3e1A43b3147820abaA3e9C843eD6aAB9E5",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "purpose": "wallet",
        "chain_id": "78ef6ee84c3764df81a7a6325a7aa1a9d0588f5038ed1bfbfb717ddf45a2b249",
        "reference_id": "abc123",
        "status": "completed",
        "amount": "0.01",
        "txid": "0xeb0becab6a49cfeb6e9ec9adef878acdaf1e70fce13dd5cb3bca2c32fbcc32b0", // false(boolean) if it is not added to the block
        "created": "2024-05-30T11:19:14.122Z",
        "lastModified": "2024-05-30T11:38:00.194Z", // Only when updated
        "errors": [
            {
                "ts": "2024-05-30T11:24:12.101Z",
                "message": "Insufficient fund."
            }
        ] // Or `null` if no error
    }
      // -- Snip -- 
    ],
    "found": 3,
    "total": 3
  }
}

• data: Array of transaction records for the current page.
• found: Number of records returned in this page.
• total: Total number of matching transactions across all pages.

Transaction status behaviour (Important)

Each transaction has one of four possible status values:

• completed: The transaction has been successfully submitted to the mempool (broadcast to the network but not necessarily included in a block yet). In this state, txid will contain a transaction hash.
• pending: The transaction is still in CoKeeps' internal queue and has not yet been broadcast to the network.
• error: An error occurred while processing or broadcasting the transaction. Your backend will be notified via the Update endpoint. The Hot Wallet machine will automatically retry transactions in this state every 5 minutes, up to 5 attempts.
• exit: All retry attempts for a previously failing transaction have been exhausted and the system has stopped retrying. Manual follow-up may be required.

These statuses should be carefully considered when:

• Displaying transaction information to users, and
• Calculating or exposing balances that affect withdrawal limits or risk decisions.

NOTE

To confirm whether a transaction has actually been included in a block, use the Lookup Transaction API and verify that a valid blockNumber (or equivalent) is present.

List Monitored Address

This REST API returns a paginated list of all addresses that have been registered for monitoring.

Endpoint: <ck_hotwallet_url>/service/information/monitor

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Monitored addresses",
  "ciphertext": {
    "data": [
      // -- Snip -- 
      {
         "mid": "6841b727f5a5dbd9e3b469c8",
         "address": "0x8c746C3E0fAdE49c061B0E9883153c82e06FDaA1",
         "chain_id": "bsctestnet",
         "webhookUrl": "https://mybackend.com/test/webhook",
         "status": "active",
         "confirmations": 1,
         "higherThan": "0.00001",
         "lowerThan": "90000.0",
         "created": "2024-05-30T11:19:14.122Z",
         "lastModified": "2024-05-30T11:38:00.194Z"
      }
      // -- Snip -- 
    ],
    "found": 3,
    "total": 3
  }
}

Each record includes:

• mid: Unique identifier of the monitor configuration.
• address: On-chain address being monitored.
• chain_id: Network identifier for the monitored address.
• webhookUrl: URL where webhook notifications will be sent when activity matches the configured criteria.
• status: Current monitoring status (e.g. active or inactive).
• confirmations: Minimum number of block confirmations required before a notification is triggered.
• higherThan: Optional upper threshold; alerts are triggered when the balance is greater than this value.
• lowerThan: Optional lower threshold; alerts are triggered when the balance is less than this value.
• created: Timestamp indicating when the monitor was created.
• lastModified: Timestamp indicating when the monitor configuration was last updated.

Dynamic Transaction Pool

Retrieve Integrated Accounts

This endpoint is used in the Dynamic Transaction Pool for omnibus withdrawals that are executed via multi-signature accounts. Given a pool_id (generated when a user submits a withdrawal request via CKSDK), it returns the relevant omnibus multi-signature account information. You can use this data to drive your approval or rejection workflows, or simply to retrieve details for monitoring and reporting purposes.

Endpoint: <ck_hotwallet_url>/service/pool/integrated-accounts

Request payload:

{
  "pool_id": "string"
}

• pool_id: Identifier of the Omnibus withdrawal record you want to inspect.

Response payload example:

{
  "success": true,
  "message": "Pool integrated accounts",
  "ciphertext": [
    {
      "address": "AS1yfbX6dx9dJd8fiey3uc22anb6KGZz6USSB8zmGW92",
      "chain_id": "solanadevnet",
      "withdrawal": true,
      "sweepDestination": false,
      "writeAction": true,
      "writeActionInstruction": [
        {
          "address": "7WqErRX6pF6nUxZaaYHLWkWdM5Xeiu977Rjonpa4BeH6",
          "chain_id": "solanadevnet",
          "instructions": [
            {
              "method": "transferChecked",
              "withdrawalAlias": true
            }
          ]
        }
      ],
      "shared": {
        "_id": "6607f0d438df6e00132defdd",
        "label": "Solana MS",
        "chain_id": "solanadevnet",
        "address": "AS1yfbX6dx9dJd8fiey3uc22anb6KGZz6USSB8zmGW92",
        "total": "3",
        "needed": "2",
        "members": [
          {
            "address": "ECsDGeXFjxXDFSDJZbEF67DK28CFSWmB8xKksusAZck",
            "input": "ECsDGeXFjxXDFSDJZbEF67DK28CFSWmB8xKksusAZck",
            "linked": false
          },
          {
            "address": "CAMmmhXUgqmFqERQkPVsTc77ECf1uUdGWUzboarnrxb7",
            "input": "CAMmmhXUgqmFqERQkPVsTc77ECf1uUdGWUzboarnrxb7",
            "linked": false
          },
          {
            "address": "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
            "input": "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
            "linked": "655f29b5a9d8900019c65a6a"
          }
        ],
        "meta": {
          "multisigPublicKey": "5ywqMepwADm72e55zcfXG13NtTSrtZAEjxBF4urLLegQ",
          "multisigSignerPublicKey": "AS1yfbX6dx9dJd8fiey3uc22anb6KGZz6USSB8zmGW92",
          "version": "v1",
          "programId": "6dL7oBn5EmyZVYh55Kh6xkJ8fJ5vd7LAt28EyKZXg3ZD"
        },
        "spl": {
          "address": "A9rkBicskJBTZwRkbTMQUFRA9PU19nLi26vT3dhZHT35",
          "multisigPublicKey": "A9rkBicskJBTZwRkbTMQUFRA9PU19nLi26vT3dhZHT35"
        }
      },
      "data": {
        "txs": 19,
        "balances": {
          "hex": "10c32fa15",
          "int": 4499634709,
          "sol": "4.499634709"
        },
        "balance": "4.499634709"
      }
    }
  ]
}

You can summarise the main fields as:

• address: The on-chain address of the integrated account.
• chain_id: Network identifier for this account.
• withdrawal: Indicates whether this account is configured as a Withdrawal account in this pool context.
• sweepDestination: Indicates whether this account is a sweep target (e.g. a Holding or omnibus destination).
• writeAction: Indicates whether additional write actions (e.g. smart contract calls) are associated with this account.
• writeActionInstruction: List of downstream instructions (such as token transfers) that will be executed from this account.
• shared: Metadata describing the underlying multi-signature account (label, threshold, member list, and chain-specific configuration).
• data: Current operational data for this account, including transaction count (txs) and balances for the address.

List Transactions

Use this REST API to retrieve a paginated list of all transactions recorded in the Dynamic Transaction Pool.

Endpoint: <ck_hotwallet_url>/service/pool/tx

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Pool transaction",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "_id": "66228d8e4f07ea0013fb9eb6",
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "chain_id": "solanadevnet",
        "amount": "0.003",
        "type": "withdrawal",
        "reference_id": "2024-03-21_ABC-123",
        "to": "J6pZKwXQhbA7WEKKBc2cY7gFSLyAyJNUkpetsZDFTpjp",
        "hash": "a5367428a4a63f848013359c7868736778fe6579bbb02af381975873fb7f2059",
        "signature": "ef2734831d69768e9c73f40c06f8a3657bde6474b8a02d86001d5392cb89e5da5104732ee7a81e581dd3273af8eda95f9d83a9e837ad1516f0aa9f7a2771340c61353336373432386134613633663834383031333335396337383638373336373738666536353739626262303261663338313937353837336662376632303539",
        "status": "pending",
        "memo": "test",
        "amountDecimal": "0.003",
        "decimals": 9,
        "created": "2024-04-19T15:28:14.335Z",
        "sbdv": true,
        "int": "3000000"
      },
      // -- Snip --
    ],
    "found": 24,
    "total": 24
  }
}

Key fields in each transaction record typically include:

• _id: Internal identifier of the pool transaction record.
• uid: UUID of the user who initiated the withdrawal request.
• chain_id: Network identifier for the transaction.
• amount: Human-readable amount requested for withdrawal.
• type: Transaction type (e.g. withdrawal).
• reference_id: Business or platform reference used to correlate this transaction with your internal systems.
• to: Destination address for the withdrawal.
• hash: SBDV-related hash used to verify integrity of the stored transaction data.
• signature: CKSDK-generated signature attesting to the request payload.
• status: Current status of the pool entry (for example, pending, approved, rejected, depending on your workflow).
• memo: Optional memo or note attached to the transaction.
• amountDecimal: Amount expressed as a decimal string, using the token's decimals.
• decimals: Number of decimal places for the asset.
• created: Timestamp when the pool transaction was created.
• sbdv: Boolean indicating whether Signature-Based Data Verification has passed for this record.
• int: Amount in integer form (base units) corresponding to amountDecimal.

Dynamic Ledger

NOTE

This section applies only to Omnibus account configurations where Dynamic Ledger has been enabled.

Initiating User Deposit

This REST API is used to notify the Dynamic Ledger when a new deposit has been credited to a user's account in your system.

Endpoint: <ck_hotwallet_url>/service/ledger/deposit

Request payload:

{
  "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
  "type": "deposit",
  "chain_id": "solana",
  "amount": "10.5", // Decimal string
  "txid": "PAYNET_ABC-123",
  "meta": {} // Optional
}

• uid: UUID of the user in your system.
• type: Must be "deposit" for this operation.
• chain_id: Network identifier associated with the omnibus account (e.g. solana).
• amount: Deposit amount as a decimal string.
• txid: Your internal transaction identifier for this deposit (for example, a payment gateway or core ledger reference).
• meta: Optional object for attaching additional metadata (e.g. notes, source, tags).

Response payload example:

{
  "success": true,
  "message": "Deposited",
  "ciphertext": {
    "id": "6622954f4f07ea0013fb9eb7"
  }
}

• id: Identifier of the Dynamic Ledger entry created for this deposit.

Executing Withdrawal

This REST API is used to notify the Dynamic Ledger when a withdrawal is recorded on your off-chain omnibus ledger. It is effectively the opposite of the Initiating Deposit: deposits increase a user's omnibus balance, while this withdrawal endpoint decreases it.

This operation does not perform an on-chain withdrawal. It is purely a ledger update used when you are managing balances off-chain (Eg. omnibus account structure).

Endpoint: <ck_hotwallet_url>/service/ledger/withdraw

Request payload:

{
  "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
  "type": "withdraw",
  "chain_id": "bitcoin",
  "amount": "0.5", // Decimal string
  "txid": "TRANSACTION_ABC-123",
  "meta": {} // Optional
}

• uid: UUID of the user whose omnibus balance should be debited.
• type: Must be "withdraw" for this operation.
• chain_id: Network identifier associated with the omnibus account (e.g. bitcoin).
• amount: Withdrawal amount as a decimal string.
• txid: Your internal transaction identifier for this deposit (for example, a payment gateway or core ledger reference).
• meta: Optional object for additional metadata (e.g. reason, desk ID, notes)

Response payload example:

{
  "success": true,
  "message": "Withdrawn",
  "ciphertext": {
    "id": "65f1cb2360bed20013fc89e5"
  }
}

• id: Identifier of the Dynamic Ledger entry created for this withdrawal.

Retrieve User Balance

Use this REST API to retrieve a user's current Dynamic Ledger balance for a specific network.

Endpoint: <ck_hotwallet_url>/service/ledger/balance/of

Request payload:

{
  "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
  "chain_id": "solana"
}

• uid: UUID of the user whose balance you want to query.
• chain_id: Network identifier associated with the omnibus ledger (e.g. solana).

Response payload example:

{
  "success": true,
  "message": "Balance of",
  "ciphertext": {
    "int": "39995000",
    "amount": "0.039995",
    "decimals": 9,
    "pending": {
      "int": "3000000",
      "amount": "0.003",
      "decimals": 9
    }
  }
}

• int: User's confirmed balance in base units (integer).
• amount: User's confirmed balance as a decimal string, using the specified decimals.
• decimals: Number of decimal places for the asset.
• pending.int: Pending amount in base units (e.g. in-flight withdrawals).
• pending.amount: Pending amount as a decimal string.
• pending.decimals: Decimal precision for the pending amount (same as decimals).

Retrieve Total Balance

Use this REST API to retrieve the aggregate balance recorded in the Dynamic Ledger for a given network.

Endpoint: <ck_hotwallet_url>/service/ledger/balance/total

Request payload:

{
  "chain_id": "solana"
}

• chain_id: Network identifier for which you want to aggregate all ledger balances (e.g. solana).

Response payload example:

{
  "success": true,
  "message": "Balance total",
  "ciphertext": {
    "int": "39995000",
    "amount": "0.039995",
    "decimals": 9,
    "pending": {
      "int": "0",
      "amount": "0.0",
      "decimals": 9
    }
  }
}

• int: Total confirmed balance across all users in base units (integer).
• amount: Total confirmed balance as a decimal string, using the specified decimals.
• decimals: Number of decimal places for the asset.
• pending.int: Total pending amount in base units (e.g. in-flight withdrawals).
• pending.amount: Total pending amount as a decimal string.
• pending.decimals: Decimal precision for the pending amount (same as decimals).

Retrieve General Summary

Use this REST API to fetch paginated list network-level summary of the Dynamic Ledger, grouped by chain (e.g. total balances and user counts per network).

Endpoint: <ck_hotwallet_url>/service/ledger/summary/total

Request payload:

{
  "params": {
    // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Summary total",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "name": "Solana",
        "chain_id": "solana",
        "total": "12.039995",
        "decimals": 9,
        "usersCount": 1
      },
      {
        "name": "Bitcoin",
        "chain_id": "bitcoin",
        "total": "1.3339",
        "decimals": 8,
        "usersCount": 2
      },
      // -- Snip --
    ],
    "found": 7,
    "total": 7
  }
}

• name: Human-readable network name.
• chain_id: Network identifier.
• total: Aggregate confirmed balance for that network as a decimal string.
• decimals: Number of decimal places used for amounts on that network.
• usersCount: Number of users with a non-zero ledger entry on that network.
• found: Number of summary records returned in this page.
• total: Total number of summary records across all pages.

Retrieve User Summary by Chain

Use this REST API to fetch paginated list user-level summary from the Dynamic Ledger for a given network.

Endpoint: <ck_hotwallet_url>/service/ledger/summary/users

Request payload:

{
  "params": {
     chain_id: 'solanadevnet'
     // Obtain from SDK
  },
  "currentPage": 1,
  "perPage": 5 // Between 1 to 100
}

• params: Filter and sorting options (obtained from CKSDK; see the Pagination filters section for available options).
• currentPage: The page number to retrieve.
• perPage: Number of records per page (minimum 1, maximum 100).

Response payload example:

{
  "success": true,
  "message": "Summary total",
  "ciphertext": {
    "data": [
      // -- Snip --
      {
        "uid": "c80df78a-95ef-4717-8c0d-081fcb352994",
        "chain_id": "solana",
        "decimals": 9,
        "int": "39995000",
        "amount": "0.039995"
      }
      // -- Snip --
    ],
    "found": 7,
    "total": 7
  }
}

• uid: UUID of the user.
• chain_id: Network identifier for this summary entry.
• decimals: Number of decimal places used for amounts on this network.
• int: User's confirmed balance in base units (integer).
• amount: User's confirmed balance as a decimal string, using decimals.