# 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 | --- # 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://docs.superstate.com/investors/api/balances-api.md?ask= ``` 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.