> ## Documentation Index > Fetch the complete documentation index at: https://darknyx.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Inspect the per-match jobs and Solana signatures associated with a TEE-local settlement batch handle. # Settlement Status **TL;DR** `GET /settlement/status/{batch_id}` returns every per-match job in a settlement batch. A match can be pending, confirmed, rejected, or ambiguous independently of its siblings. This is an authenticated operational/debug surface; trader clients should treat the orders and fills streams as their primary lifecycle. ## GET /settlement/status/\{batch\_id} `batch_id` is an unsigned integer local to the running engine. It is not an on-chain identifier and the order-read response does not promise a batch-id field. Use this endpoint when an operator or diagnostic response has supplied a known batch handle. The engine retains a bounded recent window of terminal batches, so `404` may mean the handle is unknown **or has aged out**; use the orders and fills streams as the trader-facing lifecycle source. Authenticated with a bearer token: ```bash theme={null} curl -s "$GATEWAY/settlement/status/$BATCH_ID" \ -H "Authorization: Bearer $TOKEN" | jq . ``` ### Response ```json theme={null} { "batch_id": 42, "jobs": [ { "batch_id": 42, "match_idx": 0, "stage": "done", "outcome": { "kind": "confirmed", "signature": "5xQ…", "slot": 309482113, "reconciled_from_consumed_pdas": false }, "created_at_ms": 1784271000000, "last_transition_at_ms": 1784271002880, "lock_buyer_sig": "2aB…", "lock_seller_sig": "3cD…", "verify_sig": "4eF…", "settle_sig": "5xQ…" } ] } ``` Each job has a `match_idx`, current `stage`, independent `outcome`, timestamps, and whichever Solana signatures have confirmed so far. Optional fields are omitted until available. ## Stages `stage` is one of `queued`, `locking_notes`, `proving`, `verifying`, `settling`, `closing`, `done`, or `failed`. A `done` match has confirmed even when the shared marker has not yet been reclaimed; marker close is asynchronous rent cleanup, not part of trade finality. ## Outcomes | `outcome.kind` | Meaning | | -------------- | ----------------------------------------------------------------------------------------------------------- | | `pending` | No final per-match result yet. | | `confirmed` | The settle transaction confirmed, or finalized consumed-note accounts proved it landed. | | `rejected` | A definitive error made the match terminal. | | `ambiguous` | RPC evidence is inconclusive; the engine keeps the match reserved while reconciling or safely redriving it. | Do not infer that every match succeeded from a batch-wide stage. Inspect every job. The user-facing order lifecycle commits a fill only for `confirmed`; a definitive failure emits `settlement_failed` and requires a fresh order after the input lock expires. See [Settlement](/documentation/how-it-works/settlement) for the finality model. ## OpenAPI ````yaml api-reference/openapi/darknyx-public.yaml GET /settlement/status/{batch_id} 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: /settlement/status/{batch_id}: get: tags: - settlement summary: | Per-match settlement outcomes and on-chain signatures for one engine batch ID. parameters: - name: batch_id in: path required: true schema: type: integer format: uint64 responses: '200': description: Settlement status. content: application/json: schema: $ref: '#/components/schemas/SettlementStatus' '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' '404': description: >- Unknown batch ID, including a terminal batch that aged out of bounded retention. content: application/json: schema: $ref: '#/components/schemas/Error' security: - BearerAuth: [] components: schemas: SettlementStatus: type: object required: - batch_id - jobs properties: batch_id: type: integer format: uint64 jobs: type: array description: | Per-match status in match-index order. Confirmed siblings can reach `done` while an ambiguous sibling remains `settling` and redrives. items: type: object required: - batch_id - match_idx - stage - outcome - created_at_ms - last_transition_at_ms properties: batch_id: type: integer format: uint64 match_idx: type: integer format: uint8 stage: type: string enum: - queued - locking_notes - proving - verifying - settling - closing - done - failed outcome: type: object required: - kind description: | `ambiguous` is non-terminal and remains reserved while the TEE reconciles both consumed-note PDAs and redrives within the marker/lock window. `rejected` is terminal. properties: kind: type: string enum: - pending - confirmed - rejected - ambiguous signature: type: string slot: type: integer format: uint64 reconciled_from_consumed_pdas: type: boolean reason: type: string enum: - settlement_rejected - reconciliation_pending description: | A closed-set label, not free-form text. Present only on `rejected` / `ambiguous`. The detailed diagnostic stays inside the enclave: this endpoint is readable by any authenticated account, and internal error text is built by interpolating errors that reach in from the RPC client (SW-01). failed_reason: type: string enum: - rpc_unavailable - prover_failed - leaf_resolution_failed - alt_not_active - settlement_rejected - internal_error description: | Present only when `stage` is `failed`. A closed-set label identifying the CLASS of failure, never the internal message. Which pipeline step failed is implied by the signature fields populated so far. Labels are append-only — a new failure class adds a value, existing ones are never renamed. created_at_ms: type: integer format: uint64 last_transition_at_ms: type: integer format: uint64 lock_buyer_sig: type: string lock_seller_sig: type: string verify_sig: type: string settle_sig: type: string close_sig: type: string description: Normally absent because marker close is asynchronous. 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. ````