> ## 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. > The current Merkle root and leaf count of the on-chain note commitment tree. # Tree Root A proof is only valid against the root it was built for. Read the root, build the proof, and submit before the tree advances, or the vault rejects the spend with `StaleMerkleRoot (6004)`. ## OpenAPI ````yaml api-reference/openapi/darknyx-public.yaml GET /tree/root 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/root: get: tags: - tree summary: | Current Merkle root + leaf count. description: | Convenience read served by the TEE's in-memory Merkle mirror. Eventually-consistent with the on-chain MerkleTree[tree_id].current_root and may lag briefly after a confirmed append. Under tree-sharding the on-chain tree is split into `num_trees` per-shard `MerkleTree` accounts; pass `?tree_id` to select a shard (default 0). The response echoes the `tree_id` it served. For correctness-sensitive reads, fetch the selected MerkleTree account from Solana and independently verify the returned root. If this shard's mirror is known to diverge from Solana, the endpoint fails closed with 503/code 5002. Do not build a proof from that mirror; read the tree from Solana until the venue cold-resyncs it. parameters: - name: tree_id in: query required: false schema: type: integer default: 0 description: Which Merkle shard to read (0..num_trees-1). Default 0. responses: '200': description: Tree root snapshot. content: application/json: schema: $ref: '#/components/schemas/TreeRoot' '429': $ref: '#/components/responses/PublicRateLimited' '503': description: Mirror diverged from Solana (code 5002); use an on-chain tree read. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TreeRoot: type: object required: - tree_id - merkle_root - leaf_count - on_chain_slot properties: tree_id: type: integer default: 0 description: | Which Merkle shard this root is for (echoes the request's `?tree_id`, default 0). Present under tree-sharding. merkle_root: type: string description: | Current Merkle root of shard `tree_id`, hex-encoded. It should equal finalized on-chain `MerkleTree[tree_id].current_root`. Historical roots accepted through the on-chain 64-entry history are not returned by this endpoint. leaf_count: type: integer description: Leaf count of this shard. on_chain_slot: type: integer description: | Solana slot at which the TEE last synced this shard's mirror from on-chain `MerkleTree[tree_id]`. 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 responses: PublicRateLimited: description: | The venue-wide public-route allowance is exhausted (SW-02). Every unauthenticated route shares one weighted bucket: client traffic reaches the enclave through the dstack gateway, so all requests present the same source address and a per-caller limit here would bound the venue rather than any individual caller. Weights follow real cost — `/attestation` (a TDX quote per request, uncacheable because the caller's nonce is the point) is the heaviest, `/transparency` is moderate, and in-memory reads are ~100x lighter. Honest polling sits far inside the budget. `POST /auth/token` is deliberately EXEMPT from this bucket and cannot return this response: metering it venue-wide would let junk credentials exhaust a shared allowance and lock every real account out of authenticating. Its own `429`, documented on that operation, comes from the per-account login bucket instead. `Retry-After` carries the back-off in seconds. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' ````