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.

Example

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

{
  "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