> For the complete documentation index, see [llms.txt](https://docs.superstate.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.superstate.com/investors/api/balances-api.md).

# Balances API

The Balances API allows you to retrieve balance information for all instruments held by your organization or a specific entity via the `/v1/balances` endpoint.

***

## Authentication

This endpoint requires an API key with either the `FundManager` or `TransactionViewer` role. Contact Superstate for an API key. 

***

## Sending a Request

For information on how to send a request, please see the [API key section on the API page](/investors/api.md#using-api-key-authenticated-endpoints).

Example

```typescript
import { superstateApiKeyRequest } from '@superstateinc/api-key-request';

const balances = await superstateApiKeyRequest({
  apiKey: SUPERSTATE_API_KEY,
  apiSecret: SUPERSTATE_API_SECRET,
  endpoint: "/v1/balances",
});

console.log(balances);
```

***

## Query Parameters

#### entity\_id

Filter the response to only include balances for a specific entity. Contact Superstate to get entity ID(s) associated with your organization.

| Property | Value   |
| -------- | ------- |
| Type     | integer |
| Required | No      |

**Note:** When using an entity-scoped API key, the `entity_id` parameter must match the entity ID associated with the API key.

***

## Response

The response contains balance information organized by entity, with optional organization-level aggregations.

#### Response Structure

| Field                   | Type   | Description                                                                               |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `entities`              | object | Map of entity IDs to their balance data                                                   |
| `total_portfolio_value` | object | Total portfolio value across all entities (organization-scoped keys only)                 |
| `org_balances`          | object | Aggregated balances by instrument across the organization (organization-scoped keys only) |

#### Entity Balance Data

Each entity in the `entities` map contains:

| Field         | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| `entity_id`   | integer | The entity's unique identifier                         |
| `entity_name` | string  | The entity's display name                              |
| `balances`    | object  | Map of instrument symbols to balance details           |
| `subaccounts` | object  | (Optional) Map of subaccount IDs to their balance data |

#### Asset Balance Details

Each instrument in the `balances` map contains:

| Field               | Type   | Description                                        |
| ------------------- | ------ | -------------------------------------------------- |
| `instrument_symbol` | string | The instrument ticker (e.g., "USTB", "USCC")       |
| `instrument_domain` | string | Category: "Funds", "Equities", or "FiatCurrencies" |
| `total_shares`      | string | Total shares/units held                            |
| `total_notional`    | object | Total value in USD (when available)                |
| `price`             | object | Current price per share (when available)           |
| `balances`          | array  | Detailed breakdown by balance type                 |

#### Balance Entry Types

Each entry in the `balances` array represents a specific type of holding:

| Label                 | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `BookEntryAvailable`  | Book-entry shares available for transactions            |
| `BookEntryRestricted` | Book-entry shares with transfer restrictions            |
| `Token`               | On-chain tokenized shares                               |
| `Protocol`            | Shares deposited in DeFi protocols (Aave, Morpho, etc.) |

#### Example Response

```json
{
  "entities": {
    "123": {
      "entity_id": 123,
      "entity_name": "Acme Corp",
      "balances": {
        "USCC": {
          "instrument_symbol": "USCC",
          "instrument_domain": "Funds",
          "total_shares": "0.460719",
          "total_notional": "5.267199",
          "price": "11.432564",
          "balances": [
            {
              "label": "Token",
              "instrument_symbol": "USCC",
              "instrument_domain": "Funds",
              "chain_id": 11155111,
              "subaccount_id": 222,
              "chain_address": "0x1234567890abcdef1234567890abcdef12345678",
              "name": "MyAddressNickname",
              "total_shares": "0.460719",
              "notional_balance": "5.267199",
              "notional_price": "11.432564",
              "yield_value": null,
              "restrictive_legend": null
            }
          ]
        },
        "TEST": {
          "instrument_symbol": "TEST",
          "instrument_domain": "Equities",
          "total_shares": "400.000000",
          "total_notional": null,
          "price": null,
          "balances": [
            {
              "label": "BookEntryAvailable",
              "instrument_symbol": "TEST",
              "instrument_domain": "Equities",
              "chain_id": null,
              "subaccount_id": 222,
              "chain_address": null,
              "name": null,
              "total_shares": "400.000000",
              "notional_balance": null,
              "notional_price": null,
              "yield_value": null,
              "restrictive_legend": null
            }
          ]
        },
        "USTB": {
          "instrument_symbol": "USTB",
          "instrument_domain": "Funds",
          "total_shares": "10.939991",
          "total_notional": "119.875793",
          "price": "10.957577",
          "balances": [
            {
              "label": "Token",
              "instrument_symbol": "USTB",
              "instrument_domain": "Funds",
              "chain_id": 11155111,
              "subaccount_id": 222,
              "chain_address": "0x1234567890abcdef1234567890abcdef12345678",
              "name": "MyAddressNickname",
              "total_shares": "10.939991",
              "notional_balance": "119.875793",
              "notional_price": "10.957577",
              "yield_value": null,
              "restrictive_legend": null
            }
          ]
        }
      }
    }
  },
  "total_portfolio_value": "125.142992",
  "org_balances": {
    "USCC": {
      "instrument_symbol": "USCC",
      "instrument_domain": "Funds",
      "total_shares": "0.460719",
      "total_notional": "5.267199",
      "price": "11.432564",
      "balances": [
        {
          "label": "Token",
          "instrument_symbol": "USCC",
          "instrument_domain": "Funds",
          "chain_id": 11155111,
          "subaccount_id": 222,
          "chain_address": "0x1234567890abcdef1234567890abcdef12345678",
          "name": "MyAddressNickname",
          "total_shares": "0.460719",
          "notional_balance": "5.267199",
          "notional_price": "11.432564",
          "yield_value": null,
          "restrictive_legend": null
        }
      ]
    },
    "USTB": {
      "instrument_symbol": "USTB",
      "instrument_domain": "Funds",
      "total_shares": "10.939991",
      "total_notional": "119.875793",
      "price": "10.957577",
      "balances": [
        {
          "label": "Token",
          "instrument_symbol": "USTB",
          "instrument_domain": "Funds",
          "chain_id": 11155111,
          "subaccount_id": 222,
          "chain_address": "0x1234567890abcdef1234567890abcdef12345678",
          "name": "MyAddressNickname",
          "total_shares": "10.939991",
          "notional_balance": "119.875793",
          "notional_price": "10.957577",
          "yield_value": null,
          "restrictive_legend": null
        }
      ]
    },
    "TEST": {
      "instrument_symbol": "TEST",
      "instrument_domain": "Equities",
      "total_shares": "400.000000",
      "total_notional": null,
      "price": null,
      "balances": [
        {
          "label": "BookEntryAvailable",
          "instrument_symbol": "TEST",
          "instrument_domain": "Equities",
          "chain_id": null,
          "subaccount_id": 222,
          "chain_address": null,
          "name": null,
          "total_shares": "400.000000",
          "notional_balance": null,
          "notional_price": null,
          "yield_value": null,
          "restrictive_legend": null
        }
      ]
    }
  }
}
```

***

### Error Responses

| Status Code | Description                                                                            |
| ----------- | -------------------------------------------------------------------------------------- |
| 401         | Invalid or missing API key                                                             |
| 403         | API key does not have the required permissions (FundManager or TransactionViewer role) |
| 404         | The specified entity was not found or is not accessible with this API key              |
| 500         | Internal server error                                                                  |