> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glider.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Portfolio Positions

> Returns real-time per-asset token balances and USD values for a portfolio.

Returns the portfolio's live positions — per-asset balances, unit prices,
and USD values — plus an aggregate `totalValueUsd`. Responses are cached
for up to 30 seconds, so rapid polling from a single caller is cheap. For
schedule state (`nextDueAt`, `lastRebalanceAt`, `status`), strategy
metadata, and smart account addresses without live balances, use
`GET /v2/portfolios/{portfolioId}` instead.

**One shape, every asset class.** The `assets[]` array uses the same row
shape (`assetId`, `symbol`, `decimals`, `balance`, `balanceRaw`,
`priceUsd`, `valueUsd`) for ERC-20 tokens, SPL tokens, and tokenized
real-world assets (equities, treasuries) when the underlying allocation
includes them. Symbol, decimals, and price come from Glider's upstream
data providers and are passed through unchanged.

* Auth: `x-api-key` header (required)
* Scope: `portfolios:read`

**Partial failures are surfaced, not raised as errors.** When a chain is
temporarily unavailable or a price is missing, the endpoint still returns
`200` with whatever loaded and a structured `warnings[]` array describing the
gap. A full failure returns `totalValueUsd: "0"`, `assets: []`, and populated
`warnings` — never a `5xx` for transient issues.

**Multi-chain by construction.** Every asset entry carries a full CAIP-19
`assetId` and a CAIP-10 `smartAccountId`, so EVM and non-EVM holdings share
one wire shape.

<ParamField path="portfolioId" type="string" required>
  Portfolio identifier returned by `POST /v2/enroll` or `GET /v2/portfolios`.
</ParamField>

Common error responses:

* `400` when the path parameter is invalid
* `401` when `x-api-key` header is missing or the key is invalid
* `403` when the API key lacks the `portfolios:read` scope
* `404` when the portfolio does not exist or does not belong to the tenant
* `500` on unexpected server errors

Warning kinds (in `warnings[]`):

* `MISSING_SMART_ACCOUNT` — no smart account is known for the requested chain
* `RPC_ERROR` — chain RPC timed out or errored
* `MISSING_PRICE` — no USD price found for an asset
* `BLOCKLISTED_ASSET` — asset is blocked and was skipped
* `MISSING_ASSET` — asset metadata is unavailable

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.glider.fi/v2/portfolios/pf_01JWZEE2MF30KVRMRX53N88VA4/positions' \
    --header 'x-api-key: gldr_sk_your_api_key'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.glider.fi/v2/portfolios/pf_01JWZEE2MF30KVRMRX53N88VA4/positions",
    { headers: { "x-api-key": "gldr_sk_your_api_key" } },
  );
  const data = await response.json();

  if (data.data.warnings.length > 0) {
    // Show a stale-data banner; the response is still usable for whatever loaded.
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "portfolioId": "pf_01JWZEE2MF30KVRMRX53N88VA4",
      "totalValueUsd": "1500.500000",
      "fetchedAt": "2026-04-15T12:34:56.000Z",
      "smartAccounts": [
        { "accountId": "eip155:8453:0xe3a2d1f49aee887e42655b56371d4d76bbf58058" }
      ],
      "assets": [
        {
          "assetId": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "smartAccountId": "eip155:8453:0xe3a2d1f49aee887e42655b56371d4d76bbf58058",
          "symbol": "USDC",
          "decimals": 6,
          "balance": "1500.500000",
          "balanceRaw": "1500500000",
          "priceUsd": "1.000000",
          "valueUsd": "1500.500000"
        }
      ],
      "warnings": []
    }
  }
  ```

  ```json 200 (partial) theme={null}
  {
    "success": true,
    "data": {
      "portfolioId": "pf_01JWZEE2MF30KVRMRX53N88VA4",
      "totalValueUsd": "1000.000000",
      "fetchedAt": "2026-04-15T12:34:56.000Z",
      "smartAccounts": [
        { "accountId": "eip155:8453:0xe3a2d1f49aee887e42655b56371d4d76bbf58058" }
      ],
      "assets": [
        {
          "assetId": "eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "smartAccountId": "eip155:8453:0xe3a2d1f49aee887e42655b56371d4d76bbf58058",
          "symbol": "USDC",
          "decimals": 6,
          "balance": "1000.000000",
          "balanceRaw": "1000000000",
          "priceUsd": "1.000000",
          "valueUsd": "1000.000000"
        }
      ],
      "warnings": [
        { "kind": "RPC_ERROR", "message": "chain 1 RPC timeout" }
      ]
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": {
      "code": "API_006",
      "message": "Portfolio with ID pf_01JWZEE2MF30KVRMRX53N88VA4 not found"
    }
  }
  ```
</ResponseExample>