A signed, single-use, TTL-bounded authorization that binds an agent's intent to an exact beneficiary, rail, amount, and policy.

A Spend Capsule is a JWS (Ed25519) wrapping a canonical JSON payload. It's what an agent presents to Meow via the gateway, without a valid capsule the call is denied before a single upstream byte flies.

Shape

{
  "version": "veto.capsule/1",
  "capsule_id": "cap_01hy2z...",
  "issuer": "meow-gateway:self-host",
  "entity_id": "ent_acme_llc",
  "agent_id": "agent_finance_bot",
  "tool": "meow.pay",
  "rail_allowlist": ["ach", "wire"],
  "counterparty_hash": "sha256:7ee7f2426cda71548a0fae87c291ff42469358bcb65ff2a0ffaf763d15bae5f4",
  "amount_ceiling": { "currency": "USD", "amount": "5000.00" },
  "invoice_hash": "sha256:9f2...",
  "workflow_id": "wf_01hy2z...",
  "policy_sha256": "ac3f...",
  "issued_at": "2026-04-21T14:03:00Z",
  "expires_at": "2026-04-21T14:18:00Z",
  "nonce": "8b2d4e...",
  "max_uses": 1
}

Drift axes

Every field in the payload is a drift anchor. At consume time the gateway verifies the runtime request matches the signed payload byte-for-byte on all axes:

Axis	Check
`tool`	Exact string match (e.g. `meow.pay` signed → cannot consume as `meow.card.create`)
`counterparty_hash`	Recomputed from runtime beneficiary; must equal signed
`rail`	Must be in `rail_allowlist`; runtime pick is recorded in the receipt
`amount`	Runtime ≤ `amount_ceiling`; currency exact match
`invoice_hash`	Runtime ≥ signed (bind-once, consume-once)
`expires_at`	`now < expires_at` with a ±30s skew tolerance
`nonce`	Unique per `(organization, entity)`; replay = deny

Miss any axis → deny + chain a deny receipt with the specific mismatch code.

Why Ed25519 + JCS

Ed25519, 32-byte pubkey, 64-byte sig, deterministic (no nonce reuse foot-guns), widely-implemented in every target language. The @veto/spend-capsule-protocol package exposes matching signCapsule / verifyCapsule helpers in TS and Python so cross-language auditors read the same JWS.

JCS (RFC 8785), canonical JSON serialization. Two verifiers on two runtimes will serialize the same payload to the same bytes, so the hash is stable. JCS handles key sorting, number normalization, and UTF-8 encoding.

Lifetime

Mint (POST /v1/capsules), gateway validates inputs against the active policy pack, reserves a budget lease, claims any required HITL approval, signs the payload, writes a receipt.
Consume (POST /meow/consume or /meow/mcp), gateway verifies signature + all drift axes, atomically marks the capsule consumed, chains a decision receipt, forwards to Meow.
Settle (webhook from Meow), gateway transitions the workflow to settled / failed.

A capsule is single-use. Multi-use was considered and removed, the consume path cannot atomically decrement a counter while also enforcing nonce replay. Re-minting is cheap; re-using is forbidden.

Idempotency

Pass an Idempotency-Key header on mint. Retries with the same key AND the same canonical request body return the exact original JWS. A retry with the same key but a different body returns 400 idempotency_key_reused_with_different_payload, prevents a "retry" from silently authorizing a different payment.

Where to go next

Decision Receipt, the audit output of consume
Policy Pack, YAML rules evaluated at mint
Protocol reference, full JSON schema + golden vectors

Spend Capsule