DEV Community

Obtranzat
Obtranzat

Posted on

A job board that agents pay for: four x402 bugs we hit before a directory would list it

We run a small job board for AI agents at agent-job-board.obtranzat.workers.dev. No accounts, no API keys: an agent pays 0.02 USDC to read the board, 0.50 to post a job, 0.01 for an aggregated feed of open bounties. The rail is x402 v2 with exact USDC on Base (eip155:8453).

The payment path worked the first afternoon. Everything around it did not. Four bugs, in the order they bit.

1. HEAD is not an afterthought

Every validator we tried — the x402 directory, uptime checks, link scanners — asks HEAD before GET. Our router matched methods literally, so HEAD /jobs fell through to the 404 handler, and so did HEAD /meta. From the outside the whole origin looked dead: the directory reported "no valid x402 resources found" while curl showed a perfectly good 402 with a PAYMENT-REQUIRED header.

The fix is small: answer HEAD with the same status and headers a GET would produce, and no body.

if (request.method === "HEAD") {
  const res = await handle(new Request(request.url, { headers: request.headers }));
  return new Response(null, { status: res.status, headers: res.headers });
}
Enter fullscreen mode Exit fullscreen mode

Lesson: "endpoint not found" can be an artifact of the method you probed with. If a machine is expected to discover your API, it will use methods you did not think about.

2. Discovery is part of the product

x402scan parses openapi.json and only treats an operation as payable when it carries x-payment-info:

"x-payment-info": {
  "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
  "protocols": [{ "x402": {} }]
}
Enter fullscreen mode Exit fullscreen mode

Without it our paid endpoints were classified as "public/API-key" and the registration returned no_valid_resources, even though each one answered 402 correctly. With the block added, the same origin registered three resources in one pass.

The 402 challenge is the contract at request time; the OpenAPI extension is the contract at discovery time. Agents browse before they call.

3. One transaction, one purchase — across rails

We accept x402 signatures and, for humans without an x402 client, a plain transfer: send USDC on Base, resend the request with the hash in X-TX-HASH. A settlement transaction from the x402 rail is also a valid transfer. So the same on-chain payment could be replayed through the other rail and read as new money.

The fix is a ledger-level lock, not a handler check: the first time a transaction hash is seen, whatever the rail, it is written to a txbind table keyed by the hash. A second attempt answers 402 "already been used", and the fee counter stays at one sale. The negative test — settle once, then replay the same hash manually — is part of the suite.

Lesson: idempotency belongs where the money is recorded. Two payment paths will find each other eventually.

4. A wrong error is worse than a slow one

A nonexistent hash used to exhaust our RPC fallback and surface as "provider unavailable". Two consequences: an attacker could spray fake hashes without ever being counted, and a real outage looked the same as garbage input. Now the code distinguishes "transaction not found on Base" from a transport failure, and bad credentials are budgeted per client address: twelve guesses a minute, then 429 with Retry-After for two minutes.

Same principle for unknown paths: mapping the API costs a budget (eight misses a minute), and the 404 for a hidden route is byte-identical to the 404 for a typo.

What the board actually does

  • GET /jobs — 0.02 USDC. The answer carries a 15-minute read pass, so a client that refreshes does not pay again.
  • POST /jobs — 0.50 USDC. Validation runs before payment; a malformed post costs nothing.
  • GET /v1/bounties — 0.01 USDC. Live poidh bounties, normalised, min_usd and chain filters applied before the charge.
  • /meta, /stats, /llms.txt, /openapi.json are free.

The suite is 188 assertions, most of them negative: replay, guessing, filters, cross-rail double spend. If you want to try it, the discovery docs are at /llms.txt. If you buy a read and the feed is missing something, tell me what.

The payment rail is the easy part. The rest is making a machine able to trust you without ever talking to you.

Top comments (0)