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

# Portfolio API — View Holdings, Values, and PnL Data

> Query current token holdings, USD values, and PnL across connected wallets, or pull historical portfolio snapshots with the Big Brain Ape Portfolio API.

The Portfolio API gives you a real-time snapshot of every token you hold across your connected wallets. Use it to retrieve current balances, USD values, and profit-and-loss figures by network, or pull historical portfolio data to track how your holdings have changed over time.

## GET /portfolio

Retrieve all current token holdings across your connected wallets. Results include per-token amounts, USD values, and PnL percentages.

**Required scope:** `read`

### Query Parameters

<ParamField query="network" type="string">
  Filter holdings by blockchain network. Accepted values: `solana`, `ethereum`, `base`, `arbitrum`. Omit to return holdings from all connected networks.
</ParamField>

<ParamField query="currency" type="string" default="USD">
  The fiat currency used for value calculations. Defaults to `USD`.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET 'https://api.bigbrainape.com/v1/portfolio?currency=USD' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "totalValue": 12450.50,
    "currency": "USD",
    "change24h": 3.42,
    "holdings": [
      {
        "token": "SOL",
        "amount": "15.5",
        "valueUSD": 2232.50,
        "pnlPercent": 12.4,
        "network": "solana"
      },
      {
        "token": "ETH",
        "amount": "2.1",
        "valueUSD": 6720.00,
        "pnlPercent": -2.1,
        "network": "ethereum"
      }
    ]
  },
  "timestamp": "2024-01-15T14:32:00Z"
}
```

### Response Fields

<ResponseField name="success" type="boolean">
  `true` when the request completes without errors.
</ResponseField>

<ResponseField name="data" type="object">
  The portfolio payload.

  <Expandable title="data fields">
    <ResponseField name="data.totalValue" type="number">
      The combined value of all holdings expressed in the requested `currency`.
    </ResponseField>

    <ResponseField name="data.currency" type="string">
      The currency code used for all value fields in this response (e.g. `USD`).
    </ResponseField>

    <ResponseField name="data.change24h" type="number">
      Percentage change in total portfolio value over the past 24 hours.
    </ResponseField>

    <ResponseField name="data.holdings" type="array">
      An ordered list of individual token positions.

      <Expandable title="holdings item fields">
        <ResponseField name="token" type="string">
          The token ticker symbol (e.g. `SOL`, `ETH`).
        </ResponseField>

        <ResponseField name="amount" type="string">
          The raw token balance held across all connected wallets, returned as a string to preserve precision.
        </ResponseField>

        <ResponseField name="valueUSD" type="number">
          The current USD value of this position.
        </ResponseField>

        <ResponseField name="pnlPercent" type="number">
          Profit-and-loss for this position expressed as a percentage. Negative values indicate a loss.
        </ResponseField>

        <ResponseField name="network" type="string">
          The blockchain network where this holding resides.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 UTC timestamp indicating when the data was fetched.
</ResponseField>

***

## GET /portfolio/history

Retrieve the historical total value of your portfolio over a given period. Use this endpoint to power charts, calculate returns over time, or feed your own analytics pipeline.

**Required scope:** `read`

### Query Parameters

<ParamField query="period" type="string" required>
  The lookback window for the history. Accepted values: `1d`, `7d`, `30d`, `90d`, `1y`.
</ParamField>

<ParamField query="interval" type="string">
  The granularity of each data point. Accepted values: `hourly`, `daily`. Defaults to `daily` for periods longer than `7d` and `hourly` for `1d`.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET 'https://api.bigbrainape.com/v1/portfolio/history?period=7d&interval=daily' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "period": "7d",
    "interval": "daily",
    "currency": "USD",
    "startValue": 10800.00,
    "endValue": 12450.50,
    "changePercent": 15.28,
    "dataPoints": [
      {
        "timestamp": "2024-01-09T00:00:00Z",
        "value": 10800.00
      },
      {
        "timestamp": "2024-01-10T00:00:00Z",
        "value": 11050.75
      },
      {
        "timestamp": "2024-01-11T00:00:00Z",
        "value": 10920.30
      },
      {
        "timestamp": "2024-01-12T00:00:00Z",
        "value": 11340.00
      },
      {
        "timestamp": "2024-01-13T00:00:00Z",
        "value": 11890.10
      },
      {
        "timestamp": "2024-01-14T00:00:00Z",
        "value": 12100.40
      },
      {
        "timestamp": "2024-01-15T00:00:00Z",
        "value": 12450.50
      }
    ]
  },
  "timestamp": "2024-01-15T14:32:00Z"
}
```

### Response Fields

<ResponseField name="data.period" type="string">
  The requested lookback window.
</ResponseField>

<ResponseField name="data.interval" type="string">
  The granularity used for each data point in `dataPoints`.
</ResponseField>

<ResponseField name="data.currency" type="string">
  The currency used for all value fields.
</ResponseField>

<ResponseField name="data.startValue" type="number">
  Portfolio value at the start of the requested period.
</ResponseField>

<ResponseField name="data.endValue" type="number">
  Portfolio value at the end of the requested period (most recent snapshot).
</ResponseField>

<ResponseField name="data.changePercent" type="number">
  Percentage change between `startValue` and `endValue`.
</ResponseField>

<ResponseField name="data.dataPoints" type="array">
  Ordered list of value snapshots for the requested period and interval.

  <Expandable title="dataPoints item fields">
    <ResponseField name="timestamp" type="string">
      ISO 8601 UTC timestamp for this snapshot.
    </ResponseField>

    <ResponseField name="value" type="number">
      Total portfolio value at this point in time, in the requested currency.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Use `interval=hourly` with `period=1d` to get an intraday chart suitable for a 24-hour performance view on a dashboard.
</Tip>