> For the complete documentation index, see [llms.txt](https://balance-1.gitbook.io/balance-custody-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://balance-1.gitbook.io/balance-custody-api/v1/external-accounts.md).

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