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

> Page through tree leaves to rebuild a local mirror from cold.

# Leaves

For clients catching up from cold or verifying an independently built mirror. Ordinary
trading does not need it.

This is an authenticated read. Complete
[Transport & Attestation](../getting-started/transport-and-attestation.mdx)
before sending the bearer token.


## OpenAPI

````yaml api-reference/openapi/darknyx-public.yaml GET /tree/leaves
openapi: 3.1.0
info:
  title: Darknyx TEE API
  version: 4.1.0
  description: |
    Public + authenticated REST and WebSocket API for the Darknyx dark pool
    TEE matching layer. One attested endpoint may expose several independently
    routed spot markets. Pairs with the v2 on-chain custody program
    (vault, program ID `C63vKvysCzX55PKraas4Wc22ijqjGJQdPC1mrzCFVWZx`).
  contact:
    name: Darknyx engineering
  license:
    name: PolyForm Perimeter License 1.0.1
    url: https://polyformproject.org/licenses/perimeter/1.0.1
servers:
  - url: https://api.darknyx.example.com
    description: Mainnet placeholder; use the origin published with a deployment.
  - url: https://api.devnet.darknyx.example.com
    description: Devnet placeholder; use the origin published with a deployment.
security: []
tags:
  - name: auth
    description: OAuth2 client-credentials and bearer-token lifecycle.
  - name: attestation
    description: |
      Darknyx engine and transport attestation plus the deployment gateway's
      separate evidence bundle. Programmatic clients verify the certificate on
      their actual connection with `/transport-attestation` before any
      credential or sensitive write. `/evidences/*` describes surrounding
      ingress infrastructure and is not a substitute for the engine check.
  - name: info
    description: |
      Application/instance metadata, boot-session id, and settlement signers.
      Verify measured identity through `/attestation`, not self-reported fields.
  - name: instruments
    description: Public market metadata.
  - name: orders
    description: Place / cancel / modify / inspect orders.
  - name: system
    description: Public engine liveness + server time (GTT slot conversion).
  - name: account
    description: Per-account open orders and preferences. Balances remain client-derived.
  - name: tree
    description: >-
      Convenience Merkle-tree mirror; clients can verify the same state on
      Solana.
  - name: transparency
    description: Public solvency snapshot + engine identity + aggregate stats.
  - name: settlement
    description: Batch settlement status (TEE → L1 tx_signature lookup).
paths:
  /tree/leaves:
    get:
      tags:
        - tree
      summary: |
        Page through leaves. Used by clients catching up cold or
        re-syncing after a long disconnect.
      description: |
        Returns at most 10,000 leaves per request. A mirror known to diverge
        from Solana fails closed with 503/code 5002.
      parameters:
        - name: from
          in: query
          required: true
          schema:
            type: integer
        - name: to
          in: query
          required: true
          schema:
            type: integer
        - name: tree_id
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Which Merkle shard to page (0..num_trees-1). Default 0.
      responses:
        '200':
          description: Leaves in [from, to) on the selected shard.
          content:
            application/json:
              schema:
                type: object
                required:
                  - leaves
                  - merkle_root
                properties:
                  leaves:
                    type: array
                    items:
                      type: object
                      required:
                        - leaf_index
                        - value
                      properties:
                        leaf_index:
                          type: integer
                        value:
                          type: string
                  merkle_root:
                    type: string
        '401':
          description: >-
            Missing / invalid / expired / revoked bearer token, or a token
            invalidated by the operator.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The account is suspended.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Mirror diverged from Solana (code 5002); use an on-chain tree read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  schemas:
    Error:
      type: object
      description: |
        The error envelope. Every non-2xx response renders as this shape, with
        the mapped HTTP status. Success responses are NOT enveloped (their typed
        body is returned directly). Every response — success and error — carries
        an `x-request-id` header for correlation with server logs.
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: |
            Stable numeric error code. Ranges: 1000–1099 request validation,
            1100–1199 auth, 1200–1299 conflict, 1300–1399 not found, 1400–1499
            rate limit, 5000+ server. See the Error Codes reference.

            One exception to the ranges: `1402` is returned with HTTP 503, not
            429. It signals that credential verification is momentarily at
            capacity and was refused rather than queued. Branch on the numeric
            code rather than inferring the status from its range.
          example: 1102
        message:
          type: string
          example: trading_key_signature does not verify against the canonical body
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Short-lived (≤ 1h) bearer token from POST /auth/token.

        Expiry is EXACT — there is no grace period past `expires_in`, on REST
        or on the streaming transport. Refresh on a margin.

        A structurally valid, unexpired token is still refused when it has been
        revoked (401), when the operator has invalidated the tokens the account
        was holding (401), or when the account is suspended (403). Suspension
        also blocks issuing a new one, so re-authenticating does not clear it.

````