API documentation

API keys (platforms). Create keys in the dashboard. Keys are shown once at creation and stored hashed. Revoke any key instantly from the dashboard. Requests without a valid key are rejected with 401 when key enforcement is on (RECOURSE_REQUIRE_KEYS=1; development mode is open).

Wallet identity & x402 — for agents, no account needed

An autonomous agent has no email and shouldn't need a human to sign up for it. On Recourse its wallet is its identity, its signature is its consent to the Rules, and it pays the case fee with the request. Nothing else is required.

1. Identity + consent. Sign an EIP-4361 Sign-In-With-Ethereum message with the wallet (Base, chain id 8453; fresh nonce; issued within the last 5 minutes; single use). Its statement must be the venue's consent text — fetch it from GET /x402/requirements:

   recourse.so wants you to sign in with your Ethereum account:
   0xYourAgentWallet…
   
   I agree that any dispute I submit is determined by Recourse under the Recourse Standard Rules v1.0 (https://recourse.so/rules/v1.0), final and binding as a matter of contract.
   
   URI: https://recourse.so/disputes
   Version: 1
   Chain ID: 8453
   Nonce: 6f1c9a2b3d4e5f60
   Issued At: 2026-09-04T09:00:00.000Z

   Send base64({ address, message, signature, chainId }) as the X-Sign-In-With-X header on every request. That signature is kept on the dispute record as the party's venue agreement.
2. Terms. POST /disputes with the header and no payment returns 402 Payment Required with an x402 body: accepts[0] gives the scheme (exact), network, asset (USDC), payTo, and maxAmountRequired — the case fee for the dispute's value tier, in USDC atomic units. Prices: GET /x402/requirements?amount_minor=….
3. Pay with the request. Sign an EIP-3009 TransferWithAuthorization for that amount to payTo, wrap it as an x402 payment payload, and retry with it base64-encoded in X-PAYMENT. The response carries X-PAYMENT-RESPONSE with the settlement (transaction hash, or sandbox: true when the venue has no facilitator configured — nothing moves, the record still issues). Alternatively keep a prepaid balance: POST /x402/top-up (same 402 dance, minimum $5) and GET /x402/balance/:address; fees are drawn from it automatically.
4. Don't hold the socket. Rulings take tens of seconds. Send Prefer: respond-async (or ?async=1) to get 202 { id, progress, result }; poll GET /disputes/:id/progress for the live milestones and fetch GET /disputes/:id when it reports done.

Both parties should have signed the underlying agreement by wallet (the demo's agreement object shows the shape); the respondent's consent to the venue is the clause in that agreement, the claimant's is the signature above. See it end to end at /agents/demo — the agent there is a real wallet doing exactly this against this API.

When a bundle trips an escalation trigger (published per rule-pack: low engine confidence, amount above ceiling, contradictory or uninspectable evidence, fraud allegations), the response comes back status: "escalated" with the engine's draft ruling attached, and the case enters the Recourse Review Bench — our internal queue, staffed by Recourse.

• Tier 2 (enhanced review): a Recourse reviewer examines the bundle with a deeper engine pass and confirms or overrides the draft.
• Tier 3 (human panel): independent adjudicators contracted by Recourse — never your staff, never ours with a conflict. Panelists are conflict-screened per case and excluded where any relationship with a party or the platform exists.

Your team is never asked to judge. Your only integration point is the escrow webhook: the draft instruction arrives flagged escalated: true (your escrow partner holds funds); the bench's final ruling follows as a superseding instruction with escalated: false.

Who executes what

Every executor honours escalated: true by holding, and every instruction is on the dispute record as rail_instruction. Recourse decides; it never custodies. Spec: integrations/escrow/WEBHOOK-SPEC.md.

recourse_escrow — the Recourse Protocol

For funds committed to a RecourseEscrow transaction. Submit the bundle with settlement: { rail: "recourse_escrow", chain_id, escrow, transaction_id, amount, token_decimals } after the transaction has been disputed on chain. The determination is signed by the venue's settlement key (EIP-712, domain RecourseEscrow/1 on the escrow) over (transactionId, payeeAmount, round, notBefore, recourseDisputeId) and returned on the record as rail_instruction; anyone submits it and the contract pays the split as ruled. An appeal is round 2 and supersedes an unexecuted round 1; appeal_window_hours becomes notBefore. Full guide: Recourse Protocol.

kleros_escrow — Kleros escrow, Recourse as arbitrator

For funds held in Kleros's EscrowUniversal (unmodified) with RecourseArbitrator named as its ERC-792 arbitrator. Submit the bundle with settlement: { rail: "kleros_escrow", chain_id, escrow, arbitrator, transaction_id, dispute_id } after the escrow has opened the dispute. The determination is signed by the venue's settlement key (EIP-712, domain RecourseArbitrator/1 on the arbitrator) and the signed instruction is returned on the record as rail_instruction:

{ "rail": "kleros_escrow", "dispute_id": "7", "ruling": 1,
  "mapping": "…the side the determination favours takes the escrowed amount…",
  "recourse_dispute_id": "dsp_…", "signature": "0x…",
  "execute": "RecourseArbitrator(0x…).executeSignedRuling(7, 1, keccak256("dsp_…"), signature)" }

Anyone may execute it — normally the winning agent — and the escrow pays out; Recourse never holds funds and pays no gas. Kleros rulings are binary (1 buyer/claimant refunded, 2 seller/respondent paid): the side the money instruction favours wins, and the full proportional determination stays on the record. Escalated determinations carry no signature — the escrow stays frozen until the bench finalises. Send the execution with an explicit gas limit (≈600k): the escrow swallows a failed token transfer rather than reverting, so gas estimation converges on a value at which the payout starves. Contracts, tests and deploy script: contracts/ in the repo. New integrations should prefer recourse_escrow, which executes the proportional split as ruled.

Judgment is rail-agnostic; enforcement is an adapter. The bundle's settlement field names the rail holding the disputed funds, and the ruling's webhook carries a rail-specific rail_instruction ready to execute. Recourse never holds funds, keys, or balances on any rail.

"Spec-stable" = payload formats are frozen and exercised end-to-end against the reference receiver; live execution activates with partner onboarding. Name Recourse as resolver in your escrow contract, Connect flow, or x402 payment terms once — every transaction inherits the venue.

One event type: ruling.money_instruction, HMAC-SHA256 signed, at-least-once delivery. Full spec with per-rail payloads and verification reference: integrations/escrow/WEBHOOK-SPEC.md in the integration kit.

POST {your registered endpoint}
recourse-timestamp: 1754460000
recourse-signature: hex(hmac_sha256(secret, timestamp + "." + body))

{ "type": "ruling.money_instruction", "dispute_id": "dsp_…", "escalated": false,
  "instruction": { "type": "split", "to_respondent_minor": 45000, "to_claimant_minor": 15000, "currency": "USD" },
  "rail_instruction": { "rail": "tempo", "network": "tempo-testnet", "transfer_intents": [
    { "to": "0xPROVIDER", "amount_minor": 45000, "asset": "USDC", "memo": "recourse:dsp_…" },
    { "to": "0xBUYER",    "amount_minor": 15000, "asset": "USDC", "memo": "recourse:dsp_…" } ] } }

Platforms (API key)

1. Free trial: every account starts with 25 free rulings, any tier, no card. The playground needs no account at all.
2. Then a card on file is required. Save one on the dashboard (Stripe; the card is held by Stripe, not by us). Until you do, requests answer 402 { code: "payment_method_required" } with a link to fix it.
3. Usage is charged monthly. Rulings meter at the rate card — $4.00 Tier 1 (automated), $20.00 Tier 2 (bench review; appeals meter here), $150.00 Tier 3 (human panel) — and the previous month's invoice is charged to the saved card on the 1st. No minimum, no commitment.
4. If a charge fails the invoice goes past due and requests answer 402 { code: "past_due" } until it is paid from the dashboard (saved card retry or Checkout). Nothing you already filed is affected.

Volume & enterprise: annual commitments with reserved capacity price Tier 1 at $1–2, add liability-backed rulings, DSA/ODS readiness and shadow-pilot onboarding, and are invoiced under contract — no card, never gated. Talk to us.

AI agents (wallet identity)

No account, no card. An agent pays the case fee with the request over x402 (USDC on Base), or keeps a prepaid balance topped up the same way; the fee is by dispute value (see GET /x402/requirements). With no payment and no balance the request answers 402 carrying the exact payment terms — nothing is filed and nothing is owed. Details: wallet identity & x402.

The platform or the filing agent pays; the other party never does; the fee is never a percentage of the disputed value. Disputes opened by people in the dispute room follow claimant pricing (free during the MVP).