> ## 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. > How Darknyx signals readiness and degraded mode, so you can check it before trading and back off when subsystems are down. # System Status **TL;DR** `GET /system/status` is a public readiness snapshot: is matching running, is settlement wired, is an oracle attached, and what slot the engine is on. A `degraded` flag tells you, in one boolean, whether to back off before you hit a write failure. ## GET /system/status Public, with no authentication. ### Response ```json theme={null} { "degraded": false, "matcher_running": true, "settle_enabled": true, "oracle_configured": true, "current_slot": 309482113, "version": "…" } ``` | Field | Type | Description | | ------------------- | ------- | ------------------------------------------------------------------------------------------------ | | `degraded` | boolean | `true` when settlement is unavailable, global readiness fails, or at least one market is paused. | | `matcher_running` | boolean | At least one market can currently accept and match orders. | | `settle_enabled` | boolean | The on-chain settlement pipeline is wired (matches will settle). | | `oracle_configured` | boolean | A price oracle is attached (the clearing-price reference). | | `current_slot` | integer | The engine's current view of the Solana slot. | | `version` | string | The running engine's build version. | ## When degradation occurs The venue is `degraded` when a core subsystem is unavailable: the matching tick is not running, the settlement pipeline is not wired, or the finalized governance/signer view no longer matches the boot-approved configuration. On a multi-market venue, a governed-market mismatch pauses new trading venue-wide rather than leaving some books running against uncertain authority. An oracle failure is narrower: it pauses only markets bound to the affected feed. In that partial state `degraded` is true, `matcher_running` can remain true, and each `/instruments` entry reports its own `trading_enabled` value. Under a venue-wide readiness failure, new place and modify operations fail closed with `503 Service Unavailable` for every market. Under market-local oracle degradation, only place/modify for the affected market fails; a healthy symbol whose own `trading_enabled` remains true can continue even while the venue-level `degraded` summary is true. Cancels, authenticated reads, and reconciliation continue so a trader can reduce risk and the engine can resolve already-pending settlements. ## How it manifests | Surface | Behavior under degradation | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REST order management | New place/modify may return HTTP `503` with stable code `5001`; cancel remains available. Reads (`/instruments`, `/transparency`, `/tree/*`) generally remain available, except a diverged tree shard fails its `/tree/*` reads closed with `5002`. | | WebSocket trading | `order.place` / `order.modify` may return an `error` with `code: 5001`; cancellation remains available. | | `/health` | Still returns `200` (the engine process is up), which is why `/system/status` is the better readiness signal for a trading client. | ## Best practices * **Use both readiness levels.** Check `/system/status` for venue health, then the chosen `/instruments/{symbol}` entry's `trading_enabled` value. Always handle a racing `503` from place/modify. Do not block a healthy symbol merely because another market makes the venue-level `degraded` summary true. * **Use it, not `/health`, for readiness.** `/health` answers "is the process up"; `/system/status` answers "can I trade right now." * **Back off and poll.** On a `503`, refresh `/system/status` plus the requested instrument. Resume that symbol when its own `trading_enabled` is true; do not wait for `degraded=false` when only another market remains paused. A venue-wide failure keeps every instrument disabled until global readiness recovers. * **Surface it.** It is public and leaks nothing, so it is safe to show on a status page or wire into client-side health checks. ## OpenAPI ````yaml api-reference/openapi/darknyx-public.yaml GET /system/status 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: /system/status: get: tags: - system summary: | Liveness / degraded-mode snapshot. Public, unauthenticated. description: | Reports whether the matching tick and the on-chain settle pipeline are wired, whether an oracle cache is attached, and the TEE's current Solana slot. `degraded` is `true` whenever the settle pipeline is down, every matcher is unavailable, or any market is fail-closed. `matcher_running` remains true when at least one market can trade. On a multi-market venue, finalized-governance drift pauses every book, while an oracle failure pauses only markets bound to that feed. Read each instrument's `trading_enabled` field for market-local readiness. Cancels, reads, and pending-settlement reconciliation continue. responses: '200': description: Engine status snapshot. content: application/json: schema: type: object required: - degraded - matcher_running - settle_enabled - oracle_configured - oracle_mode - oracle_max_age_ms - current_slot - version properties: degraded: type: boolean description: >- true when any market is paused or matching/governance/settlement readiness is down. matcher_running: type: boolean description: >- true when at least one configured market can accept and match new orders. settle_enabled: type: boolean description: The on-chain settle pipeline is wired. oracle_configured: type: boolean description: An oracle cache (clearing-price reference) is attached. oracle_mode: type: - string - 'null' enum: - pyth-router-quorum-v1 - pyth-solana-push-v1 - null description: Versioned oracle source selected exclusively at boot. oracle_max_age_ms: type: - integer - 'null' format: uint64 description: Source-specific signed-price age budget. current_slot: type: integer format: uint64 version: type: string '429': $ref: '#/components/responses/PublicRateLimited' components: 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' 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 ````