Transactions

This document details the Balance Custody v1 Transactions API, offering endpoints to retrieve, view, and update transactions across the custody platform.

• Supported Currencies

• API URL

• Authentication

• API Endpoints

  • GET /api/v1/transactions

  • GET /api/v1/transactions/:id

  • PUT /api/v1/transactions/:id

• Errors

Supported Currencies

See the Wallets API docs.

API URL

You will receive your warm wallet integration URL from your point of contact at Balance, and will look like:

YOUR_CUSTOM_SUBDOMAIN.balancecustody.ca

---

Authentication

Due to the nature of the information exposed, every endpoint in this API requires authentication.

For more information on authentication go to Authentication doc.

---

API Endpoints

For brevity, the curl examples below do not include headers. See the Authentication section for required headers.

Response data is for example purposes only and does not represent real crypto accounts.

GET /api/v1/transactions

List all transactions. Includes internal and external transactions. Cursor-based pagination is supported.

Internal transactions are defined as transactions between your Cold or Warm wallets managed by Balance Custody.

External transactions are defined as transactions that are originated externally, destined for your Cold or Warm wallets managed by Balance Custody.

Accepted parameters:

Accepts the following GET parameters as part of the query string:

status

Optional. Indicates the status of transactions to query for. If not specified, returns all transactions.

Possible values are:

• pending_approval - Transaction is in this state if your warm wallets are set up to require extra approvals before being signed and broadcast by the warm wallets.

• approved - Transaction is in this state if it has been approved (or auto-approved if your warm wallets do not require extra approvals), but not yet signed and broadcast.

• pending_generation - Transaction is in this state after a submitted transaction has received all required approvals, while our asynchronous workers are validating and generating transaction data for signing with the wallets.

• completed - Transaction is in this state after it has been successfully signed and broadcast.

• canceled - Transaction is in this state if its execution has been canceled through the UI.

• failed - Transaction is in this state if it its execution failed at any of the steps. In this case the system administrators at Balance are notified and will contact you with next steps.

regulatory_status

Optional. Indicates the regulatory status of transactions to query for. This will be used when querying for deposits that require Travel Rule information to be submitted.

Possible values are:

• pending - indicates transactions that have missing Travel Rule information that must be provided.

• completed - indicates transactions that do not have missing Travel Rule information.

type

Optional. Indicates the type of the transaction to query for. If not specified, returns all transactions.

Possible values are:

• internal - Transactions originating from your warm or cold wallets.

• external - Incoming transactions originating from wallets outside your custody account.

completed_since

Optional. If specified, returns completed transactions only that were completed after the given timestamp. Completed transactions are defined as external transactions that are confirmed in a block, or internal transactions that have been successfully broadcast. If not specified, returns all transactions.

Values are UNIX timestamps (in seconds).

created_since

Optional. If specified, returns transactions that were created after the given timestamp. The created_since filter refers to the timestamp when a transaction was created or imported in the Balance database, whereas the completed_since filter refers to blockchain broadcast or confirmation time of a given transaction.

The created_since filter can be useful for scanning for transactions that were backfilled or imported long after they were confirmed in a block.

Values are UNIX timestamps (in seconds).

Pagination

To request more results provide either a before or after parameter containing the cursor from the transaction you want data prior to or following. For example, to request data after the result in the example below: GET /api/v1/transactions?after=MTI=

A page_size parameter may be provided to control the size of the response. This must be between 1 and 100 and if omitted defaults to 10.

Request

Example without filters:

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions

Example with the status filter:

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed

Example with completed_since:

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed\&type=external\&completed_since=1585598824

Example with created_since: (NOTE: this is the preferred method of polling for incoming external transactions)

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions?status=completed\&type=external\&created_since=1585598824

Response

Returns an array of transaction JSON structs.

Status: 200

Example of an Internal transaction:

{
  "page_info": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "MTI=",
    "end_cursor": "Mw=="
  },
  "page": [
    {
      "cursor": "MTI=",
      "data": {
        "id": 1,
        "type": "transaction",
        "status": "completed",
        "created_at": "2019-06-18T19:33:15.000Z",
        "requested_by": "api",
        "source": {
          "id": 1,
          "type": "wallet",
          "kind": "warm",
          "custom_id": "editable custom id 1",
          "name": "editable name 1",
          "description": "editable description 1",
          "balance": {
            "btc": 12.34567890,
            "bch": 12.34567890,
            "ada": 12.34567890,
            "ltc": 12.34567890,
            "eth": 12.34567890,
            "eigen": 12.34567890,
            "fil": 12.34567890,
            "xrp": 12.34567890,
            "xlm": 12.34567890,
            "usdc": 12.34567890
          },
          "funding_addresses": {
            "btc": "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg",
            "bch": "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ",
            "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
            "ltc": "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3",
            "eth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
            "eigen": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
            "usdc": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
            "fil": "f1xyexamplefiladdress987654321",
            "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
            "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2"
          },
          "extras": {
            "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
              "tag": "xrp tag"
            },
            "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
              "memo": "xlm memo"
            }
          }
        },
        "amounts": {
          "btc": 1.23456789,
          "bch": 1.23456789,
          "ada": 1.23456789,
          "ltc": 1.23456789,
          "eth": 1.23456789,
          "eigen": 1.23456789,
          "fil": 1.23456789,
          "xrp": 1.23456789,
          "xlm": 1.23456789,
          "usdc": 1.23456789
        },
        "fees": {
          "btc": 0.0002,
          "bch": 0.0002,
          "ada": 0.155381,
          "ltc": 0.0002,
          "eth": 0.0002,
          "eigen": 0.0002,
          "fil": 0.00025202,
          "xrp": 0.00001,
          "xlm": 0.00001,
          "usdc": 0.0002
        },
        "fee_units": {
          "btc": "sat/b",
          "bch": "sat/b",
          "ada": "ada",
          "ltc": "sat/b",
          "eth": "gwei",
          "eigen": "gwei",
          "fil": "nanoFIL",
          "xrp": "xrp/op",
          "xlm": "xlm/op",
          "usdc": "gwei"
        },
        "block": {
          "btc": 1234567,
          "bch": 1234567,
          "ada": 1234567,
          "ltc": 1234567,
          "eth": 1234567,
          "eigen": 1234567,
          "fil": 1234567,
          "xrp": 1234567,
          "xlm": 1234567,
          "usdc": 1234567
        },
        "cad_rates": {
          "btc": 123.45,
          "bch": 123.45,
          "ada": 1.23,
          "ltc": 123.45,
          "eth": 123.45,
          "eigen": 123.45,
          "fil": 5.67,
          "xrp": 0.89,
          "xlm": 0.17,
          "usdc": 1.34
        },
        "notes": "Custom note for this transfer",
        "completed_at": "2019-06-18T19:33:16.000Z",
        "transaction_ids": [
          { "currency": "btc", "transaction_id": "<BTC_TX_ID>" },
          { "currency": "bch", "transaction_id": "<BCH_TX_ID>" },
          { "currency": "ada", "transaction_id": "<ADA_TX_ID>" },
          { "currency": "ltc", "transaction_id": "<LTC_TX_ID>" },
          { "currency": "eth", "transaction_id": "<ETH_TX_ID>" },
          { "currency": "eigen", "transaction_id": "<EIGEN_TX_ID>" },
          { "currency": "fil", "transaction_id": "<FIL_TX_ID>" },
          { "currency": "xrp", "transaction_id": "<XRP_TX_ID>" },
          { "currency": "xlm", "transaction_id": "<XLM_TX_ID>" },
          { "currency": "usdc", "transaction_id": "<USDC_TX_ID>" }
        ],
        "destination": {
          "id": 2,
          "type": "wallet",
          "kind": "warm",
          "custom_id": "editable custom id 2",
          "name": "editable name 2",
          "description": "editable description 2",
          "balance": {
            "btc": 12.34567890,
            "bch": 12.34567890,
            "ada": 12.34567890,
            "ltc": 12.34567890,
            "eth": 12.34567890,
            "eigen": 12.34567890,
            "fil": 12.34567890,
            "xrp": 12.34567890,
            "xlm": 12.34567890,
            "usdc": 12.34567890
          },
          "funding_addresses": {
            "btc": "1EWwLtiDvrLKKf6ySDoKqnFYLvcDMr2TvY",
            "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
            "ada": "addr1qydz8s47l6zw0u4jeeqzryxjz6j5vzg50t0s5vrqjx9s5rzq7e0u80gkwur",
            "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
            "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "fil": "f1abexamplefiladdress123456789",
            "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
            "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
          },
          "extras": {
            "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
              "tag": "xrp tag"
            },
            "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
              "memo": "xlm memo"
            }
          }
        }
      }
    },
    ...
  ]
}

Example of an Incoming External transaction:

{
  "page_info": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "MTI=",
    "end_cursor": "Mw=="
  },
  "page": [
    {
      "cursor": "MTI=",
      "data": {
        "id": 1,
        "hash": "<BCH_TX_ID>",
        "type": "external",
        "direction": "incoming",
        "timestamp": "2019-01-22T01:23:45.000-04:00",
        "block": 123456,
        "source_addresses": [
          "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ"
        ],
        "destination_addresses": [
          "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH"
        ],
        "destination": {
          "id": 2,
          "type": "wallet",
          "kind": "warm",
          "custom_id": "editable custom id 2",
          "name": "editable name 2",
          "description": "editable description 2",
          "balance": {
            "btc": 12.34567890,
            "bch": 12.34567890,
            "ada": 12.34567890,
            "ltc": 12.34567890,
            "eth": 12.34567890,
            "eigen": 12.34567890,
            "fil": 12.34567890,
            "xrp": 12.34567890,
            "xlm": 12.34567890,
            "usdc": 12.34567890
          },
          "funding_addresses": {
            "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
            "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
            "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
            "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
            "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "fil": "f1xyexamplefiladdress987654321",
            "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
            "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
          },
          "extras": {
            "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
              "tag": "xrp tag"
            },
            "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
              "memo": "xlm memo"
            }
          }
        },
        "amount": 123.4567890,
        "fee": 0.12345678,
        "fee_unit": "sat/b",
        "currency": "bch"
      }
    },
    ...
  ]
}

Example of an Outgoing External transaction:

{
  "page_info": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "MTI=",
    "end_cursor": "Mw=="
  },
  "page": [
    {
      "cursor": "MTI=",
      "data": {
        "id": 1,
        "type": "transaction",
        "status": "completed",
        "created_at": "2019-11-18T20:26:51.000Z",
        "requested_by": "api",
        "source": {
          "id": 1,
          "type": "wallet",
          "kind": "warm",
          "custom_id": "Source Wallet Custom Id",
          "name": "Source Wallet Name",
          "description": "Source Wallet Description",
          "balance": {
            "btc": 12.34567890,
            "bch": 12.34567890,
            "ada": 12.34567890,
            "ltc": 12.34567890,
            "eth": 12.34567890,
            "eigen": 12.34567890,
            "fil": 12.34567890,
            "xrp": 12.34567890,
            "xlm": 12.34567890,
            "usdc": 12.34567890
          },
          "funding_addresses": {
            "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
            "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
            "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
            "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
            "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
            "fil": "f1xyexamplefiladdress987654321",
            "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
            "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
          },
          "extras": {
            "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
              "tag": "xrp tag"
            },
            "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
              "memo": "xlm memo"
            }
          }
        },
        "amounts": {
          "btc": 1.23456789,
          "bch": 1.23456789,
          "ada": 1.23456789,
          "ltc": 1.23456789,
          "eth": 1.23456789,
          "eigen": 1.23456789,
          "fil": 1.23456789,
          "xrp": 1.23456789,
          "xlm": 1.23456789,
          "usdc": 1.23456789
        },
        "fees": {
          "btc": 0.0002,
          "bch": 0.0002,
          "ada": 0.155381,
          "ltc": 0.0002,
          "eth": 0.0002,
          "eigen": 0.0002,
          "fil": 0.00025202,
          "xrp": 0.00001,
          "xlm": 0.00001,
          "usdc": 0.0002
        },
        "fee_units": {
          "btc": "sat/b",
          "bch": "sat/b",
          "ada": "ada",
          "ltc": "sat/b",
          "eth": "gwei",
          "eigen": "gwei",
          "fil": "nanoFIL",
          "xrp": "xrp/op",
          "xlm": "xlm/op",
          "usdc": "gwei"
        },
        "block": {
          "btc": 1234567,
          "bch": 1234567,
          "ada": 1234567,
          "ltc": 1234567,
          "eth": 1234567,
          "eigen": 1234567,
          "fil": 1234567,
          "xrp": 1234567,
          "xlm": 1234567,
          "usdc": 1234567
        },
        "cad_rates": {
          "btc": 123.45,
          "bch": 123.45,
          "ada": 1.23,
          "ltc": 123.45,
          "eth": 123.45,
          "eigen": 123.45,
          "fil": 5.67,
          "xrp": 0.89,
          "xlm": 0.17,
          "usdc": 1.34
        },
        "notes": "Transaction Notes",
        "completed_at": "2019-11-18T20:26:51.000Z",
        "transaction_ids": [
          { "currency": "btc", "transaction_id": "<BTC_TX_ID>" },
          { "currency": "bch", "transaction_id": "<BCH_TX_ID>" },
          { "currency": "ada", "transaction_id": "<ADA_TX_ID>" },
          { "currency": "ltc", "transaction_id": "<LTC_TX_ID>" },
          { "currency": "eth", "transaction_id": "<ETH_TX_ID>" },
          { "currency": "eigen", "transaction_id": "<EIGEN_TX_ID>" },
          { "currency": "fil", "transaction_id": "<FIL_TX_ID>" },
          { "currency": "xrp", "transaction_id": "<XRP_TX_ID>" },
          { "currency": "xlm", "transaction_id": "<XLM_TX_ID>" },
          { "currency": "usdc", "transaction_id": "<USDC_TX_ID>" }
        ],
        "destination": {
          "id": 1,
          "type": "external_account",
          "custom_id": "Destination Wallet Custom Id",
          "name": "Destination Wallet Name",
          "description": "Destination Wallet Description",
          "addresses": {
            "bch": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH"
          }
        }
      }
    },
    ...
  ]
}

GET /api/v1/transactions/:id

List details for an individual transaction. No parameters accepted.

NOTE: the id argument can be defined as one of two things:

1. the ID of an internal transaction (i.e. an integer)

2. the Hash of an externally originated transaction (i.e. a string)

Internal Transaction

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/1

Response

Returns a transaction JSON struct.

Status: 200

Data:

{
  "id": 1,
  "type": "transaction",
  "status": "completed",
  "created_at": "2025-04-09T18:51:35.000Z",
  "requested_by": "Operator",
  "source": {
    "id": 201,
    "type": "wallet",
    "kind": "warm",
    "custom_id": "Internal Wallet A",
    "name": "Internal Wallet A",
    "description": "Source wallet for internal transfer",
    "balance": {
      "btc": 12.34567890,
      "bch": 12.34567890,
      "ada": 12.34567890,
      "ltc": 12.34567890,
      "eth": 12.34567890,
      "eigen": 12.34567890,
      "usdc": 12.34567890,
      "fil": 12.34567890,
      "xrp": 12.34567890,
      "xlm": 12.34567890
    },
    "funding_addresses": {
      "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
      "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
      "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
      "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
      "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "fil": "f1xyexamplefiladdress987654321",
      "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
      "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
    }
  },
  "amounts": {
    "ltc": 0.0003
  },
  "fees": {
    "ltc": 0.000004
  },
  "fee_units": {
    "ltc": "sat/b"
  },
  "block": {
    "ltc": 2876792
  },
  "cad_rates": {
    "btc": 123.45,
    "bch": 123.45,
    "ada": 0.90,
    "ltc": 110.53,
    "eth": 123.45,
    "eigen": 0.99,
    "usdc": 1.00,
    "fil": 3.58,
    "xrp": 0.66,
    "xlm": 0.13
  },
  "notes": null,
  "is_batched": false,
  "completed_at": "2025-04-09T18:52:09.000Z",
  "transaction_ids": [
    {
      "currency": "ltc",
      "transaction_id": "8bfd1142ab5a237605e546124116bc6c5ec665ffa8d5ac4ba33798a593b39608"
    }
  ],
  "destination": {
    "id": 202,
    "type": "wallet",
    "kind": "warm",
    "custom_id": "Internal Wallet B",
    "name": "Internal Wallet B",
    "description": "Destination wallet for internal transfer",
    "balance": {
      "btc": 12.34567890,
      "bch": 12.34567890,
      "ada": 12.34567890,
      "ltc": 12.34567890,
      "eth": 12.34567890,
      "eigen": 12.34567890,
      "usdc": 12.34567890,
      "fil": 12.34567890,
      "xrp": 12.34567890,
      "xlm": 12.34567890
    },
    "funding_addresses": {
      "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
      "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
      "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
      "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
      "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "fil": "f1xyexamplefiladdress987654321",
      "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
      "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
    }
  },
  "regulatory_status": "not_required",
  "originator_entity": {
    "kind": "corporate",
    "address1": "123 Example Lane",
    "address2": "Floor 2",
    "city": "Toronto",
    "state": "Ontario",
    "postcode": "M5V 2Y1",
    "country": "Canada",
    "corporate_name": "Demo Originator Inc.",
    "incorporation_number": "ABC123456",
    "nature_of_business": "Digital asset services",
    "id_doc_type_code": 3,
    "id_doc_number": "ABC123456",
    "id_doc_jurisdiction_country": "Canada",
    "id_doc_jurisdiction_state": "Ontario",
    "registration_country": "Canada",
    "registration_state": "Ontario",
    "authorized_person_first_name": "John",
    "authorized_person_last_name": "Smith"
  },
  "beneficiary_entity": {
    "kind": "corporate",
    "address1": "123 Example Lane",
    "address2": "Floor 2",
    "city": "Toronto",
    "state": "Ontario",
    "postcode": "M5V 2Y1",
    "country": "Canada",
    "corporate_name": "Demo Beneficiary Inc.",
    "incorporation_number": "XYZ987654",
    "nature_of_business": "Digital asset services",
    "id_doc_type_code": 3,
    "id_doc_number": "XYZ987654",
    "id_doc_jurisdiction_country": "Canada",
    "id_doc_jurisdiction_state": "Ontario",
    "registration_country": "Canada",
    "registration_state": "Ontario",
    "authorized_person_first_name": "Alice",
    "authorized_person_last_name": "Johnson"
  },
  "beneficiary_entities": [
    {
      "kind": "corporate",
      "address1": "123 Example Lane",
      "address2": "Floor 2",
      "city": "Toronto",
      "state": "Ontario",
      "postcode": "M5V 2Y1",
      "country": "Canada",
      "corporate_name": "Demo Beneficiary Inc.",
      "incorporation_number": "XYZ987654",
      "nature_of_business": "Digital asset services",
      "id_doc_type_code": 3,
      "id_doc_number": "XYZ987654",
      "id_doc_jurisdiction_country": "Canada",
      "id_doc_jurisdiction_state": "Ontario",
      "registration_country": "Canada",
      "registration_state": "Ontario",
      "authorized_person_first_name": "Alice",
      "authorized_person_last_name": "Johnson"
    }
  ]
}

Off-chain Reconciliation Transaction

Such transaction is only possible when Delivery by Ledger Entry is enabled, and off-chain transactions are reconciled on-chain.

The returned data is the same as the Internal Transaction above, with two additional fields included:

"is_offchain_reconciliation": true,   # signifies that this transaction is an off-chain reconciliation transaction
"reconciled_transaction_ids": [1,2,3] # returns the off-chain transaction IDs that were reconciled by this transaction

External Transaction

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/021d6eb3a0a63d857619879a6f8b04124d75725d09d726fddec286829d4c7785

Response

Returns a transaction JSON struct.

Status: 200

Example of an Incoming External transaction:

Data:

{
  "id": 1,
  "hash": "abcdef1234567890deadbeef1234567890abcdef1234567890abcdef12345678",
  "type": "external",
  "direction": "incoming",
  "timestamp": "2025-01-01T12:34:56.000Z",
  "block": 654321,
  "source_addresses": [
    "GDSAMPLEINCOMINGADDRESS1234567890"
  ],
  "destination_addresses": [
    "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2"
  ],
  "destination": {
    "id": 2,
    "type": "wallet",
    "kind": "warm",
    "custom_id": "editable custom id 2",
    "name": "editable name 2",
    "description": "editable description 2",
    "balance": {
      "btc": 12.34567890,
      "bch": 12.34567890,
      "ltc": 12.34567890,
      "dash": 12.34567890,
      "eth": 12.34567890,
      "etc": 12.34567890,
      "xrp": 12.34567890,
      "xlm": 12.34567890,
      "pax": 12.34567890,
      "usdc": 12.34567890
    },
    "funding_addresses": {
      "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
      "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
      "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
      "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363",
      "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "etc": "0x4d35262056fb60e00BBc117a6c535f43fe4ED663",
      "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
      "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2",
      "pax": "0x32D7335171B0b57522D810c264a1264c9509b620",
      "usdc": "0x01938ba1c4699fd09b116dd3326906661d34170a"
    },
    "extras": {
      "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
        "tag": "xrp tag"
      },
      "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
        "memo": "xlm memo"
      }
    }
  },
  "amount": 123.456789,
  "fee": 0.000123,
  "fee_unit": "xlm/op",
  "currency": "xlm",
  "memo": "xlm memo",
  "regulatory_status": "completed",
  "beneficiary_entity": {
    "kind": "corporate",
    "address1": "123 Example Street",
    "address2": "Suite 100",
    "city": "Demo City",
    "state": "Ontario",
    "postcode": "M5V1A1",
    "country": "Canada",
    "corporate_name": "Example Corp Inc.",
    "incorporation_number": "ABC1234567",
    "nature_of_business": "Virtual asset services",
    "id_doc_type_code": 3,
    "id_doc_number": "ABC1234567",
    "id_doc_jurisdiction_country": "Canada",
    "id_doc_jurisdiction_state": "Ontario",
    "registration_country": "Canada",
    "registration_state": "Ontario",
    "authorized_person_first_name": "Jane",
    "authorized_person_last_name": "Doe",
    "is_client_instructed": false
  },
  "beneficiary_entities": [
    {
      "kind": "corporate",
      "address1": "123 Example Street",
      "address2": "Suite 100",
      "city": "Demo City",
      "state": "Ontario",
      "postcode": "M5V1A1",
      "country": "Canada",
      "corporate_name": "Example Corp Inc.",
      "incorporation_number": "ABC1234567",
      "nature_of_business": "Virtual asset services",
      "id_doc_type_code": 3,
      "id_doc_number": "ABC1234567",
      "id_doc_jurisdiction_country": "Canada",
      "id_doc_jurisdiction_state": "Ontario",
      "registration_country": "Canada",
      "registration_state": "Ontario",
      "authorized_person_first_name": "Jane",
      "authorized_person_last_name": "Doe",
      "is_client_instructed": false
    }
  ]
}

Note: the beneficiary_entity field has been deprecated. It will only return the most recently assigned beneficiary entity for a transaction. Instead use the field beneficiary_entities which is an array containing all beneficiary entities assigned to the transaction.

Example of an Outgoing External transaction:

Data:

{
  "id": 1,
  "type": "transaction",
  "status": "completed",
  "created_at": "2024-12-01T12:00:00.000Z",
  "requested_by": "Jane Demo",
  "source": {
    "id": 888,
    "type": "wallet",
    "kind": "warm",
    "custom_id": "Demo Wallet 001",
    "name": "Demo Wallet 001",
    "description": "Used in transaction examples",
    "balance": {
      "btc": 12.34567890,
      "bch": 12.34567890,
      "ada": 12.34567890,
      "ltc": 12.34567890,
      "eth": 12.34567890,
      "eigen": 12.34567890,
      "usdc": 12.34567890,
      "fil": 12.34567890,
      "xrp": 12.34567890,
      "xlm": 12.34567890
    },
    "onchain_balance": {
      "btc": 12.34567890,
      "bch": 12.34567890,
      "ada": 12.34567890,
      "ltc": 12.34567890,
      "eth": 12.34567890,
      "eigen": 12.34567890,
      "usdc": 12.34567890,
      "fil": 12.34567890,
      "xrp": 12.34567890,
      "xlm": 12.34567890
    },
    "funding_addresses": {
      "btc": "13UbCqnsjBd9Z9KAN4MosoqRhx9BouufKH",
      "bch": "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
      "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
      "ltc": "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
      "eth": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "eigen": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "usdc": "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09",
      "fil": "f1xyexamplefiladdress987654321",
      "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
      "xlm": "GBBCHCAAFACXZXELWKOLM4QU52FOM6PEBBMJ54O57K6QWFSM6TGEI2QO"
    },
    "owner": {
      "address1": "123 Demo Ave.",
      "address2": "Suite 456",
      "city": "Exampleville",
      "state": "Testland",
      "postcode": "X0X 0X0",
      "country": "Demo Country",
      "corporate_name": "Demo Custody Inc."
    }
  },
  "amounts": {
    "eth": 0.0025
  },
  "cad_rates": {
    "btc": 95000.0,
    "bch": 625.0,
    "ada": 0.62,
    "ltc": 110.0,
    "eth": 4850.0,
    "eigen": 4.50,
    "usdc": 1.37,
    "fil": 7.48,
    "xrp": 0.72,
    "xlm": 0.13
  },
  "notes": "Example transaction",
  "is_batched": false,
  "completed_at": "2024-12-01T12:00:12.000Z",
  "transaction_ids": [
    {
      "currency": "eth",
      "transaction_id": "0xb783de71f27a49911d3f3b7d0d6303d40e5e8fca71b84123bfea8ad8f9dc99ab"
    }
  ],
  "destination": {
    "id": 889,
    "name": "Demo External Account",
    "custom_id": "external-001",
    "description": "Destination for ETH",
    "type": "external_account",
    "addresses": {
      "eth": "0x4d9739cc9e3b9eabc302e78d7f9e283f002233f1"
    }
  },
  "fees": {
    "eth": 0.00045
  },
  "fee_units": {
    "eth": "gwei"
  },
  "block": {
    "eth": 20999999
  },
  "regulatory_status": "not_required",
  "originator_entity": {
    "kind": "corporate",
    "address1": "123 Demo Ave.",
    "address2": "Suite 456",
    "city": "Exampleville",
    "state": "Testland",
    "postcode": "X0X 0X0",
    "country": "Demo Country",
    "corporate_name": "Demo Custody Inc.",
    "incorporation_number": "999999-9",
    "nature_of_business": "Digital asset custody",
    "id_doc_type_code": 3,
    "id_doc_number": "999999-9",
    "id_doc_jurisdiction_country": "Demo Country",
    "id_doc_jurisdiction_state": "Testland",
    "registration_country": "Demo Country",
    "registration_state": "Testland",
    "authorized_person_first_name": "Jane",
    "authorized_person_last_name": "Demo"
  }
}

PUT /api/v1/transactions/:id

Update details of a transaction with a given ID.

Currently, you are only able to update regulatory compliance fields for external deposits.

NOTE: the id argument can be defined as one of two things:

1. the ID of an internal transaction (i.e. an integer)

2. the Hash of an externally originated transaction (i.e. a string)

Accepted parameters:

• is_originator_declared - a boolean; if provided, and set to false - then your organization information is used as an Originator Entity, and no further parameters for Originator Entity are required.

• originator_entity - an object of type Originator Entity. Signifies the originator of the deposit. Only persisted if the destination wallet does not already have a default originator entity set, and if the deposit does not already have an originator entity set. You should aim to provide all available information. The Balance Custody platform will make a determination about whether the information you provided is sufficient for the current transaction, and return a response code 200 if it is. If the information is insufficient, a 400 response code will be returned, along with an error message describing the missing field.

• third_party_entity - an object of type Third Party Entity. Signifies the third party that instructed this deposit to be made. Only persisted if the deposit does not already have a third party entity set. You should aim to provide all available information. The Balance Custody platform will make a determination about whether the information you provided is sufficient for the current transaction, and return a response code 200 if it is. If the information is insufficient, a 400 response code will be returned, along with an error message describing the missing field.

• is_client_instructed - a boolean; default is 'false'; should be set to 'true' if one of your clients instructed this deposit for the provision of goods and services on your platform

Request

curl -XPUT \
     -d '{"originator_entity":{"firstname":"John","lastname":"Smith","address1":"1 King Road","address2":"Unit 30","city":"Toronto","state":"Ontario","postcode":"1A2 3B4","country":"Canada","account_id":"123-123123"}}' \
     https://your_custom_subdomain.balancecustody.ca/api/v1/transactions/1

Response

Same response as GET /api/v1/transactions/:id

Errors

Errors in this API are the same as the ones specified in the wallet API docs.