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

# Get Portfolio Snapshot Items

> Get historical portfolio snapshot data with normalized coin balances and portfolio metrics

<Note>**500** credits per request</Note><hr />

<AccordionGroup>
  <Accordion title="You will get">
    * Historical coin quantities and balances over time
    * Total portfolio balance tracking with changes
    * Price changes and quantity changes between snapshots
    * Filterable by date range and specific coins
  </Accordion>

  <Accordion title="Required">
    <Note>This endpoint is only available for users with a Degen plan subscription (when using shareToken).</Note>

    * shareToken OR portfolioId: Provide one of these to identify the portfolio.
      * shareToken: Get this from your CoinStats portfolio page by clicking "Share"
      * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange
    * If neither is provided, returns snapshot data for all API-connected portfolios
  </Accordion>

  <Accordion title="Optional">
    * from & to: Date range filter (YYYY-MM-DD format)
    * coinIds: Comma-separated list of coin IDs to filter by
    * page & limit: Pagination controls
    * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter)
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /api-reference/openapi.json get /v1/portfolio/snapshot/items
openapi: 3.0.0
info:
  title: CoinStats Public API
  description: >-
    CoinStats Public API — programmatic access to market data, news, NFTs,
    wallets, exchange connections, and user portfolios. Authenticate every
    request with the `X-API-KEY` header (or an OAuth Bearer token in the
    `Authorization` header). Generate keys at https://openapi.coinstats.app.
  version: '1.0'
  contact: {}
servers:
  - url: https://openapiv1.coinstats.app
security: []
tags:
  - name: CoinStats
    description: ''
  - name: Market Data
    description: >-
      The Market Data section of the API provides endpoints to access a wide
      range of market-related information, including cryptocurrency coins,
      ticker data, and fiat currency rates. This category offers comprehensive
      data to help users monitor and analyze the cryptocurrency market, track
      prices, and gain insights into market trends
  - name: News
    description: >-
      The News section of the API allows you to access news articles and updates
      related to cryptocurrencies and the blockchain industry. It provides
      valuable information from various sources to keep you informed about the
      latest developments
  - name: NFTs
    description: >-
      The NFT section of the API provides endpoints to interact with
      Non-Fungible Tokens (NFTs), which are unique digital assets stored on a
      blockchain. These endpoints allow you to retrieve information about NFTs,
      including collections, assets, trending NFTs, and specific assets
      associated with wallet addresses.
  - name: Wallet Data
    description: >-
      The Wallet section of the API provides a comprehensive set of endpoints to
      manage and interact with wallets. It enables users to retrieve wallet
      balances, monitor syncing status, fetch transaction data, and synchronize
      wallet information with the blockchain. By integrating these endpoints
      into your application, you can offer robust wallet functionality to your
      users.
  - name: Exchange Connection
    description: >-
      The Exchange Connection section of the API provides a comprehensive set of
      endpoints to manage and interact with exchanges. It enables users to
      retrieve exchange balances, monitor syncing status, fetch transaction
      data. By integrating these endpoints into your application, you can offer
      robust exchange portfolio tracking functionality to your users.
  - name: User Portfolio
    description: >-
      The Portfolio section of the API provides a comprehensive set of endpoints
      to manage and interact with Share Portfolios. It enables users to retrieve
      current Portfolio Coins and Transactions.
  - name: Usage
    description: The Usage section provides account-level API usage data.
  - name: Status
    description: The Status section provides API availability checks.
paths:
  /v1/portfolio/snapshot/items:
    get:
      tags:
        - User Portfolio
      summary: >-
        Get historical portfolio snapshot data with normalized coin balances and
        portfolio metrics
      operationId: get-portfolio-snapshot-items
      parameters:
        - name: sharetoken
          required: false
          in: header
          description: '[Get Share Token](/sharetoken)'
          schema:
            type: string
        - name: passcode
          required: false
          in: header
          description: Passcode for accessing protected portfolio data
          schema:
            example: '123456'
            type: string
        - name: page
          required: false
          in: query
          description: Page number to retrieve (1-based indexing)
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items to return per page
          schema:
            example: 20
            type: number
        - name: portfolioId
          required: false
          in: query
          description: >-
            Portfolio ID for accessing a specific API-connected portfolio.
            Required if shareToken is not provided.
          schema:
            example: abc123def456
            type: string
        - name: from
          required: false
          in: query
          description: Start date for snapshot data (YYYY-MM-DD format)
          schema:
            example: '2024-01-01'
            type: string
        - name: to
          required: false
          in: query
          description: End date for snapshot data (YYYY-MM-DD format)
          schema:
            example: '2024-12-31'
            type: string
        - name: coinIds
          required: false
          in: query
          description: Comma-separated list of coin IDs to filter by
          schema:
            example: bitcoin,ethereum,cardano
            type: string
      responses:
        '200':
          description: Portfolio Snapshot Items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioSnapshotResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                statusCode: 400
                message: Bad Request
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                statusCode: 403
                message: Forbidden
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '404':
          description: Not Found
          content:
            application/json:
              example:
                statusCode: 404
                message: Not Found
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '409':
          description: Conflict (for some endpoints)
          content:
            application/json:
              example:
                statusCode: 409
                message: Transactions not synced
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                statusCode: 429
                message: Rate limit exceeded
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '503':
          description: Service Unavailable
          content:
            application/json:
              example:
                statusCode: 503
                message: Service Unavailable. Please Contact Support
      security:
        - X-API-KEY: []
components:
  schemas:
    PortfolioSnapshotResponseDto:
      type: object
      properties:
        result:
          description: Array of portfolio snapshots ordered chronologically
          type: array
          items:
            $ref: '#/components/schemas/PortfolioSnapshotItemDto'
      required:
        - result
    PortfolioSnapshotItemDto:
      type: object
      properties:
        date:
          format: date-time
          type: string
          description: ISO 8601 timestamp when the snapshot was taken
          example: '2025-08-29T10:00:00.000Z'
        coinBalances:
          description: Array of individual cryptocurrency balances and their changes
          type: array
          items:
            $ref: '#/components/schemas/SnapshotCoinBalanceDto'
        totalBalance:
          type: number
          description: Total USD value of all holdings in the portfolio
          example: 74.137019959
        totalBalanceChange:
          type: number
          description: Change in total USD balance compared to previous snapshot
          example: -0.43391738
        totalBalancePercentChange:
          type: number
          description: Percentage change in total balance compared to previous snapshot
          example: -0.58188537
      required:
        - date
        - coinBalances
        - totalBalance
        - totalBalanceChange
        - totalBalancePercentChange
    SnapshotCoinBalanceDto:
      type: object
      properties:
        symbol:
          type: string
          description: Cryptocurrency symbol
          example: KMNO
        icon:
          type: string
          description: URL to the coin icon image
          example: https://static.coinstats.app/coins/kaminobx1.png
        quantity:
          type: number
          description: Amount of cryptocurrency held
          example: 282.85
        balance:
          type: number
          description: USD value of the held amount
          example: 15.7021349
        quantityChange:
          type: number
          description: Change in quantity compared to previous snapshot
          example: 0
        balanceChange:
          type: number
          description: Change in USD balance compared to previous snapshot
          example: -0.2110061
        pricePerUnit:
          type: number
          description: Current price per unit in USD (0 when price data unavailable)
          example: 0
        pricePercentChange:
          type: number
          description: >-
            Percentage change in price from previous snapshot (0 when price data
            unavailable)
          example: 0
      required:
        - symbol
        - icon
        - quantity
        - balance
        - quantityChange
        - balanceChange
        - pricePerUnit
        - pricePercentChange
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key required to access the endpoints. Generate one from your
        dashboard at https://openapi.coinstats.app and pass it in the
        `X-API-KEY` request header. Never expose your key in client-side code.

````