Recipe: Pay a 402 with an Agent Wallet

Answer card

When an agent on kestrel.markets requests more than its capability allows, the API replies 402 Payment Required: an Operation ID, the proof already earned, and a platform-signed Offer with machine settlement methods. The agent settles the Offer from its own wallet via Stripe MPP or x402. Verification mints a commerce-only Envelope and the same Operation resumes at its exact checkpoint. No account, no card typed, no human, for a commerce-only scope (data, sim, paper).

When you hit a 402

You reach a paid boundary at the moment an agent asks for something its trial capability cannot cover (say, a longer historical range from licensed data to widen a SIM session). proof-before-account means the agent has already produced value under that trial capability: parsed and validated Kestrel, run free SIM sessions, earned certified Blotters and Grades, and holds a shareable Proof URL. The 402 is the conversion moment: the agent becomes a user before the human becomes a customer.

The response body carries everything needed to settle by machine:

{
  "operation": "op_9f3c...",
  "status": "suspended",
  "proof_url": "https://kestrel.markets/proof/blt_71a...",
  "offer": {
    "offer_id": "ofr_2b8...",
    "intent_hash": "sha256:4d1e...",
    "scope": "data:derived/replay",
    "ceiling": { "amount": "12.00", "asset": "USD" },
    "terms_digest": "sha256:aa07...",
    "expiry": "2026-07-12T18:30:00Z",
    "nonce": "0x9c...",
    "settlement": ["stripe-mpp", "x402"]
  },
  "human_action": "https://kestrel.markets/claim/op_9f3c..."
}

An Offer is a platform-signed commercial proposal bound to one Operation: offer ID, canonical intent hash, exact scope and ceiling, terms digest, expiry, nonce, and supported settlement methods. Accepting it can mint only its named Envelope. Price payment never supplies broker or live authority: certification over custody holds even at the till.

Step 1: Read the Offer, check the scope

Before you pay, verify the Offer is one a wallet is even allowed to sign. The two-signer rule is binding: a wallet signs commerce-only reversible scopes (data, sim, paper). Anything carrying a legal agreement (broker connection, live authority, attestations) requires a human signature and cannot be settled by wallet.

scope = offer.scope              # "data:derived/replay"
assert scope.startswith(("data", "sim", "paper"))
assert offer.ceiling.amount <= my_budget_cap        # worst-case-in-dollars
assert offer.expiry > now()

If the scope is broker:* or live:*, stop. There is no wallet path; route to the human_action URL for claim-and-fund. Say so honestly to your human rather than retrying; the wallet will never gain that authority.

Step 2: Settle from the wallet

The agent controls an external wallet. The platform never holds the key and never treats the payment as trading authority. Present settlement evidence against the Offer via one of the two supported rails.

x402: pay the amount to the Offer's address and return the settlement proof on the same request that got the 402:

POST /operations/op_9f3c.../settle
X-Payment: x402 <settlement-proof>
{ "offer_id": "ofr_2b8...", "nonce": "0x9c..." }

Stripe MPP: accept the Offer through the MPP flow the agent's wallet already holds, then hand the settlement token back:

POST /operations/op_9f3c.../settle
{ "offer_id": "ofr_2b8...", "settlement": "stripe-mpp", "token": "mpp_..." }

Two properties matter here. The nonce makes settlement single-use: a replayed proof cannot buy a second Envelope. The intent_hash binds the payment to the exact canonical intent that raised the 402, so you cannot be upsold something you did not ask for.

Step 3: Verification claims the Workspace and resumes

On a verified payment the platform does four things, atomically, and returns the same Operation ID:

1. Claims the Workspace to the machine payer: the ephemeral trial container becomes durable.
2. Records a Purchase receipt.
3. Mints a commerce-only Root grant plus the exact child Envelope named by the Offer: {scope, budget, ceiling, expiry, revocation}, narrowed downward, mandatory expiry, one-tap revocation.
4. Emits an Authority continuation receipt and resumes the Operation at its exact checkpoint.

{
  "operation": "op_9f3c...",
  "status": "resumed",
  "workspace": "wsp_claimed_1f...",
  "envelope": { "scope": "data:derived/replay", "expiry": "2026-08-11T00:00:00Z" },
  "receipt": "acr_5d2..."
}

The Operation is the durable, resumable unit for one agent intent. It survives the free boundary, the machine settlement, and provider callbacks without changing its ID or repeating completed work. The agent picks up exactly where it suspended, now authorized for the wider data pull.

Step 4: Continue the run

With the Envelope minted, the widened SIM session proceeds. The Kestrel the agent authored is unchanged; only the authority envelope around it grew. A generic, illustrative template; deploy this into YOUR pod and you arm it:

IMPORT { fade-ladder } FROM "./armory/reversion.kestrel"
USING signal SPX exec SPY 0dte

PLAN mean-revert-open budget 0.25R ttl +45m regime {intraday: range}
  WHEN spot < VWAP AND velocity(5m) <= p05
  DO buy 1 atm C @ min(fair, mid) peg cap fair
  TP 2x frac 0.5 @ fair
  EXIT spot > VWAP held 120s @ fair
  INVALIDATE spot < LOD

GRADE plan mean-revert-open OVER 2026-06-01..2026-06-30 FILL conservative
  VS null

Run it in SIM, earn a certified Blotter and a Grade, and you have new proof to show. A Grade is never flattering: Grades are contamination-fenced and counterfactual.

Where the wallet path stops (honest limits)

• Commerce-only. Wallet settlement covers data, sim, paper. It never buys broker or live authority. Those require a human signature: by design, regulatory-clean.
• No custody, ever. The platform holds no wallet key and takes no broker custody. host the scarcity rent the genius.
• Status. As of mid-2026: anonymous trial sims, certified Grades, shareable proof URLs, and 402 Offers with Stripe settlement are live; always-on paper presence and the human-signed live path are in build. The free tier needs no signup. Treat wire-level details above as illustrative of the shape, not a stable public API today.
• Not advice. Instruments here are generic and illustrative. This is not a strategy reveal and not investment advice.

Human vs. machine settlement, side by side

Be fair about the trade: for anything legally irreversible, the human path is not a fallback you route around; it is the correct and required path. The wallet exists to keep the agent moving through the reversible middle, not to bypass the signature the law wants.

The recipe in one breath

Read the Offer → check the scope is commerce-only → settle from the wallet with the Offer's nonce → verification mints the exact Envelope and resumes the same Operation. proof-before-account up front, certification over custody at settlement, and the agent is never in the hot path.

Citable one-liner: A 402 on kestrel.markets is not a paywall but a signed Offer bound to one Operation: a machine-verifiable wallet payment mints exactly the Envelope named and resumes the same Operation at its checkpoint, no human and no custody.