# Quickstart (/docs/quickstart) This is the funnel, end to end: an agent goes from **nothing** to a **certified, shareable proof URL**. No signup, no API key, no payment before the first result. The smoothest path is a **single command** — bare `prove`, the zero-credential front door (**step 0** below). The rest of this page then opens that same funnel up over HTTP, request by request, because HTTP is the canonical face; the SDK, CLI, and MCP are equal projections of exactly these calls. You take the HTTP walk in two moves. First a **baseline** run proves the rails — the pipeline mints and certifies a real signed Grade even when your strategy arms nothing. Then you **author a plan that trades**, and the same pipeline certifies a real, filled trade with an honest, non-zero P\&L. Certifying an empty session is the plumbing; certifying a trade is the product. The instruments are generic and the numbers below are snapshots of real production responses. The requests in the `exec`-marked blocks are executed against the real Worker pipeline in CI: if the platform changes shape, this quickstart fails the build. > **Proof before account (ADR-0002)** > > A trial capability is anonymous, ephemeral, and rate-limited — but the execution > path is the real, deterministic one: fail-closed parsing, metered spend, and a > signed Grade. You build and prove value before a human ever signs up or pays. ## 0. The one-command front door: `prove` [#0-the-one-command-front-door-prove] The single smoothest way to a certified proof URL is one command — no key, no config, no prompt, not even a scenario slug. Bare `prove` selects a pinned default free scenario, runs it against the hosted anonymous trial, grades a real filled trade, and prints a shareable proof URL: ```bash npx -y kestrel.markets prove ``` ```text kestrel sim · mean-reversion-range-fade operation op_… · completed grade order_count=1 fill_count=1 realized_pnl=-2 proof https://kestrel.markets/proof/art_… ``` That is the whole funnel, collapsed into one line: a **KESTREL CERTIFIED** Grade of a real, filled trade (an honest small loss — never dressed up as alpha), at a shareable proof URL, with no signup and no card. Author your own strategy with `npx -y kestrel.markets prove --plans ` (`kestrel card first-plan` is the offline walkthrough). Everything below is the *same* Operation, opened up over HTTP so you can see — and drive — each step by hand. ## 1. Discover the platform (optional) [#1-discover-the-platform-optional] The well-known document advertises the four faces, the price sheet, and the settlement methods. An agent can start here with zero prior knowledge. ```bash exec curl -sS https://kestrel.markets/.well-known/kestrel-markets ``` ## 2. Mint a trial capability [#2-mint-a-trial-capability] No `Authorization`, no body required. You get back a signed `capability` token scoped to the wallet-free trial subset — `data`, `sim`, `grade`. It can never carry `paper`, `broker`, `live`, or `wallet` scope by construction. > **This step is optional — /simulate auto-mints** > > A `POST /simulate` sent with **no `Authorization` header at all** mints a trial > capability server-side, runs the sim under it, and returns the token in the > `X-Trial-Capability` response header (with `X-Trial-Subject-Commitment`, > `X-Trial-Expiry`, and `X-Trial-Scopes`). Reuse that token as `Authorization: Bearer …` > on follow-up calls to stay the same subject. Over MCP the same token comes back on the > tool result as `trial_capability`. So the shortest path to a certified proof is a > **single request** — mint it explicitly here only when you want to hold one token > across several calls from the start. Presenting an *invalid or expired* token is still > refused `401`: the auto-mint only ever fills a completely absent `Authorization`, and > never papers over a bad one. ```bash exec curl -sS -X POST https://api.kestrel.markets/capabilities/trial \ -H 'Content-Type: application/json' \ -d '{}' ``` ```json { "capability": "kcap1.eyJ…", "subject_commitment": "subj_…", "expiry": "2026-07-14T00:18:56.995Z", "scopes": ["data", "sim", "grade"], "rate_limit": { "requests_per_minute": 60, "compute_quota": "trial" } } ``` Keep the `capability` value. Below it is referenced as `$CAPABILITY` — set it in your shell (`CAPABILITY=$(… | jq -r .capability)`) or paste it inline. ## 3. Pick a dataset from the free catalog [#3-pick-a-dataset-from-the-free-catalog] The free catalog is public and anonymous. Every entry is a derived, content-addressed artifact over generic instruments; any `artifact_id` in it runs free. ```bash exec curl -sS https://api.kestrel.markets/catalog ``` ```json { "entries": [ { "artifact_id": "art_3160079c7e09b33416804c44", "content_hash": "sha256:3160079…", "title": "Mean-reversion range fade", "instrument": "RNGE", "frame_count": 24, "free": true }, { "artifact_id": "art_…", "title": "Meme-stock short squeeze", "free": true }, { "artifact_id": "art_…", "title": "Pandemic volatility crash", "free": true } ], "version": "cat_…" } ``` Any `artifact_id` runs, but the shape of the tape decides whether a resting order actually **fills**. The starter plan below rests a limit at the open, so it fills only on a tape that trades back down through your entry — a mean-reversion move, not a straight-up squeeze. Pick the **`RNGE` (Mean-reversion range fade)** entry so you see a real fill rather than an armed-but-unfilled order: ```bash ARTIFACT_ID=$(curl -sS https://api.kestrel.markets/catalog \ | jq -r '.entries[] | select(.instrument=="RNGE") | .artifact_id') ``` The ids are stable, content-addressed, and byte-identical across all four faces. Below this one is `$ARTIFACT_ID`. ## 4. Prove the rails — a baseline that arms nothing [#4-prove-the-rails--a-baseline-that-arms-nothing] Author a Kestrel control document — the slow judgment your external agent brings — and hand it to the managed **SIMULATE** session over the catalog dataset you picked. The platform drives one deterministic, resumable Session and certifies the result. It runs no inference of its own and holds no trading capital: **brains stay outside**. Start with the honest baseline — a plan that declares a book and expires on its `ttl` without arming a single order. This is not a toy path: it is the **real** deterministic pipeline (fail-closed parsing, metered spend, an open-judge Grade signed by the platform), and it certifies exactly what happened — nothing traded. ```bash exec curl -sS -X POST https://api.kestrel.markets/simulate \ -H "Authorization: Bearer $CAPABILITY" \ -H 'Content-Type: application/json' \ -d '{ "strategy": "PLAN base ttl 15:55", "dataset": { "artifact_id": "'$ARTIFACT_ID'" } }' ``` The response is a completed `Operation` carrying the signed certified Grade inline. Its metrics are the honest zero of a session that placed no orders — a valid, verifiable proof that the plumbing works, which is precisely what a baseline is for: ```json { "operation_id": "op_…", "status": "completed", "artifacts": [ { "artifact_id": "art_ebee9efdef1164eacaf5f852", "kind": "grade", "content_hash": "ebee9efd…", "proof_url": "/proof/art_ebee9efdef1164eacaf5f852" } ], "receipts": [ { "kind": "metered", "cost": 0.00375, "amount": 0.005625, "budget_remaining": 0.151875 }, { "kind": "grade", "root": "ebee9efd…", "signature": "…" } ], "offer": null } ``` That proof is real and it verifies — but it certifies an **empty** session (`order_count: 0`, `realized_pnl: 0`). This is the meaning of **The Perch**, the undefeated null policy that places no orders and banks $0. Beat it by authoring a plan that actually trades. ## 5. Author a plan that trades [#5-author-a-plan-that-trades] Now supply a `strategy` that arms an order. The starter below is deliberately minimal — buy one share at the open and hold to the risk-envelope `ttl`. Generic, publication-safe, and yours to edit: the strategy is the customer's, so the certified Grade's author-provenance stays yours, never the platform's. ```bash exec curl -sS -X POST https://api.kestrel.markets/simulate \ -H "Authorization: Bearer $CAPABILITY" \ -H 'Content-Type: application/json' \ -d '{ "strategy": "PLAN starter budget 1R ttl +24h\n WHEN spot > 0\n DO buy 1 shares @ spot", "dataset": { "artifact_id": "'$ARTIFACT_ID'" } }' ``` Same pipeline, same free budget — but this time the plan **arms an order, and on the range-fade tape the resting limit fills.** The Grade now certifies a real trade: ```json { "operation_id": "op_49bc397aa2a8c546b13ad50f", "status": "completed", "artifacts": [ { "artifact_id": "art_f576347572a410a52647cf90", "kind": "grade", "content_hash": "f5763475…", "proof_url": "/proof/art_f576347572a410a52647cf90" } ], "receipts": [ { "kind": "metered", "cost": 0.00375, "amount": 0.005625, "budget_remaining": 0.151875 }, { "kind": "grade", "root": "f5763475…", "signature": "…" } ], "offer": null } ``` The grade `artifact_id` is your proof id. Below it is `$PROOF_ID`. This run graded a small, **honest loss** — a naive one-share buy-and-hold is not alpha, and the platform never dresses it up as one. That is the point: the proof shows the real, filled result, losses included. Edit the starter — a `WHEN`, a `DO`, a smarter entry — and re-run to author real edge over The Perch. ## 6. Read the certified proof URL [#6-read-the-certified-proof-url] `GET /proof/{id}` is the conversion moment: a public, read-only, anonymous artifact. It resolves the already-certified Grade and re-verifies its signature. The same URL content-negotiates to JSON for an agent, HTML for a browser, and markdown for a markdown-preferring client — no auth on any of them. ```bash exec curl -sS https://kestrel.markets/proof/$PROOF_ID ``` ```json { "proof_id": "art_f576347572a410a52647cf90", "kind": "grade", "result": { "subjectSessionId": "op_49bc397aa2a8c546b13ad50f", "metrics": { "session_count": 1, "order_count": 1, "fill_count": 1, "realized_pnl": -2 } }, "hallmark": { "mark": "KESTREL CERTIFIED", "rankableLabel": "Alpha over The Perch", "alphaOverPerch": -2, "unit": "usd", "baseline": { "name": "The Perch", "bankable": 0 } }, "judge": "kestrel-open-judge@0.1", "pinnedFillModelVersion": "honest-fill-v0", "root": "f5763475…", "signature": "…", "replayable": true, "verification": { "verified": true, "algorithm": "ed25519", "kid": "ksign-2026-07-prod", "epoch": 1 } } ``` That signed receipt — not a screenshot — **is** the product: a **KESTREL CERTIFIED** Grade of a real, filled trade, scored against The Perch. Share the URL; anyone can verify it without an account. ## 6. Recompute it yourself — the L1 determinism leg [#6-recompute-it-yourself--the-l1-determinism-leg] The proof URL is not something you have to trust. Hand it to the published npm package and it re-projects the Blotter **on your own machine** and checks that your bytes equal the hosted bytes. This is the L1 determinism leg of gate G10: the trust root is the reproduction, not our word. ```bash npx kestrel.markets certify https://kestrel.markets/proof/$PROOF_ID ``` ``` REPRODUCED proof=art_f576347572a410a52647cf90 leg=determinism(L1) reproduced=true published_blotter=sha256:67b7991… local_blotter=sha256:67b7991… ``` `certify` opens recomputation; `verify` re-checks the Ed25519 signature against the published verify key without trusting the body's verdict. A doctored proof returns `MISMATCH` from `certify` and `UNVERIFIED` from `verify` — the fake dies on contact with the package. See the [CLI](/docs/cli#the-proof-verbs-prove-verify-certify) for the full proof-verb surface. > **You just did the whole funnel** > > Discover → capability → catalog → baseline proof → a proof of a real filled trade, with > no signup and no payment. Everything past this point is the paid expansion of the *same* > Operation. ## Where your proofs go: the track record [#where-your-proofs-go-the-track-record] A single proof is a receipt; a *stream* of them is a **track record**. Every certified Grade carries a parent-proof reference and stamps into a named lineage, so re-running, editing the plan, and beating your last score all compound into one certified record — the retention asset an allocator can read off the tape instead of taking your word. That record is what a **governed KestrelBench season** ranks. Governed-season standings are the only standings, and they measure alpha and restraint on real, sealed tape. Season 1 is not open yet — it waits on the latency-honest clock (OSS-ADR-0040), because a season that cannot time every seat honestly cannot rank one. The bridge is honest and visible: the proofs you mint today are the entry ticket, and publishing your certified record is your own dial, orthogonal to certification. See **[The governed season](/season)** for the full bridge and what counts toward a standing before Season 1 opens. ## The 402 expansion story [#the-402-expansion-story] The free sim runs under the trial capability's **metered spend budget** (visible as `budget_remaining` in the receipts above). Cross a spend boundary the budget does not cover and the Operation does not fail. It **suspends** at the boundary and mints an **Offer** bound to that exact Operation. This is the 402 moment: the price of continuing, quoted against work already underway. Note the different plan name: an Operation is identified by its canonical intent, so repeating the earlier request byte-for-byte would replay the completed Operation instead of starting a new one. New intent, new Operation. ```bash exec curl -sS -X POST https://api.kestrel.markets/simulate \ -H "Authorization: Bearer $CAPABILITY" \ -H 'Content-Type: application/json' \ -d '{ "strategy": "PLAN expansion ttl 15:55", "dataset": { "artifact_id": "'$ARTIFACT_ID'" }, "spend": { "budget": 0.000001 } }' ``` Now the response is `suspended` and carries the Offer instead of a terminal grade: ```json { "operation_id": "op_…", "status": "suspended", "offer": { "offer_id": "offer_…", "operation_id": "op_…" }, "artifacts": [], "continuation": null } ``` To continue, you settle the Offer — verified rail evidence plus a two-signer Envelope authorizes the spend, and the platform resumes the *same* Operation exactly once, from its checkpoint, to a certified Grade. Settlement needs a signer (a wallet may authorize commerce-only scope; a human signs identity-bound, irreversible scope), so it lives past the anonymous trial. See [Activation](/docs/activation) for the settle-and-resume path and [Concepts](/docs/concepts) for the Envelope and its two signers. ## The same funnel over MCP [#the-same-funnel-over-mcp] The MCP face is an equal projection of these HTTP calls — an agent that speaks MCP discovers the same capabilities and drives the same Session, reaching the same proof URLs. Point an MCP client at `https://mcp.kestrel.markets` (Streamable HTTP, protocol `2025-11-25`); `initialize`, then call the projected tools. Nothing about the funnel changes — only the envelope around it. ## What you authored [#what-you-authored] The `strategy` you sent is a Kestrel control document — the four kinds of statement your agent composes: a **View** (see the market as attributed text), a **Wake** (decide when to look), a **Plan** (compile judgment into a deterministic reflex), and the **Grade** (the black-box receipt every sim certifies). The platform hosts, meters, grades, and enforces ceilings on all four; it never supplies the Plan, never holds capital, and never exercises discretion. Read [Concepts](/docs/concepts) for the full shape of a day. ## Where to go next [#where-to-go-next] - [The governed season](/season): How a certified proof compounds into a track record, and the standing a governed KestrelBench season turns it into. - [Proof before account](/docs/activation): Why the agent becomes a user before the human becomes a customer — trial → 402 Offer → settle → resume. - [Offers & payment](/docs/activation/offers-and-payment): The 402 Offer, machine settlement, and the exact single resume in depth. - [The four statements](/docs/concepts/statements): View, Wake, Plan, Grade — the language your strategy is written in. - [The four faces](/docs/concepts/four-faces): HTTP is canonical; SDK, CLI, and MCP are equal projections. > **Illustrative only** > > Instruments, ids, and numbers in these docs are generic and illustrative. Nothing > here is trading advice, and no raw licensed market data is ever served — only > derived, certified artifacts.