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

# Wallet DeFi positions snapshot (200) or queued scan (202)



## OpenAPI

````yaml /openapi.yaml get /v1/solana/wallets/{wallet}/defi-positions
openapi: 3.1.0
info:
  title: Lucidblock Positions API
  version: 0.1.0
  summary: >-
    Read-only Solana DeFi positions with explicit coverage and sourced USD
    values.
  description: >
    For a Solana wallet, returns the lending, liquidity, staking, vault and
    perpetual positions found by

    verified protocol adapters, with exact per-leg amounts, sourced USD values
    and explicit coverage.


    Conventions: amounts (`amount_raw`) are non-negative base-10 integer
    strings; `amount` and every USD

    value are decimal strings; unknown values are `null`, never `"0"`. Times are
    ISO 8601 UTC with second

    precision. Addresses are base58 and case-sensitive. Absence of a position is
    trustworthy only for

    protocols whose coverage status is `complete`. Totals cover the supported
    universe only; they are not

    total wallet net worth.


    Every `/v1/*` response that passed the rate limiter carries
    `RateLimit-Limit`, `RateLimit-Remaining`

    and `RateLimit-Reset`; a 429 adds `Retry-After`. Every response carries
    `X-Request-Id`.


    While `PRIVATE_API_TOKEN` is configured (private alpha), every `/v1/*` route
    except `/v1/health`

    requires `Authorization: Bearer <token>`.


    Snapshots carry display metadata (names, symbols, first-party logo URLs
    under /assets/v1/, provenance)

    and a trademark notice: protocol and token names and logos belong to their
    owners and are shown for

    identification only (14-metadata.md). Metadata never changes ids, amounts or
    totals.
  license:
    name: Proprietary
servers:
  - url: https://api.lucidblock.xyz
    description: Production (private alpha until the v1 release gate)
security:
  - {}
  - AccessToken: []
tags:
  - name: meta
  - name: positions
  - name: catalogue
paths:
  /v1/solana/wallets/{wallet}/defi-positions:
    get:
      tags:
        - positions
      summary: Wallet DeFi positions snapshot (200) or queued scan (202)
      operationId: getWalletPositions
      parameters:
        - $ref: '#/components/parameters/Wallet'
        - name: include
          in: query
          description: >-
            Comma-separated subset of underlying, rewards, valuation, metadata,
            tokens. Default underlying,rewards,valuation,metadata (`tokens`, the
            wallet token balances of D-27, only when asked for).
          schema:
            type: string
            maxLength: 200
            pattern: >-
              ^(underlying|rewards|valuation|metadata|tokens)(,(underlying|rewards|valuation|metadata|tokens))*$
        - name: protocols
          in: query
          description: >-
            Comma-separated adapter ids (see GET /v1/solana/protocols). Default
            all registered.
          schema:
            type: string
            maxLength: 1000
        - name: freshness_seconds
          in: query
          description: Maximum acceptable snapshot age in seconds. Default 120.
          schema:
            type: integer
            minimum: 0
            maximum: 86400
        - name: include_rewards_in_total
          in: query
          description: >-
            Count claimable reward and fee legs in totals. Requires `rewards` in
            `include`.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: cursor
          in: query
          description: Opaque cursor from page.next_cursor.
          schema:
            type: string
            maxLength: 200
        - name: wait
          in: query
          description: >-
            Long-poll (D-29). When the request would start or join a refresh
            scan (202, or a stale 200 with `refreshing`), hold it open up to
            this many seconds for the scan; if it finishes in time the response
            is the normal fresh 200 for the new snapshot, else exactly the
            response without `wait`. Counted once against rate limits. 0
            (default) returns at once.
          schema:
            type: integer
            minimum: 0
            maximum: 10
            default: 0
      responses:
        '200':
          description: Fresh or stale snapshot
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletPositionsResponse'
        '202':
          description: No snapshot yet; a bounded scan is queued
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/Internal'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    Wallet:
      name: wallet
      in: path
      required: true
      description: Base58 public key decoding to exactly 32 bytes; case-sensitive.
      schema:
        $ref: '#/components/schemas/Address'
  headers:
    XRequestId:
      schema:
        type: string
    RateLimitLimit:
      schema:
        type: integer
    RateLimitRemaining:
      schema:
        type: integer
    RateLimitReset:
      schema:
        type: integer
    RetryAfter:
      schema:
        type: integer
        minimum: 1
  schemas:
    WalletPositionsResponse:
      type: object
      additionalProperties: false
      required:
        - chain
        - network
        - wallet
        - snapshot_id
        - release_status
        - as_of
        - observed_slots
        - snapshot_consistency
        - refreshing
        - refresh_job_id
        - freshness
        - coverage
        - positions
        - page
        - totals
        - request
        - metadata
      properties:
        chain:
          type: string
          const: solana
        network:
          type: string
          const: mainnet-beta
        wallet:
          $ref: '#/components/schemas/Address'
        snapshot_id:
          type:
            - string
            - 'null'
        release_status:
          $ref: '#/components/schemas/ReleaseStatus'
        as_of:
          $ref: '#/components/schemas/Timestamp'
        observed_slots:
          $ref: '#/components/schemas/SlotRange'
        snapshot_consistency:
          type: string
          enum:
            - single_slot
            - multi_slot
            - unknown
        refreshing:
          type: boolean
        refresh_job_id:
          type:
            - string
            - 'null'
        freshness:
          type: object
          additionalProperties: false
          required:
            - age_seconds
            - stale
            - max_age_seconds
          properties:
            age_seconds:
              type:
                - integer
                - 'null'
            stale:
              type: boolean
            max_age_seconds:
              type: integer
        coverage:
          $ref: '#/components/schemas/Coverage'
        positions:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        page:
          $ref: '#/components/schemas/Page'
        totals:
          oneOf:
            - $ref: '#/components/schemas/Totals'
            - type: 'null'
        request:
          $ref: '#/components/schemas/RequestEcho'
        metadata:
          description: >-
            Display metadata for the mints and protocols on this page (14 §7.1);
            null when `metadata` is not in `include`.
          oneOf:
            - $ref: '#/components/schemas/MetadataBlock'
            - type: 'null'
        tokens:
          description: >-
            D-27 wallet token balances (native SOL plus every non-zero SPL /
            Token-2022 mint) for the whole snapshot, identical on every page;
            null unless `tokens` is in `include` or when the snapshot predates
            D-27. Emitted on every 200 since D-27.
          oneOf:
            - $ref: '#/components/schemas/WalletTokens'
            - type: 'null'
        tokens_total:
          description: >-
            D-27 separate wallet-token total. Never part of, and never includes,
            `totals`. Null unless both `tokens` and `valuation` are in `include`
            (and the snapshot has a tokens section).
          oneOf:
            - $ref: '#/components/schemas/TokensTotal'
            - type: 'null'
    JobAccepted:
      type: object
      additionalProperties: false
      required:
        - job_id
        - status
        - wallet
        - retry_after_seconds
        - poll_url
        - request
      properties:
        job_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
        wallet:
          $ref: '#/components/schemas/Address'
        retry_after_seconds:
          type: integer
          minimum: 1
        poll_url:
          type: string
        request:
          $ref: '#/components/schemas/RequestEcho'
    Address:
      type: string
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
    ReleaseStatus:
      type: string
      enum:
        - alpha_partial
        - v1
    Timestamp:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
    SlotRange:
      type: object
      additionalProperties: false
      required:
        - minimum
        - maximum
      properties:
        minimum:
          type:
            - integer
            - 'null'
        maximum:
          type:
            - integer
            - 'null'
    Coverage:
      type: object
      additionalProperties: false
      required:
        - status
        - universe
        - supported_protocol_count
        - completed_protocol_count
        - failed_protocol_count
        - skipped_protocol_count
        - unsupported_programs_detected
        - protocols
        - warnings
      properties:
        status:
          type: string
          enum:
            - complete_for_supported_protocols
            - partial
            - stale
            - pending
        last_scan_status:
          type: string
          enum:
            - complete_for_supported_protocols
            - partial
        universe:
          type: string
          const: supported_adapters_only
        supported_protocol_count:
          type: integer
        completed_protocol_count:
          type: integer
        failed_protocol_count:
          type: integer
        skipped_protocol_count:
          type: integer
        unsupported_programs_detected:
          type:
            - integer
            - 'null'
        protocols:
          type: array
          items:
            $ref: '#/components/schemas/ProtocolCoverage'
        wallet_token_scan:
          type: object
          additionalProperties: false
          required:
            - spl_token
            - token_2022
            - token_accounts_found
          properties:
            spl_token:
              type: string
              enum:
                - complete
                - error
            token_2022:
              type: string
              enum:
                - complete
                - error
            token_accounts_found:
              type:
                - integer
                - 'null'
        warnings:
          type: array
          items:
            type: string
    Position:
      type: object
      additionalProperties: false
      required:
        - id
        - protocol
        - position_type
        - category
        - position_account
        - owner_role
        - market
        - assets
        - debts
        - rewards
        - net_value_usd
        - known_value_usd
        - valuation
        - accounting
        - flags
        - evidence
        - details
        - warnings
      properties:
        id:
          type: string
          pattern: >-
            ^solana:[a-z0-9_]{1,64}:[1-9A-HJ-NP-Za-km-z]{32,44}(:[A-Za-z0-9_]{1,64}){0,2}$
        protocol:
          type: object
          additionalProperties: false
          required:
            - id
            - name
            - program_id
            - logo_url
          properties:
            id:
              $ref: '#/components/schemas/AdapterId'
            name:
              type: string
            program_id:
              $ref: '#/components/schemas/Address'
            logo_url:
              type:
                - string
                - 'null'
              format: uri
              description: >-
                64 px WebP on our own host; null without `metadata` in `include`
                or when asset serving is disabled.
        position_type:
          $ref: '#/components/schemas/PositionType'
        category:
          oneOf:
            - $ref: '#/components/schemas/PositionCategory'
            - type: 'null'
        position_account:
          type:
            - string
            - 'null'
        owner_role:
          $ref: '#/components/schemas/OwnerRole'
        market:
          type:
            - string
            - 'null'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
        debts:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
        net_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        known_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        valuation:
          type: object
          additionalProperties: false
          required:
            - status
            - priced_leg_count
            - indicative_leg_count
            - unpriced_leg_count
          properties:
            status:
              type: string
              enum:
                - complete
                - partial
                - unavailable
                - not_requested
            priced_leg_count:
              type: integer
            indicative_leg_count:
              type: integer
            unpriced_leg_count:
              type: integer
        accounting:
          type: object
          additionalProperties: false
          required:
            - counts_toward_totals
            - parent_position_id
            - carried_forward_from_snapshot
          properties:
            counts_toward_totals:
              type: boolean
            parent_position_id:
              type:
                - string
                - 'null'
            carried_forward_from_snapshot:
              type:
                - string
                - 'null'
        flags:
          type: array
          description: >-
            Open enum. Known values excluded_from_totals, staker_only,
            unsupported_position_kind, interest_stale, oracle_stale,
            incomplete_position, carried_forward, has_estimated_legs,
            has_indicative_legs, has_stale_legs, locked, out_of_range.
          items:
            type: string
        evidence:
          type: object
          additionalProperties: false
          required:
            - slot
            - adapter_version
            - method
          properties:
            slot:
              type:
                - integer
                - 'null'
            adapter_version:
              type: string
            method:
              type: string
              enum:
                - wallet_token
                - pda
                - program_accounts
                - wallet_transaction
            accounts:
              type: array
              items:
                $ref: '#/components/schemas/Address'
            decoder_hash:
              type:
                - string
                - 'null'
        details:
          type: object
          description: >-
            Adapter-specific, non-additive data (keys documented per adapter in
            02/03). Amounts, prices and rates are strings.
          additionalProperties: true
        warnings:
          type: array
          description: Open enum; format code or code:detail.
          items:
            type: string
    Page:
      type: object
      additionalProperties: false
      required:
        - limit
        - returned
        - total_positions
        - next_cursor
        - page_complete
      properties:
        limit:
          type: integer
        returned:
          type: integer
        total_positions:
          type: integer
        next_cursor:
          type:
            - string
            - 'null'
        page_complete:
          type: boolean
    Totals:
      type: object
      additionalProperties: false
      required:
        - total_value_usd
        - known_value_usd
        - total_null_reasons
        - unpriced_position_count
        - priced_leg_count
        - indicative_leg_count
        - unpriced_leg_count
        - excluded
        - valuation_status
        - include_rewards_in_total
        - price_sources
        - note
      properties:
        total_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        known_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        total_null_reasons:
          type: array
          items:
            type: string
            enum:
              - coverage_incomplete
              - empty_universe
              - unpriced_legs
              - indicative_legs
              - stale_legs
              - peg_unverified
              - price_source_unavailable
        unpriced_position_count:
          type: integer
        priced_leg_count:
          type: integer
        indicative_leg_count:
          type: integer
        unpriced_leg_count:
          type: integer
        excluded:
          type: object
          additionalProperties: false
          required:
            - indicative_value_usd
            - stale_value_usd
            - estimated_rewards_value_usd
            - claimable_rewards_not_included_usd
            - staker_only_value_usd
          properties:
            indicative_value_usd:
              $ref: '#/components/schemas/NullableDecimal'
            stale_value_usd:
              $ref: '#/components/schemas/NullableDecimal'
            estimated_rewards_value_usd:
              $ref: '#/components/schemas/NullableDecimal'
            claimable_rewards_not_included_usd:
              $ref: '#/components/schemas/NullableDecimal'
            staker_only_value_usd:
              $ref: '#/components/schemas/NullableDecimal'
        valuation_status:
          type: string
          enum:
            - complete
            - partial
            - unavailable
        include_rewards_in_total:
          type: boolean
        price_sources:
          type: array
          items:
            $ref: '#/components/schemas/PriceSourceStatus'
        warnings:
          type: array
          description: >-
            Open enum of wallet-level valuation warnings (always sent by current
            servers; absent in older captures). `unpriced_collateral_debt_only`
            = some position's known value is negative because a debt is priced
            while its collateral is not (05 §6.2); the known value is not that
            position's worth.
          items:
            type: string
        note:
          type: string
    RequestEcho:
      type: object
      required:
        - include
        - protocols
        - freshness_seconds
        - include_rewards_in_total
      properties:
        include:
          type: array
          items:
            type: string
            enum:
              - underlying
              - rewards
              - valuation
              - metadata
              - tokens
        protocols:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/AdapterId'
        freshness_seconds:
          type: integer
        include_rewards_in_total:
          type: boolean
        limit:
          type: integer
    MetadataBlock:
      type: object
      additionalProperties: false
      required:
        - notice
        - assets
        - protocols
      properties:
        notice:
          type: string
        assets:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AssetMetadata'
        protocols:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ProtocolMetadata'
    WalletTokens:
      type: object
      additionalProperties: false
      required:
        - scan
        - holdings
        - note
      properties:
        scan:
          type: object
          additionalProperties: false
          required:
            - spl_token
            - token_2022
            - native_sol
          properties:
            spl_token:
              type: string
              enum:
                - complete
                - error
            token_2022:
              type: string
              enum:
                - complete
                - error
            native_sol:
              type: string
              enum:
                - complete
                - error
        holdings:
          type: array
          items:
            $ref: '#/components/schemas/WalletTokenHolding'
        note:
          type: string
    TokensTotal:
      type: object
      additionalProperties: false
      required:
        - total_value_usd
        - known_value_usd
        - total_null_reasons
        - valuation_status
        - priced_count
        - indicative_count
        - stale_count
        - unpriced_count
        - counted_in_position_count
        - spam_suspected_count
        - note
      properties:
        total_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        known_value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        total_null_reasons:
          type: array
          items:
            type: string
            enum:
              - coverage_incomplete
              - unpriced_tokens
              - indicative_tokens
              - stale_tokens
        valuation_status:
          type: string
          enum:
            - complete
            - partial
            - unavailable
        priced_count:
          type: integer
        indicative_count:
          type: integer
        stale_count:
          type: integer
        unpriced_count:
          type: integer
        counted_in_position_count:
          type: integer
        spam_suspected_count:
          type: integer
        note:
          type: string
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
            details:
              type: object
        request_id:
          type: string
    ProtocolCoverage:
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - adapter_version
        - warnings
        - error_code
      properties:
        id:
          $ref: '#/components/schemas/AdapterId'
        status:
          type: string
          enum:
            - complete
            - partial
            - error
            - not_applicable
            - skipped
        adapter_version:
          type: string
        warnings:
          type: array
          items:
            type: string
        error_code:
          type:
            - string
            - 'null'
          description: >-
            Open enum. DISCOVERY_FAILED, INVALID_ADAPTER_OUTPUT,
            ADAPTER_EXCEPTION, BUDGET_EXCEEDED, DEADLINE_EXCEEDED,
            RPC_UNSUPPORTED, RPC_RATE_LIMITED, ADAPTER_QUARANTINED,
            ADAPTER_DISABLED, ADAPTER_NOT_APPROVED, ADAPTER_SHADOW.
    AdapterId:
      type: string
      pattern: ^[a-z0-9_]{1,64}$
    PositionType:
      type: string
      enum:
        - lending_supply
        - lending_borrow
        - liquidity_concentrated
        - liquidity_bins
        - liquidity_fungible
        - vault
        - native_staking
        - liquid_staking
        - perpetual
        - yield_reward
        - governance_staking
        - unclassified
    PositionCategory:
      type: string
      enum:
        - lending
        - concentrated_lp
        - bin_lp
        - fungible_lp
        - vault
        - native_staking
        - liquid_staking
        - perpetual
        - rewards
    OwnerRole:
      type: string
      enum:
        - authority
        - beneficiary
        - token_holder
        - delegate
        - stake_authority
        - withdraw_authority
        - unknown
    Leg:
      type: object
      additionalProperties: false
      required:
        - role
        - mint
        - symbol
        - amount_raw
        - decimals
        - amount
        - price_usd
        - value_usd
        - pricing_source
        - price_as_of
        - valuation_status
        - confidence
        - claimable
        - amount_basis
        - informational
        - in_totals
        - exclusion_reason
        - context
        - market_price_usd
        - protocol_mark_price_usd
        - price_warnings
      properties:
        role:
          $ref: '#/components/schemas/LegRole'
        mint:
          $ref: '#/components/schemas/Address'
        symbol:
          type:
            - string
            - 'null'
        amount_raw:
          $ref: '#/components/schemas/AtomicAmount'
        decimals:
          type: integer
          minimum: 0
          maximum: 255
        amount:
          $ref: '#/components/schemas/Decimal'
        price_usd:
          $ref: '#/components/schemas/NullableDecimal'
        value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        pricing_source:
          type:
            - string
            - 'null'
        price_as_of:
          type:
            - string
            - 'null'
        valuation_status:
          $ref: '#/components/schemas/LegValuationStatus'
        confidence:
          type:
            - string
            - 'null'
          enum:
            - qualified
            - indicative
            - null
        claimable:
          type:
            - boolean
            - 'null'
        amount_basis:
          type: string
          enum:
            - exact
            - estimated
        informational:
          type: boolean
        in_totals:
          type: boolean
        exclusion_reason:
          oneOf:
            - $ref: '#/components/schemas/ExclusionReason'
            - type: 'null'
        context:
          oneOf:
            - $ref: '#/components/schemas/LegContext'
            - type: 'null'
        market_price_usd:
          $ref: '#/components/schemas/NullableDecimal'
        protocol_mark_price_usd:
          $ref: '#/components/schemas/NullableDecimal'
        price_warnings:
          type: array
          items:
            type: string
    NullableDecimal:
      type:
        - string
        - 'null'
      pattern: ^-?\d+(\.\d+)?$
    PriceSourceStatus:
      type: object
      required:
        - id
        - status
        - as_of
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - ok
            - degraded
            - unavailable
        as_of:
          type:
            - string
            - 'null'
    AssetMetadata:
      type: object
      additionalProperties: false
      required:
        - mint
        - symbol
        - name
        - verified
        - verification
        - logo_url
        - logo
        - website
        - token_program
        - flags
        - provenance
      properties:
        mint:
          $ref: '#/components/schemas/Address'
        symbol:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        verified:
          type: boolean
        verification:
          type:
            - string
            - 'null'
          enum:
            - curated
            - price_seed
            - lst_registry
            - protocol_receipt
            - token_list_solana_labs
            - null
        logo_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Equals logo.sizes."64"; null only when asset serving is disabled or
            no placeholder file exists yet.
        logo:
          oneOf:
            - $ref: '#/components/schemas/Logo'
            - type: 'null'
        website:
          type:
            - string
            - 'null'
          format: uri
          description: https link, verified tokens only; a link, never an image source.
        token_program:
          type:
            - string
            - 'null'
          enum:
            - spl_token
            - token_2022
            - null
        flags:
          type: array
          items:
            type: string
          description: >-
            Open enum: symbol_collision, suspicious_name, metadata_mutable,
            metadata_malformed, metadata_truncated, metadata_pointer_foreign,
            metadata_unavailable, onchain_symbol_changed, logo_pending_review
        provenance:
          $ref: '#/components/schemas/MetadataProvenance'
    ProtocolMetadata:
      type: object
      additionalProperties: false
      required:
        - id
        - brand_id
        - display_name
        - logo_url
        - logo
        - website
        - trademark_owner
        - provenance
      properties:
        id:
          $ref: '#/components/schemas/AdapterId'
        brand_id:
          type: string
        display_name:
          type: string
        logo_url:
          type:
            - string
            - 'null'
          format: uri
        logo:
          oneOf:
            - $ref: '#/components/schemas/Logo'
            - type: 'null'
        website:
          type:
            - string
            - 'null'
          format: uri
        trademark_owner:
          type:
            - string
            - 'null'
        provenance:
          $ref: '#/components/schemas/MetadataProvenance'
    WalletTokenHolding:
      type: object
      additionalProperties: false
      required:
        - mint
        - token_program
        - token_accounts
        - amount_raw
        - decimals
        - amount
        - symbol
        - name
        - logo_url
        - verified
        - spam_suspected
        - price_usd
        - value_usd
        - valuation_status
        - pricing_source
        - price_as_of
        - counted_in_position
        - in_total
      properties:
        mint:
          $ref: '#/components/schemas/Address'
          description: Native SOL uses 11111111111111111111111111111111 (priced as wSOL).
        token_program:
          type: string
          enum:
            - native
            - spl_token
            - token_2022
        token_accounts:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Token accounts summed into this row; empty for native SOL.
        amount_raw:
          $ref: '#/components/schemas/AtomicAmount'
        decimals:
          type: integer
          minimum: 0
          maximum: 255
        amount:
          $ref: '#/components/schemas/Decimal'
        symbol:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        logo_url:
          type:
            - string
            - 'null'
          format: uri
        verified:
          type: boolean
        spam_suspected:
          type: boolean
          description: >-
            Unverified mint that is unpriced or carries a suspicious_name /
            symbol_collision metadata flag. Excluded from tokens_total.
        price_usd:
          $ref: '#/components/schemas/NullableDecimal'
        value_usd:
          $ref: '#/components/schemas/NullableDecimal'
        valuation_status:
          $ref: '#/components/schemas/LegValuationStatus'
        pricing_source:
          type:
            - string
            - 'null'
        price_as_of:
          type:
            - string
            - 'null'
          format: date-time
        counted_in_position:
          type:
            - string
            - 'null'
          description: >-
            Id of the DeFi position that already accounts for this token (LP
            mint, LST / vault share, position NFT); such rows are never in
            tokens_total.
        in_total:
          type: boolean
    ErrorCode:
      type: string
      enum:
        - INVALID_PARAMETER
        - INVALID_ADDRESS
        - UNSUPPORTED_PROTOCOL
        - CURSOR_EXPIRED
        - UNAUTHORIZED
        - NOT_FOUND
        - JOB_NOT_FOUND
        - METHOD_NOT_ALLOWED
        - FORBIDDEN
        - CONFLICT
        - CONFIG_INVALID
        - RATE_LIMITED
        - INTERNAL
        - DB_UNAVAILABLE
        - QUEUE_UNAVAILABLE
        - SNAPSHOT_UNAVAILABLE
        - SCAN_FAILED
        - RPC_BUDGET_EXHAUSTED
        - ASSET_REMOVED
    LegRole:
      type: string
      enum:
        - supplied
        - collateral
        - borrowed
        - liquidity
        - staked
        - share
        - underlying
        - margin
        - unrealized_pnl
        - funding
        - fee
        - reward
    AtomicAmount:
      type: string
      pattern: ^\d+$
    Decimal:
      type: string
      pattern: ^-?\d+(\.\d+)?$
    LegValuationStatus:
      type: string
      enum:
        - priced
        - indicative
        - stale
        - unsupported
        - no_liquidity
        - unlicensed
        - error
        - not_requested
    ExclusionReason:
      type: string
      enum:
        - indicative
        - stale
        - unpriced
        - estimated
        - staker_only
        - rewards_not_included
        - informational
        - nested
    LegContext:
      type: object
      additionalProperties: false
      required:
        - account
        - as_of_slot
        - status
        - reward_index
      properties:
        account:
          type:
            - string
            - 'null'
        as_of_slot:
          type:
            - integer
            - 'null'
        status:
          type:
            - string
            - 'null'
          enum:
            - active
            - activating
            - deactivating
            - inactive
            - warming_up
            - unstaking
            - null
        reward_index:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 9
    Logo:
      type: object
      additionalProperties: false
      required:
        - url
        - sizes
        - png_url
        - placeholder
        - placeholder_reason
        - initials
        - color
      properties:
        url:
          type: string
          format: uri
          description: 128 px WebP on our own host (/assets/v1/). Never a third-party URL.
        sizes:
          type: object
          additionalProperties: false
          properties:
            '32':
              type: string
              format: uri
            '64':
              type: string
              format: uri
            '128':
              type: string
              format: uri
        png_url:
          type: string
          format: uri
        placeholder:
          type: boolean
        placeholder_reason:
          type:
            - string
            - 'null'
          enum:
            - unverified
            - not_available
            - null
        initials:
          type: string
          maxLength: 2
          description: 1–2 uppercase letters from the symbol (or '?')
        color:
          type: string
          pattern: ^#[0-9a-f]{6}$
          description: >-
            Background colour for a text avatar, from an 8-colour palette chosen
            by sha256(subject id).
    MetadataProvenance:
      type: object
      additionalProperties: false
      required:
        - name_source
        - symbol_source
        - logo_source
        - logo_licence
        - onchain_slot
        - updated_at
      properties:
        name_source:
          type:
            - string
            - 'null'
          enum:
            - curated
            - token_2022
            - metaplex
            - token_list_solana_labs
            - null
        symbol_source:
          type:
            - string
            - 'null'
          enum:
            - curated
            - token_2022
            - metaplex
            - token_list_solana_labs
            - adapter
            - null
        logo_source:
          type: string
          enum:
            - token_2022_uri
            - metaplex_uri
            - brand_kit
            - protocol_github
            - favicon
            - curated_file
            - token_list_solana_labs
            - brand
            - placeholder
        logo_licence:
          type: string
          enum:
            - issuer_published
            - brand_guidelines
            - apache-2.0
            - permission
            - own_work
        onchain_slot:
          type:
            - integer
            - 'null'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
  responses:
    BadRequest:
      description: >-
        INVALID_PARAMETER, INVALID_ADDRESS, UNSUPPORTED_PROTOCOL or
        CURSOR_EXPIRED
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: UNAUTHORIZED
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    MethodNotAllowed:
      description: METHOD_NOT_ALLOWED
      headers:
        Allow:
          schema:
            type: string
            const: GET, HEAD, OPTIONS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: RATE_LIMITED
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Internal:
      description: INTERNAL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unavailable:
      description: >-
        DB_UNAVAILABLE, QUEUE_UNAVAILABLE, SNAPSHOT_UNAVAILABLE, SCAN_FAILED,
        CONFIG_INVALID or RPC_BUDGET_EXHAUSTED
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: >-
        PRIVATE_API_TOKEN, required on /v1/* (except /v1/health) while
        configured.

````

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