API overview
The API is JSON in and JSON out. Base URL: https://api.alphaassay.com. Pure/read
operations can be reproduced with the same explicit as_of; stateful operations expose their
effective timestamp and only replay a stored response under the documented idempotency contract. The same engine also serves MCP, but shared engine
code does not make the transports byte-for-byte or route-for-tool identical.
How do REST, MCP and x402 differ?
| surface | published contract | authentication and scope |
|---|---|---|
| hosted MCP | 21 public tools from tools/list (6 free, 15 metered) | streamable HTTP; paid tools take an api_key tool argument |
| local stdio | 50 operator/research tools in a separate catalog | development/runtime surface; not the hosted customer storefront |
| REST | routes in /openapi.json | public, bearer-authenticated and REST-only operations; request schemas and bounds can differ from MCP |
| x402 | POST /x402/v1/gauntlet only | accountless REST gauntlet with payment and receipt envelopes; not universal MCP billing |
The generated transport-parity contract classifies shared operations as exact, translated or partial, and marks MCP-only and REST-only operations explicitly; callers must not infer parity from similar names. Current public counts and engine facts come from https://api.alphaassay.com/v1/meta/facts; current prices come from https://api.alphaassay.com/v1/meta/pricing.
Which endpoints need no account?
The public endpoints need no account: run a golden specimen through the full battery, verify any certificate, pull the current persisted calibration population/status snapshot, pull the anonymised graveyard digest, and query the family-budget arithmetic — all free and rate-limited. They are listed below.
| endpoint | what it does |
|---|---|
| POST /v1/assay/demo | run a golden specimen through the full battery — free, rate-limited |
| POST /v1/certificate/verify | authenticity check of any certificate — powers /verify |
| GET /v1/public/calibration | bucketed mature-registration count plus accumulating/insufficient-history state — format |
| GET /v1/public/graveyard-digest | anonymised statistics of failed strategy families |
| GET /v1/public/forward-stats | aggregated forward record of all monitored certificates — evaluation timing cannot be gamed, by construction |
| GET /v1/public/engine-assay/suite | the engine test suite: every qualitatively distinct fill situation, ground truth withheld |
| GET /v1/public/engine-assay/starter | an annotated teaching subset of the suite, with ground truth — free |
| GET /v1/public/family-budget | pure math over the published survival thresholds: what survival demands at N trials, and the trial count at which a given result dies (break_even_n) — reads no family data |
| GET /v1/meta/facts | the platform's self-description — engine version, stage order, attack set, register size — in the standard signed-or-explicitly-unsigned envelope. When signed:true, an offline raw-signature check detects changed signed bytes; full platform trust additionally needs an independently pinned root, the signed trust bundle and complete key/revocation history. |
| POST /v1/tear-sheet | render any gauntlet verdict dossier as a shareable tear sheet — free |
How do paid endpoints work?
Hosted MCP metered tools take an api_key argument and publish their current amounts at
/v1/meta/pricing. Bearer REST operations use
the routes and schemas in /openapi.json; certificate issuance is its own post-evaluation
lifecycle action. Accountless x402 is limited to POST
/x402/v1/gauntlet. The demo shape must not be assumed for other operations.
What conventions does every response follow?
Every response carries a request id header for support and replay. Errors are structured JSON with the same honesty as verdicts — a rate limit says exactly when to retry, an invalid input says exactly which field. And every assay response ends with the disclaimer that is also our business model: methodology audit, not investment advice.