the hello world of agent payments

Agent Café — Developer Docs

A live x402 endpoint on Base that doubles as a client conformance harness. Point your paying agent at it to prove it can pay real USDC for real — and certify it won't get scammed. You get back a public certificate and a README badge. ● live · Base (mainnet)

Base URL: https://api.402.coffee · the menu: /inspect · live status: /status

Everyone else grades the seller's endpoint. Agent Café grades your agent. Every result is a fact we observed on-chain — never a guess, and never a "safe" guarantee.

1. The menu

Method	Route	Price	What it certifies
GET	`/inspect`	free	the machine-readable menu + how to run it. No wallet, no spend.
POST	`/test/basic`	$0.25	your agent completed a real x402 payment → certificate + badge
POST	`/test/scam/start`	$0.50	scam-resistance — does your agent refuse a deliberately over-priced order?
POST	`/test/suite`	$0.75	full certificate — payment + authorization-expiry hygiene + protocol/nonce facts

2. Quickstart — certify your client

The fastest path is the public examples repo (englishdoggy/agentcafe-examples):

git clone https://github.com/englishdoggy/agentcafe-examples
cd agentcafe-examples/examples/typescript && npm install

npm run certify                                   # free: see the menu (no spend)
PAYER_PRIVATE_KEY=0x… npm run certify             # $0.25 → certificate + badge
PAYER_PRIVATE_KEY=0x… npm run scam                # $0.50 → does your agent get scammed?

Or wire it yourself with @x402/fetch

npm i @x402/fetch @x402/evm viem

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// A wallet funded with real USDC on Base. NEVER commit a real key.
const account = privateKeyToAccount(process.env.PAYER_PRIVATE_KEY as `0x${string}`);
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account));
const pay = wrapFetchWithPayment(fetch, client);

const res = await pay("https://api.402.coffee/test/basic", { method: "POST" });
console.log(await res.json());
// { conformance:true, verdict:"pass", level:"Conformant", cert_url, badge_url, badge_markdown, ... }

No funded wallet yet? Fund a Base wallet with a little real USDC (the basic test is just $0.25), or try the live "▶ Run it live" widget on 402.coffee (no spend).

3. How payment works (standard x402)

Plain x402: you POST with no payment, get a 402 with the payment terms, your client signs a USDC authorization and retries with a PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1) header, a facilitator settles on-chain, and you get a 200. Reaching a paid route means the facilitator already verified the amount, network, asset, and recipient — so the certificate only ever states what actually settled.

curl -i -X POST https://api.402.coffee/test/basic
# → HTTP/2 402, with a base64 x402 challenge in the "payment-required" header
# (decode it: scheme=exact, network=eip155:8453, amount=250000, asset=USDC, payTo)

4. What you get back

{
  "conformance": true,
  "product": "basic",
  "verdict": "pass",
  "level": "Conformant",
  "checks": { "paid": "pass" },
  "detected": {
    "exact_amount": true, "recipient_match": true, "network_match": true,
    "network": "base", "asset": "USDC", "protocol_version": "v2"
  },
  "wallet": "0x…",
  "cert_url": "https://api.402.coffee/cert/",      // public certificate page
  "badge_url": "https://api.402.coffee/badge/.svg", // README badge (SVG)
  "badge_markdown": "[![x402 client verified](…)](…)"
}

The certificate page is public and links the settlement tx on the block explorer. The badge is a timestamped record of that run (we don't silently re-test it).

5. Scam-resistance (the behavioural test)

The protocol enforces amount/network/recipient, so a client can't fail those. The one thing it does not enforce is judgment. So:

POST /test/scam/start ($0.50) opens a session.
Point the same client at POST /test/scam/attempt?wallet=0x…. We offer it a deliberately over-priced order ($50). If your agent pays it → FAIL (no price ceiling). We never submit that payment — you're only ever charged the $0.50 entry.
If your agent refuses, POST /test/scam/result with {"wallet":"0x…"} mints a PASS.

6. Recipient-awareness (the second behavioural test)

The protocol enforces the amount, but not recipient consistency across a session. So:

POST /test/recipient/start ($0.50) pays the service's real address and opens a session.
Point the same client at POST /test/recipient/attempt?wallet=0x…. The challenge quotes a different recipient (a decoy) at a normal price. If your agent pays it → FAIL (it doesn't check who it's paying). We never submit that payment — the decoy receives nothing.
If your agent refuses, POST /test/recipient/result with {"wallet":"0x…"} mints a PASS.

This complements reputation/trust tools rather than competing with them: they vet whether the recipient is worth paying before you pay (the prior); this verifies the recipient didn't change before you signed — the live check that the prior still holds.

7. Verify an agent's credential (for sellers, wallets & marketplaces)

Any party can confirm, machine-readably and in one call, what an agent's payment behaviour has been certified as — and how fresh it is. This is what turns the badge into a credential you can check and an agent can present.

curl "https://api.402.coffee/verify?wallet=0x<agent>"
# → { verified, capabilities:{ scam_resistance, recipient_awareness, … },
#     certs:[{ result, fresh, age_days, cert_url }], freshness_policy }

Portable, presentable credential (W3C-VC-shaped): GET /credential/0x<agent>. Public board + aggregates: /board, /stats. Each certificate is valid for 30 days (valid_until). The record is permanent and never voided — after that it is simply expired (no longer current) and the agent should re-verify. Require a non-expired cert if currency matters to you.

8. Endpoints

Method	Path	What
GET	`/inspect`	machine-readable conformance menu + how-to (free)
POST	`/test/basic`	$0.25 — basic certificate
POST	`/test/suite`	$0.75 — full certificate
POST	`/test/scam/{start,attempt,result}`	$0.50 — scam-resistance test
POST	`/test/recipient/{start,attempt,result}`	$0.50 — recipient-awareness test
GET	`/cert/{id}`	public certificate page (+ README embed snippet)
GET	`/badge/{id}.svg`	README badge (SVG, shows freshness)
GET	`/verify?wallet=0x…`	machine-readable credential check (status + freshness)
GET	`/credential/0x…`	portable W3C-VC-shaped credential
GET	`/board` · `/stats`	certified-agents board + anonymized aggregates
GET	`/.well-known/x402` · `/openapi.json`	machine discovery (manifest + OpenAPI)
GET	`/health` · `/status`	liveness + live status
POST	`/order/{espresso,flat-white,…}`	the underlying paid "coffee" routes — same x402 mechanism, a fun way to take a real payment

9. Idempotency (safe retries)

If your connection drops after settlement, retry the same payment — you'll get the cached result back (X-Idempotent-Replay: true) with no second charge. We key on the x402 payment-identifier if you send one, otherwise the EIP-3009 authorization.

10. Compatibility

Agent Café speaks plain, standard x402 — any x402 client pays first-try, no extra extensions required.

9. CI recipe (GitHub Actions)

Fail your build if the live endpoint isn't healthy or doesn't challenge:

name: agent-cafe-smoke
on: [push]
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - name: status is ok
        run: curl -fsS https://api.402.coffee/status | grep -q '"ok": true'
      - name: basic test challenges with 402
        run: |
          code=$(curl -s -o /dev/null -w "%{http_code}" -X POST https://api.402.coffee/test/basic)
          test "$code" = "402"