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

# Portfolio

> Returns the summed spot holdings of up to 100 wallets, per chain, with each wallet's share and optional PnL stats.

Returns the spot holdings of the wallets in `wallets`, a comma-separated list of 1 to 100 addresses, as one value summed across them. `chains` limits the read to a comma-separated list of [chain slugs](https://docs.metastreams.io/concepts/chains.md); omit it to read every chain. An EVM address counts on every EVM chain in scope, and a Solana address on Solana.

## Value

A value is the sum of three parts:

* The balance of the chain's gas asset, at its latest price.
* The stablecoin balances, at \$1 each.
* The open [positions](https://docs.metastreams.io/reference/rest/positions.md), at each token's latest price.

A position adds nothing to the value when:

* Its token has no price.
* It is worth more than its token's market cap.
* Its token has no known market cap and under \$1,000 of liquidity.

`hideLowLiquidity=true` drops every open position in a token with under \$1,000 of liquidity, or with no known liquidity, from the values and the stats. A stablecoin is never dropped. The default is `false`.

## Response

* `totalValueUsd` is the value of every product. It equals `spot.valueUsd`, because spot is the only product.
* `spot` splits the value into balances and positions, with one item in `spot.chains` per chain in scope. A chain with no holdings has zero values.
* `wallets` lists each requested wallet's share, in the order of the request. The shares add up to the totals. `addresses` holds the wallet under its format, `evm` or `solana`, and the other is `null`.
* `asOf` is the time the response was calculated.

## Stats

`include=stats` adds `stats` to the portfolio and to each wallet. `stats` reports performance over four timeframes: `oneDay`, `sevenDays` and `thirtyDays` cover positions whose first purchase falls in that window, and `max` covers every position.

Each timeframe contains the realized and unrealized PnL per chain, the number of open positions, the trade counts, and `buckets`. `buckets` counts positions by realized return: `rekt` loses more than 50%, `loss` loses up to 50%, `win` returns 1x to 2x, `pump` from 2x to 5x, and `moonshot` at 5x or better.

## Errors

| Code | When |
| - | - |
| `UNSUPPORTED_CHAIN` | A slug in `chains` is not supported |
| `VALIDATION_ERROR` | No wallet or more than 100, a malformed address, an unknown `include` value, or an unknown parameter |

```bash cURL theme={null}
curl "https://api.metastreams.io/v1/portfolio?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&chains=solana" \
  -H "Authorization: Bearer $API_KEY"
```

```bash With stats theme={null}
curl "https://api.metastreams.io/v1/portfolio?wallets=7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5&include=stats" \
  -H "Authorization: Bearer $API_KEY"
```

```typescript TypeScript theme={null}
const url = new URL("https://api.metastreams.io/v1/portfolio");
url.searchParams.set("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5");
url.searchParams.set("chains", "solana");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const portfolio = await response.json();
```

```rust Rust theme={null}
use serde_json::Value;

let portfolio: Value = reqwest::Client::new()
    .get("https://api.metastreams.io/v1/portfolio")
    .query(&[("wallets", "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5"), ("chains", "solana")])
    .bearer_auth(std::env::var("API_KEY")?)
    .send()
    .await?
    .error_for_status()?
    .json()
    .await?;
```

```json Portfolio theme={null}
{
  "asOf": 1789632015120,
  "totalValueUsd": "11962.40",
  "spot": {
    "valueUsd": "11962.40",
    "balancesValueUsd": "7518.40",
    "positionsValueUsd": "4444.00",
    "chains": [
      {
        "chain": "solana",
        "nativeBalance": { "native": "41.208113", "usd": "7418.40" },
        "stableBalanceUsd": "100.00",
        "positionsValue": { "native": "24.688888", "usd": "4444.00" },
        "valueUsd": "11962.40"
      }
    ]
  },
  "wallets": [
    {
      "addresses": { "evm": null, "solana": "7YttLkHDoNj9wyDur5pM1ejNaAvT9X4eqaYcHQqtj2G5" },
      "spot": {
        "valueUsd": "11962.40",
        "balancesValueUsd": "7518.40",
        "positionsValueUsd": "4444.00",
        "chains": [
          {
            "chain": "solana",
            "nativeBalance": { "native": "41.208113", "usd": "7418.40" },
            "stableBalanceUsd": "100.00",
            "positionsValue": { "native": "24.688888", "usd": "4444.00" },
            "valueUsd": "11962.40"
          }
        ]
      }
    }
  ]
}
```


## OpenAPI

````yaml specs/openapi.json GET /v1/portfolio
openapi: 3.1.0
info:
  title: Metastreams API
  description: >-
    The Metastreams market-data API. Amounts are decimal strings, timestamps are
    Unix milliseconds, and every field name is camelCase.
  license:
    name: Proprietary
  version: 1.0.0
servers:
  - url: https://{host}
    variables:
      host:
        default: api.metastreams.io
        description: API host.
security:
  - bearerKey: []
paths:
  /v1/portfolio:
    get:
      tags:
        - wallets
      summary: >-
        The summed spot holdings of the named wallets, per chain, with each
        wallet's share.
      description: >-
        `wallets` names 1 to 100 addresses. Each costs one credit.

        An EVM address counts on every EVM chain in scope, and

        a Solana address on Solana. `chains` narrows the scope, and without it
        the read covers every

        spot chain. A value is the gas and stablecoin balances plus the open
        positions at each

        token's latest price. An open position in a stablecoin that a balance
        row can hold counts at

        $1 where no balance row holds it. A position without a price adds
        nothing. Neither does one

        worth more than its token's market cap. Neither does one whose token has
        no known market cap

        and under $1,000 of liquidity. `hideLowLiquidity=true` drops an open
        position on a thin token

        from the values and the stats. A thin token has under $1,000 of
        liquidity, or none known. A

        stablecoin that a balance row can hold is never thin.

        `include=stats` adds performance over the standard timeframes, for the
        portfolio and for each

        wallet.
      operationId: wallet_portfolio
      parameters:
        - name: wallets
          in: query
          description: Wallet addresses, CSV; one to 100.
          required: true
          schema:
            type: string
          example: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
        - name: chains
          in: query
          description: >-
            Chains to scope to, CSV of the chain slugs. Absent means every spot
            chain.
          required: false
          schema:
            type: string
          example: solana,bsc
        - name: include
          in: query
          description: >-
            Optional sections to compute, CSV; only `stats`. Absent returns none
            of them.
          required: false
          schema:
            type: string
          example: stats
        - name: hideLowLiquidity
          in: query
          description: >-
            Drop open positions whose token liquidity is below the low-liquidity
            floor, or not known.

            A position in a stablecoin that a balance row can hold never drops.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: >-
            The named wallets' spot holdings. A gas balance without a price has
            a `null` USD value, which no total counts.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UiPortfolioResponse'
        '400':
          description: >-
            Unsupported chain, a malformed wallet address, a wallet count
            outside 1-100, an unknown `include` section, or a malformed
            parameter.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: >-
            Missing or invalid credential: an API key, or a session token a key
            minted.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: >-
            The organization's credits this billing period reach its plan's
            limit.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            A key whose plan excludes this endpoint gets `FORBIDDEN`. A session
            token from an

            origin it does not name gets `ORIGIN_NOT_ALLOWED`.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limit exceeded.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: Unexpected server failure.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Dependency down or maintenance.
          headers:
            X-Credits-Cost:
              schema:
                type: integer
              description: >-
                Credits charged for this request. Zero on any non-2xx. Sent on a
                metered tier only.
            X-Credits-Remaining:
              schema:
                type: integer
              description: Credit balance after this request. Sent on a metered tier only.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: >-
                Requests left in the bucket this request spent from. Not sent
                with a 401.
            X-Request-ID:
              schema:
                type: string
              description: >-
                This request's trace ID. Echoed from the request, or generated
                when it sent none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    UiPortfolioResponse:
      type: object
      description: The summed spot holdings of the named wallets.
      required:
        - totalValueUsd
        - asOf
        - wallets
        - spot
      properties:
        asOf:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: Serve-time snapshot instant.
        spot:
          $ref: '#/components/schemas/UiSpotPortfolio'
          description: Spot holdings of every named wallet.
        stats:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiPortfolioStats'
              description: Timeframe performance; present only under `include=stats`.
          description: Timeframe performance; present only under `include=stats`.
        totalValueUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of every product's value; spot is the only product.
        wallets:
          type: array
          items:
            $ref: '#/components/schemas/UiWalletDescriptor'
          description: >-
            Each named wallet's share, in request order. The shares sum to the
            matching total.

            Their `stats` sum to `stats`.
    ErrorEnvelope:
      type: object
      description: The complete error response body — every error is exactly this.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: The error.
    UnixMilliseconds:
      type: integer
      format: int64
      description: An instant, as milliseconds since the Unix epoch.
    UiSpotPortfolio:
      type: object
      description: >-
        Spot holdings per chain: gas and stablecoin balances plus open
        positions.
      required:
        - valueUsd
        - balancesValueUsd
        - positionsValueUsd
        - chains
      properties:
        balancesValueUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of every chain's priced native and stable balances.
        chains:
          type: array
          items:
            $ref: '#/components/schemas/UiSpotPortfolioChain'
          description: >-
            Per-chain cells. The whole portfolio has one per chain in scope,
            zeroed where it holds

            nothing. A wallet's share has only the cells it holds.
        positionsValueUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of every chain's priced open-position value.
        valueUsd:
          $ref: '#/components/schemas/Decimal'
          description: '`balancesValueUsd + positionsValueUsd`.'
    UiPortfolioStats:
      type: object
      description: >-
        `include=stats`: performance over the four standard timeframes. A
        position joins a

        timeframe by the age of its first purchase, never its last activity.
      required:
        - oneDay
        - sevenDays
        - thirtyDays
        - max
      properties:
        max:
          $ref: '#/components/schemas/UiTimeframeStats'
          description: Every position in scope.
        oneDay:
          $ref: '#/components/schemas/UiTimeframeStats'
          description: Positions whose first purchase falls in the last day.
        sevenDays:
          $ref: '#/components/schemas/UiTimeframeStats'
          description: Positions whose first purchase falls in the last seven days.
        thirtyDays:
          $ref: '#/components/schemas/UiTimeframeStats'
          description: Positions whose first purchase falls in the last thirty days.
    Decimal:
      type: string
      format: decimal
      description: An exact decimal, as a string.
      example: '123.456789'
    UiWalletDescriptor:
      type: object
      description: One named wallet and its share of the portfolio.
      required:
        - addresses
        - spot
      properties:
        addresses:
          $ref: '#/components/schemas/UiWalletAddresses'
          description: The wallet's address, under its family.
        spot:
          $ref: '#/components/schemas/UiSpotPortfolio'
          description: This wallet's spot holdings.
        stats:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiPortfolioStats'
              description: >-
                This wallet's timeframe performance; present only under
                `include=stats`.
          description: >-
            This wallet's timeframe performance; present only under
            `include=stats`.
    ErrorDetail:
      type: object
      description: The `error` object inside the envelope.
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: >-
            Stable, machine-readable. Clients switch on this, never on
            `message`.
        details:
          description: Optional; shape is fixed per code.
        message:
          type: string
          description: |-
            Human-readable, written for the integrating developer:
            `[What happened]. [What to do next — if actionable].`
    UiSpotPortfolioChain:
      type: object
      description: One chain's balance and open-position value.
      required:
        - chain
        - nativeBalance
        - stableBalanceUsd
        - positionsValue
        - valueUsd
      properties:
        chain:
          $ref: '#/components/schemas/SpotChain'
          description: Chain this cell covers.
        nativeBalance:
          $ref: '#/components/schemas/UiMoney'
          description: The chain's gas asset balance; zero when no balance row exists.
        positionsValue:
          $ref: '#/components/schemas/UiMoney'
          description: Sum over open positions of `holdings × token price`.
        stableBalanceUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of the stablecoin balances other than the gas asset, priced 1:1.
        valueUsd:
          $ref: '#/components/schemas/Decimal'
          description: >-
            `nativeBalance.usd + stableBalanceUsd + positionsValue.usd`, priced
            components only.
    UiTimeframeStats:
      type: object
      description: One timeframe's aggregate over the positions inside it.
      required:
        - open
        - unrealizedUsd
        - realizedUsd
        - trades
        - buckets
        - chains
      properties:
        buckets:
          $ref: '#/components/schemas/UiPnlBuckets'
          description: Positions per realized-PnL tier.
        chains:
          type: array
          items:
            $ref: '#/components/schemas/UiTimeframeChainStats'
          description: >-
            Per-chain PnL. The whole portfolio has one per chain in scope,
            zeroed where it has no

            position. A wallet's share has only the chains it has a position on.
        open:
          type: integer
          format: int64
          description: Open positions in this timeframe, priced or not.
          minimum: 0
        realizedUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of every chain's realized PnL in USD.
        trades:
          $ref: '#/components/schemas/UiTradeCounts'
          description: Trade counts across every cycle.
        unrealizedUsd:
          $ref: '#/components/schemas/Decimal'
          description: Sum of every chain's unrealized PnL in USD.
    UiWalletAddresses:
      type: object
      description: >-
        A wallet's per-family addresses. A named wallet has one family, so the
        other is absent.
      properties:
        evm:
          type:
            - string
            - 'null'
          description: EVM `0x` address, lowercase.
        solana:
          type:
            - string
            - 'null'
          description: Solana base58 address.
    ErrorCode:
      type: string
      description: |-
        Every wire error code the API can return.

        Append-only: a new code is non-breaking, since clients fall back on the
        HTTP status for one they do not recognize, and a published code is never
        renamed or removed.
      enum:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION_ERROR
        - UNSUPPORTED_CHAIN
        - NOT_FOUND
        - RATE_LIMITED
        - CREDITS_EXHAUSTED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - RANGE_TOO_LARGE
        - INVALID_CREDENTIALS
        - ORIGIN_NOT_ALLOWED
        - NOT_ORG_MEMBER
        - MEMBERSHIP_INACTIVE
        - EMAIL_NOT_VERIFIED
        - EMAIL_TAKEN
        - ALREADY_MEMBER
        - INVITATION_ALREADY_SENT
        - INVITATION_ALREADY_ACCEPTED
        - LAST_ADMIN
        - CANNOT_REMOVE_SELF
        - KEY_LIMIT_REACHED
        - TOKEN_EXPIRED
        - PAYLOAD_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - IMAGE_TOO_LARGE
    SpotChain:
      type: string
      description: >-
        Chain slug. One spelling per chain, in paths and bodies alike. Only a
        chain with spot data is published.
      enum:
        - solana
        - bsc
        - robinhood
        - elysium
        - ethereum
    UiMoney:
      type: object
      description: >-
        A chain-denominated value with its USD equivalent. The enclosing object
        carries the

        `chain` that names `native`'s unit.
      required:
        - native
      properties:
        native:
          $ref: '#/components/schemas/Decimal'
          description: Value in the owning chain's gas asset.
        usd:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Decimal'
              description: Value in USD; `null` when the native asset is unpriced.
          description: Value in USD; `null` when the native asset is unpriced.
    UiPnlBuckets:
      type: object
      description: Positions per realized-PnL tier within a timeframe.
      required:
        - moonshot
        - pump
        - win
        - loss
        - rekt
      properties:
        loss:
          type: integer
          format: int64
          description: Realized down to -50%.
          minimum: 0
        moonshot:
          type: integer
          format: int64
          description: Realized 5x or better.
          minimum: 0
        pump:
          type: integer
          format: int64
          description: Realized 2x to 5x.
          minimum: 0
        rekt:
          type: integer
          format: int64
          description: Realized worse than -50%.
          minimum: 0
        win:
          type: integer
          format: int64
          description: Realized 1x to 2x.
          minimum: 0
    UiTimeframeChainStats:
      type: object
      description: One chain's PnL within a timeframe.
      required:
        - chain
        - open
        - unrealized
        - realized
      properties:
        chain:
          $ref: '#/components/schemas/SpotChain'
          description: Chain this cell covers.
        open:
          type: integer
          format: int64
          description: Open positions on this chain, priced or not.
          minimum: 0
        realized:
          $ref: '#/components/schemas/UiMoney'
          description: >-
            Realized PnL across every cycle, from open and closed positions
            alike.
        unrealized:
          $ref: '#/components/schemas/UiMoney'
          description: Unrealized PnL on what is still held.
    UiTradeCounts:
      type: object
      description: Trade counts within a timeframe, over every cycle each position has had.
      required:
        - total
        - buys
        - sells
      properties:
        buys:
          type: integer
          format: int64
          description: Buy-side trades.
          minimum: 0
        sells:
          type: integer
          format: int64
          description: Sell-side trades.
          minimum: 0
        total:
          type: integer
          format: int64
          description: '`buys + sells`.'
          minimum: 0
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: >-
        Send an API key, or a session token a key minted, as `Authorization:
        Bearer <credential>`. A browser opening `/v1/stream` offers its session
        token in `Sec-WebSocket-Protocol` instead.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.