> ## 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.

# The summed spot holdings of the named wallets, per chain, with each wallet's share.

> `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.



## 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.