API status
QSDM has two versioned surfaces, and they version independently.
The most common source of confusion: visitors see /api/v1/health in our footer and
assume the API is "old", because we shipped a "v1 deprecation" in v0.3.2.
It's not — that deprecation was about the mining protocol, not the
HTTP URL prefix.
/api/v2/* endpoint and none planned for the v0.4.x cycle. The
mining protocol is v2-only at consensus
(FORK_V2_HEIGHT = 0) — every v1 proof is rejected at admission, and
the v1 reference miner (cmd/qsdmminer) was dropped from the public release
matrix in v0.3.2. The two "v1"s are unrelated.
/api/v1/* URL stability, wallet self-custody flow,
replay protection, CORS posture, JWT verification and the
POST /api/v1/wallet/mint retirement (HTTP 410 Gone)
are pinned by 6 rows in the api category of the
public audit checklist, all passing. Cross-cutting auth and
transport posture (mTLS, CSRF, JWT secondary-key rotation) lives
under cryptography (5 rows) and network
(5 rows). The page you are reading also resolves to a live audit
surface — GET /api/v1/audit/summary
returns the same score and blocking-findings count this badge
renders, so the badge cannot drift from the JSON contract. See
audit.html?category=api
for the deep-linked view.
The two versions, side by side
HTTP API — /api/v1/*
Every public endpoint lives under /api/v1/*. This includes the
wallet self-custody flow (POST /api/v1/wallet/submit-signed,
GET /api/v1/wallet/nonce, GET /api/v1/wallet/balance),
the trust/attestation transparency feeds, the mining work / submit / penalty
endpoints, and the live /api/v1/status health surface.
The v1 in the URL is the API URL prefix, not a deprecation flag.
It signals stable wire compatibility — any change that would break a v1 client
ships behind a new top-level prefix; there is no plan to do that in the v0.4.x cycle.
Source: API_REFERENCE.md, API_VERSIONING.md.
Mining protocol — v2 only
The mining protocol is independent of the HTTP API. Mainnet activated
FORK_V2_HEIGHT = 0 at the Phase-4 chain reset, which means
every v1 proof (CPU-only PoW) is rejected at admission with
ReasonBadVersion. The v1 reference miner
cmd/qsdmminer is no longer cross-compiled or signed by
release-container.yml — only qsdmminer-console --protocol=v2
is published.
Live GET /api/v1/status self-advertises the posture in its
mining block: protocol_versions_accepted: [2],
fork_v2_active: true. Both qsdmminer and
qsdmminer-console preflight this on startup and refuse to mine
with a v1 caller against a v2-active validator.
Source: MINING_PROTOCOL_V2.md, MINER_QUICKSTART.md.
Live HTTP API surface
The endpoints visitors can probe right now from any browser or
curl command — same paths an SDK would call.
Retired in v0.3.3: POST /api/v1/wallet/mint now returns HTTP 410 Gone
with a migration block. The supply-inflation surface from the seed-faucet era is
structurally closed; any client still hitting it shows up in the
qsdm_wallet_mint_total{result="gone"} counter on the dashboard.
Why "v1 deprecation" did not move the URL
The change in v0.3.2 (commit f727fef) was a
posture refresh on /api/v1/status, a
preflight gate in both miners, and a documentation rewrite of
MINER_QUICKSTART.md — all about the mining-protocol version
selected by the miner before it asks for work. The HTTP server's URL routing
was untouched. Test
TestDeriveMetricsURL_RejectsMissingV1Suffix in
cmd/qsdmcli explicitly rejects /api/v2 as a base URL —
no such surface exists in the running validator.