External accounts

This document details the Balance Custody v1 External Accounts API, allowing management of external accounts with endpoints to list and retrieve details for approved accounts.

• API URL

• Authentication

• API Endpoints

  • GET /api/v1/external_accounts

  • GET /api/v1/external_accounts/:id

• Errors

API URL

You will receive your 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 Docs.

---

API Endpoints

These curl examples work out of the box as the API does not require any headers to be set.

GET /api/v1/external_accounts

List all approved external accounts. Only pagination parameters are accepted.

Pagination

To request more results provide either a before or after parameter containing the cursor from the external account you want data prior to or following. For example, to request data after the result in the example below: GET /api/v1/external_accounts?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

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

Response

Returns a paginated list of external accounts, including their custom_id, name, description, supported funding addresses, and optional extras (e.g., tags or memos for certain assets).

Status: 200

Data:

{
  "page_info": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "MTI=",
    "end_cursor": "Mw=="
  },
  "page": [
    {
      "cursor": "MTI=",
      "data": {
        "id": 1,
        "type": "wallet",
        "kind": "external",
        "custom_id": "Custom ID",
        "name": "External account name",
        "description": "External account description",
        "funding_addresses": {
          "btc": "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg",
          "bch": "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ",
          "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
          "ltc": "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3",
          "eth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
          "eigen": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
          "lseth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
          "usdc": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
          "fil": "f1xyexamplefiladdress987654321",
          "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
          "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2",
          "pax": "0xb3Dc579A90652190C5e3b52479688D510111Be44",
          "paxg": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
          "eurs": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4"
        },
        "extras": {
          "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
            "tag": "xrp tag"
          },
          "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
            "memo": "xlm memo"
          }
        }
      }
    },
    ...
  ]
}

GET /api/v1/external_accounts/:id

Show details for a single external account. No parameters accepted.

Request

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

Response

Returns a single external account.

Status: 200

Data:

{
  "id": 1,
  "type": "wallet",
  "kind": "external",
  "custom_id": "Custom ID",
  "name": "External account name",
  "description": "External account description",
  "funding_addresses": {
    "btc": "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg",
    "bch": "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ",
    "ada": "addr1q9vm2gxxplld7lm0eg7dzz7wsq6t8zk9q4u6d7en8n7jgc2y8k6q9gkj6w9",
    "ltc": "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3",
    "eth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
    "eigen": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
    "lseth": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
    "usdc": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
    "fil": "f1xyexamplefiladdress987654321",
    "xrp": "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5",
    "xlm": "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2",
    "pax": "0xb3Dc579A90652190C5e3b52479688D510111Be44",
    "paxg": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4",
    "eurs": "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4"
  },
  "extras": {
    "rLaMTxt8QkFGNuD67LJsdP5KpMxYqwMen5": {
      "tag": "xrp tag"
    },
    "GBIJ2T7YZDOTVFLWIGGK3FAQ2VDZIAOPEMMWKG7YVVNXKY47ZGC5Z6K2": {
      "memo": "xlm memo"
    }
  }
}

Errors

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