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

# One page of the named wallets' spot positions.



## OpenAPI

````yaml /specs/openapi.json get /v1/positions
openapi: 3.1.0
info:
  title: Metastreams API
  description: >-
    Click's B2B market-data API. Amounts are decimal strings, timestamps are
    Unix milliseconds, and every field name is camelCase.
  license:
    name: Proprietary
    identifier: Proprietary
  version: 1.0.0
servers:
  - url: https://{host}
    variables:
      host:
        default: api.metastreams.dev
        description: API host.
security:
  - bearerKey: []
paths:
  /v1/positions:
    get:
      tags:
        - wallets
      summary: One page of the named wallets' spot positions.
      operationId: wallet_positions
      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,base
        - name: lifecycle
          in: query
          description: Lifecycle to list; `open` when absent.
          required: false
          schema:
            $ref: '#/components/schemas/Lifecycle'
        - name: hideLowLiquidity
          in: query
          description: >-
            Drop open positions whose token liquidity is below the low-liquidity
            floor.
          required: false
          schema:
            type: boolean
            default: true
        - name: hideDust
          in: query
          description: Drop open positions whose remaining value is below the dust floor.
          required: false
          schema:
            type: boolean
        - name: hideTransfers
          in: query
          description: Drop positions never acquired through a buy.
          required: false
          schema:
            type: boolean
        - name: chain
          in: query
          description: Exact-token drill-down chain; requires `token`.
          required: false
          schema:
            type: string
          example: solana
        - name: token
          in: query
          description: Exact-token drill-down address; requires `chain`.
          required: false
          schema:
            type: string
        - name: q
          in: query
          description: Case-insensitive substring of the token symbol or name.
          required: false
          schema:
            type: string
        - name: sort
          in: query
          description: >-
            Sort field and direction, `field:asc|desc`. `value:desc` when
            absent, `closedAt:desc` for closed.
          required: false
          schema:
            type: string
          example: value:desc
        - name: limit
          in: query
          description: Rows per page, clamped to 1-100; 50 when absent.
          required: false
          schema:
            type: integer
            format: int32
            maximum: 100
            minimum: 1
        - name: cursor
          in: query
          description: Opaque cursor from the previous page.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: >-
            One page of the named wallets' positions. The price-derived fields
            are `null` for a token without a price.
          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/UiSpotPositions'
        '400':
          description: >-
            Unsupported chain, a malformed wallet or token address, a wallet
            count outside 1-100, an unpaired drill-down, a bad sort, a cursor of
            other filters, 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 API key.
          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: Credit balance cannot cover the request.
          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: The key is valid, but its plan excludes this endpoint.
          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:
    Lifecycle:
      type: string
      description: A position's current-cycle lifecycle.
      enum:
        - open
        - closed
    UiSpotPositions:
      type: object
      description: One page of the named wallets' positions.
      required:
        - positions
        - hasMore
        - asOf
        - counts
      properties:
        asOf:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: Serve-time snapshot timestamp.
        counts:
          $ref: '#/components/schemas/UiPositionCounts'
          description: >-
            Per-product counts, taken before the lifecycle, display, search and
            drill-down filters.
        hasMore:
          type: boolean
          description: Whether a next page exists.
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for the next page; `null` on the last page.
        positions:
          type: array
          items:
            $ref: '#/components/schemas/UiSpotPosition'
          description: Positions on this page.
    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.
    UiPositionCounts:
      type: object
      description: Per-product position counts.
      required:
        - spot
      properties:
        spot:
          $ref: '#/components/schemas/UiSpotCounts'
          description: Spot counts.
    UiSpotPosition:
      type: object
      description: >-
        One wallet's spot position in one token, priced at the token's latest
        price.
      required:
        - product
        - chain
        - walletAddress
        - token
        - status
        - isTransfer
        - isStablecoin
        - holdings
        - holdingsPctSupply
        - avgCost
        - invested
        - received
        - realizedPnl
        - fees
        - buyCount
        - sellCount
        - tokensBought
        - tokensSold
        - openedAt
        - updatedAt
        - version
        - lifetime
        - funding
      properties:
        avgCost:
          $ref: '#/components/schemas/UiMoney'
          description: Per-token average entry cost.
        avgEntryMarketCap:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: >-
                Size-weighted market cap across the position's buys; `null` when
                none was recorded.
        avgExitMarketCap:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: >-
                Size-weighted market cap across the position's sells; `null`
                when none was recorded.
        buyCount:
          type: integer
          format: int64
          description: Buy-side trade count this cycle.
          minimum: 0
        chain:
          $ref: '#/components/schemas/SpotChain'
          description: Chain the position is on.
        closedAt:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UnixMilliseconds'
              description: When the current cycle closed; `null` while open.
        fees:
          $ref: '#/components/schemas/UiMoney'
          description: Fees paid this cycle.
        funding:
          $ref: '#/components/schemas/UiWalletFunding'
          description: >-
            The wallet's first inbound funding. Every position of one wallet
            carries the same value.
        holdings:
          $ref: '#/components/schemas/Decimal'
          description: Current token balance.
        holdingsPctSupply:
          $ref: '#/components/schemas/Decimal'
          description: Current holdings as a percent of token supply.
        identities:
          type: array
          items:
            $ref: '#/components/schemas/UiWalletIdentity'
          description: The holder's resolved identities, one element per source.
        invested:
          $ref: '#/components/schemas/UiMoney'
          description: Spent acquiring the current cycle's holdings.
        isStablecoin:
          type: boolean
          description: >-
            Whether the token is a known USD stablecoin; clients render its
            value but suppress PnL.
        isTransfer:
          type: boolean
          description: Whether every unit came without a buy (airdrop, transfer-in).
        lifetime:
          $ref: '#/components/schemas/UiPositionLifetime'
          description: >-
            Aggregates across every open/close cycle for this `(chain, wallet,
            token)`.
        openedAt:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: When the current cycle opened.
        pnlPct:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Decimal'
              description: >-
                `totalPnl.usd` as a percent of `invested.usd`; `null` without a
                cost basis or `totalPnl`.
        product:
          $ref: '#/components/schemas/Product'
          description: Always `spot` today.
        realizedPnl:
          $ref: '#/components/schemas/UiMoney'
          description: Realized PnL this cycle.
        received:
          $ref: '#/components/schemas/UiMoney'
          description: Received from sells this cycle.
        sellCount:
          type: integer
          format: int64
          description: Sell-side trade count this cycle.
          minimum: 0
        status:
          $ref: '#/components/schemas/Lifecycle'
          description: This cycle's lifecycle.
        token:
          $ref: '#/components/schemas/UiPositionToken'
          description: The held token.
        tokensBought:
          $ref: '#/components/schemas/Decimal'
          description: Tokens bought this cycle.
        tokensSold:
          $ref: '#/components/schemas/Decimal'
          description: Tokens sold this cycle.
        totalPnl:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: Realized plus unrealized PnL; `null` when `unrealizedPnl` is.
        unrealizedPnl:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: Unrealized PnL on current holdings; `null` when unpriced.
        updatedAt:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: >-
            Block time of the position's last update. Updates in one second
            share it.
        value:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: Current value (`holdings × price`); `null` when unpriced.
        version:
          $ref: '#/components/schemas/UnixMilliseconds'
          description: >-
            Reconciliation key. A client keeps the highest value per position
            and discards lower ones.
        walletAddress:
          type: string
          description: The wallet holding this position, lowercase on EVM chains.
    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].`
    UiSpotCounts:
      type: object
      description: Spot position counts across the named wallets.
      required:
        - open
        - closed
      properties:
        closed:
          type: integer
          format: int64
          description: Closed positions.
          minimum: 0
        open:
          type: integer
          format: int64
          description: Open positions.
          minimum: 0
    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.
    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
        - base
        - bsc
        - robinhood
        - arc
    UiWalletFunding:
      type: object
      description: A wallet's first inbound funding.
      required:
        - status
      properties:
        address:
          type:
            - string
            - 'null'
          description: Funder wallet or exchange address.
        amount:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Decimal'
              description: Amount received, denominated in `asset`.
        asset:
          type:
            - string
            - 'null'
          description: Asset the funding moved; `null` for the chain's native asset.
        sourceKind:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/FundingSourceKind'
              description: What the funder is (exchange, bridge, wallet, …).
        sourceLabel:
          type:
            - string
            - 'null'
          description: Display label for the funder, e.g. an exchange name.
        status:
          $ref: '#/components/schemas/FundingStatus'
          description: Whether the lookup has settled.
        symbol:
          type:
            - string
            - 'null'
          description: Display ticker of `asset`.
        timestamp:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UnixMilliseconds'
              description: When the funding transfer occurred.
        tx:
          type:
            - string
            - 'null'
          description: The funding transaction's signature or hash.
    Decimal:
      type: string
      format: decimal
      description: An exact decimal, as a string.
      example: '123.456789'
    UiWalletIdentity:
      type: object
      description: One source's resolved profile for a trade's trader.
      required:
        - source
      properties:
        avatar:
          type:
            - string
            - 'null'
          description: >-
            CDN URL of the avatar to render; `null` until the picture is
            mirrored.
        displayName:
          type:
            - string
            - 'null'
          description: Human-readable name to render.
        farcaster:
          type:
            - string
            - 'null'
          description: The wallet's Farcaster handle, where the source links one.
        handle:
          type:
            - string
            - 'null'
          description: The wallet's handle on the source.
        source:
          $ref: '#/components/schemas/IdentitySource'
          description: Who resolved this identity.
        telegram:
          type:
            - string
            - 'null'
          description: The wallet's Telegram handle, where the source links one.
        twitter:
          type:
            - string
            - 'null'
          description: The wallet's bare X handle, where the source links one.
    UiPositionLifetime:
      type: object
      description: Aggregates across every open/close cycle a wallet has had in one token.
      required:
        - invested
        - received
        - realizedPnl
        - fees
        - buyCount
        - sellCount
        - cycleCount
        - winningCycleCount
        - tokensBought
        - tokensSold
      properties:
        buyCount:
          type: integer
          format: int64
          description: Buy-side trade count across every cycle.
          minimum: 0
        cycleCount:
          type: integer
          format: int64
          description: Number of cycles opened.
          minimum: 0
        fees:
          $ref: '#/components/schemas/UiMoney'
          description: Total fees paid across every cycle.
        invested:
          $ref: '#/components/schemas/UiMoney'
          description: Total spent across every cycle.
        realizedPnl:
          $ref: '#/components/schemas/UiMoney'
          description: Total realized PnL across every cycle.
        received:
          $ref: '#/components/schemas/UiMoney'
          description: Total received from sells across every cycle.
        sellCount:
          type: integer
          format: int64
          description: Sell-side trade count across every cycle.
          minimum: 0
        tokensBought:
          $ref: '#/components/schemas/Decimal'
          description: Tokens bought across every cycle.
        tokensSold:
          $ref: '#/components/schemas/Decimal'
          description: Tokens sold across every cycle.
        winningCycleCount:
          type: integer
          format: int64
          description: Number of cycles closed with positive realized PnL.
          minimum: 0
    Product:
      type: string
      description: The financial product an event or credit pertains to.
      enum:
        - spot
        - perps
        - prediction_markets
    UiPositionToken:
      type: object
      description: >-
        A position's token. Every field but `chain` and `address` is `null` for
        a token without data.
      required:
        - chain
        - address
      properties:
        address:
          type: string
          description: Token address.
        chain:
          $ref: '#/components/schemas/SpotChain'
          description: Chain the token trades on.
        decimals:
          type:
            - integer
            - 'null'
          format: int32
          description: Token decimals.
          minimum: 0
        image:
          type:
            - string
            - 'null'
          description: Token image URL, as stored.
        marketCap:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: Current market cap.
        name:
          type:
            - string
            - 'null'
          description: Token name.
        price:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/UiMoney'
              description: Current price.
        symbol:
          type:
            - string
            - 'null'
          description: Token symbol.
    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
    FundingSourceKind:
      type: string
      description: Whether a known exchange or another wallet funded the creator.
      enum:
        - cex
        - wallet
    FundingStatus:
      type: string
      description: Whether the creator wallet's funding lookup has settled.
      enum:
        - unresolved
        - resolved
    IdentitySource:
      type: string
      description: >-
        Who resolved a trader's identity. The set grows; keep a value you do not
        recognize.
      enum:
        - codex
        - fomo
        - pump
        - gmgn
        - axiom
        - unknown
  securitySchemes:
    bearerKey:
      type: http
      scheme: bearer
      description: 'Send the API key as `Authorization: Bearer <key>`.'

````

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