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 checklist rows pin URL stability, wallet submit flow,
replay protection, CORS, and JWT posture.
See audit.html?category=api.
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. The current public network activated
FORK_V2_HEIGHT = 0 at the current 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
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.