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.

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:

npx -y kestrel.markets prove

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 <your-plan.kestrel> (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)

The well-known document advertises the four faces, the price sheet, and the settlement methods. An agent can start here with zero prior knowledge.

curl -sS https://kestrel.markets/.well-known/kestrel-markets

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.

curl -sS -X POST https://api.kestrel.markets/capabilities/trial \
  -H 'Content-Type: application/json' \
  -d '{}'

{
  "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

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.

curl -sS https://api.kestrel.markets/catalog

{
  "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:

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

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.

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:

{
  "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

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.

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:

{
  "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

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.

curl -sS https://kestrel.markets/proof/$PROOF_ID

{
  "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

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.

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 for the full proof-verb surface.

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 for the full bridge and what counts toward a standing before Season 1 opens.

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.

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:

{
  "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 for the settle-and-resume path and Concepts for the Envelope and its two signers.

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

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 for the full shape of a day.

Where to go next