Sphinx Exchange — Edge API
The Edge API is the public surface of Sphinx Exchange. It speaks Kalshi-compatible
vocabulary over REST and WebSocket; under the hood, every order is sequenced by an
Aeron Cluster deterministic core, matched by an in-memory C++ engine, and audited
into ClickHouse — see docs/exchange/exchange_software_design.md for the architecture.
This spec covers V0 and V0.1 (in-process MockChain custody, single-node sequencer,
operator-attested resolution authority). See docs/exchange/api/README.md for the human-readable docs,
change process, and codegen instructions.
This file is GENERATED from the per-service markdown in docs/exchange/api/services/ by
tools/gen_openapi.py — edit the markdown, not this file.
The margin-era (derivatives) surface is included here: the margin /v1/snapshot block,
/v1/margin_info, /v1/insurance_fund, /v1/liquidation_metrics, /v1/contract_spec(s),
the reduce_only / post_only order flags, and the mark / account WebSocket
channels — behavior normative in docs/exchange/exchange_derivatives_engine_spec.md §14.
Projection vs engine state: engine-state fields (balances, signed_qty, the margin block,
marks, last_settlement_price = the SV-2 basis) reconcile bit-for-bit against the engine at
one engine_seq_applied; the average entry price is an Edge PROJECTION off the fill tape
(GET /v1/fills), never an engine field — do not conflate the two.
EXTERNAL VARIANT: operator-only (x-internal) operations are omitted.
Authentication
- HTTP: Bearer Auth
- API Key: ReporterKey
Customer-facing authentication. Use the plaintext_key returned by
POST /v1/accounts or POST /v1/credentials as the bearer token.
Tokens have the shape <prefix>.<suffix> where the prefix is the credential's public
identifier (used as a database lookup key) and the suffix is a high-entropy secret. Edge
validates by looking up the credential by prefix and verifying SHA-256 of the suffix
against the stored hash.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Reporter authentication for /v1/instrument/resolution/* (submit + preview). Dev value is the literal string
dev-reporter (configurable via EDGE_REPORTER_API_KEY).
V0 is a single shared secret; V1 introduces reporter quorum (each reporter has its own key + stake).
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-Reporter-Key |
Terms of Service
https://sphx.io/termsLicense
Proprietary