# External accounts

* [API URL](#api-url)
* [Authentication](#authentication)
* [API Endpoints](#api-endpoints)
  * [`GET /api/v1/external_accounts`](#get-api-v1-external_accounts)
  * [`GET /api/v1/external_accounts/:id`](#get-api-v1-external_accounts-id)
* [Errors](#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.](/balance-custody-api/authentication.md)

***

## 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**

```bash
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:

```json
{
  "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**

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

**Response**

Returns a single external account.

Status: `200`

Data:

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://balance-1.gitbook.io/balance-custody-api/v1/external-accounts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.