x402 Cloud: a handler that does not return a Response fails as a blank HTTP 500 with no diagnostic (and the quick-start shows that pattern)

[groundtruth-now]

Summary

A correctly-signed exact / eip155:8453 USDC payment to an x402 Cloud endpoint returns
HTTP 500 with a completely empty body and no x-x402-paid header. The unpaid and
malformed-payment paths on the same endpoint behave correctly, and the failure reproduces
against a trivial handler that only returns a static object — so it is not handler code.

Bankr's own accounting shows 0 reqs / $0 earned after six paid attempts, so the failure
appears to happen before request accounting and before settlement. Nothing is charged.

Environment

• @bankr/cli latest (via npx), Node v24.18.0, Windows
• Endpoints deployed with bankr x402 deploy, network: base, currency: USDC,
  paymentScheme: exact, price 0.01
• Payer: an independent client signing EIP-3009 transferWithAuthorization, holding zero
  native gas (the normal x402 arrangement). The same client settles successfully against
  other x402 resources.

What works

# no payment header
$ curl -s -o /dev/null -w '%{http_code}\n' -H 'accept: application/json' "$URL"
402

# malformed payment header (either name -- both are read)
$ curl -s -w '%{http_code}\n' -H 'X-PAYMENT: bm90LWEtcGF5bWVudA==' "$URL"
400 {"error":"Invalid payment signature encoding"}

$ curl -s -w '%{http_code}\n' -H 'PAYMENT-SIGNATURE: bm90LWEtcGF5bWVudA==' "$URL"
400 {"error":"Invalid payment signature encoding"}

The 402 challenge itself is well-formed:

{
  "x402Version": 2,
  "error": "Payment Required",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "10000",
    "amount": "10000",
    "resource": "https://x402.bankr.bot/<wallet>/<service>",
    "payTo": "0x8AEE621035D93Deb3C0C1177fac252dC2dd501a0",
    "maxTimeoutSeconds": 60,
    "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "extra": { "name": "USD Coin", "version": "2" }
  }],
  "facilitator": "https://api.bankr.bot/facilitator"
}

What fails

Replaying with a valid signed payload built from that exact challenge:

paid request: HTTP 500
  x-x402-paid       : null
  payment-response  : (none)

body:
<empty>

The body is zero bytes — there is no error string to act on.

Minimal reproduction: a trivial handler 500s identically

To rule out our own handler, I deployed a service whose handler does nothing but return a
static object:

export default async function handler(req: Request) {
  const url = new URL(req.url);
  return {
    ok: true,
    echo: url.searchParams.get("q") ?? null,
    has_process: typeof process !== "undefined",
    has_fetch: typeof fetch !== "undefined",
    timestamp: new Date().toISOString(),
  };
}

bankr.x402.json for it:

{
  "description": "reachability probe",
  "price": "0.000001",
  "methods": ["GET"],
  "category": "data",
  "paymentScheme": "exact"
}

A signed payment to that endpoint returns the same HTTP 500 with an empty body.
Wrapping the entire handler body in a top-level try/catch that returns the error does not
change the response either, which suggests the fault is at module load or at invocation,
upstream of handler code.

Evidence table

request	result
no payment header	402, well-formed challenge
malformed X-PAYMENT	400 Invalid payment signature encoding
malformed PAYMENT-SIGNATURE	400 Invalid payment signature encoding
correctly signed payment	500, empty body, no x-x402-paid
same, against the trivial handler above	500, empty body — identical
bankr x402 list after 6 paid attempts	0 reqs $0 earned

Notes

• Reproduced six times over roughly eight hours, across two service versions (v1 and v2)
  and three separate services on the same account, so it is not transient.
• Initially I suspected the API key lacking Wallet API scope, since bankr x402 call
  returned API error (403): This API key does not have Wallet API access enabled.
  Enabling that scope fixed the 403 — bankr x402 call now proceeds to payment — but the
  500 to an independently-funded client is unchanged, so the scope is ruled out as the
  cause.
• Possibly related to x402 Cloud: exact BNKR + Permit2 402 then Payment verification failed (USDC canary not involved) #4, but distinct: that one is BNKR + Permit2 returning HTTP 400
  "Payment verification failed". This is canonical Base USDC returning HTTP 500 with no
  body at all.

Happy to leave the probe endpoint deployed for inspection, or to run any diagnostic call
that would help narrow it.

[groundtruth-now]

Root cause found, and it was ours — with one part that I think is still worth fixing on your side.

What it was

Handlers run on Bun and the wrapper requires a web-standard Response. Our handlers
returned plain objects. That throws inside the wrapper and surfaces to the payer as
HTTP 500 with a zero-byte body.

Changing every return path to Response.json(body) — and errors to
Response.json({ error }, { status }) — fixed all three services immediately:

ping           v2  paid -> HTTP 200  {"ok":true,...,"returns":"Response.json"}
creator-record v3  paid -> HTTP 200  (full record payload)
coin-record    v3  paid -> HTTP 200  (full record payload)

bankr x402 list now shows 1 reqs / $0.01 earned on each, where six previous paid
attempts had produced 0 reqs / $0 earned. So settlement and accounting were never
broken — the handler simply never produced a response.

What I think is still yours

1. A handler return-type error produces a blank 500 with no diagnostic anywhere.
Not in the response body, not in bankr x402 call, and there is no logs subcommand in
the CLI. From the payer's side an unhandled throw in the wrapper is indistinguishable
from a dead endpoint, a bad deploy, or a facilitator problem — which is why this took six
paid attempts and a deliberately trivial handler to isolate. Even a bare
{"error":"handler did not return a Response"} would have made it a one-minute fix.

2. The quick-start documents the pattern that fails. x402-cloud/quick-start
shows:

export default async function handler(req: Request) {
  ...
  return {
    city,
    temperature: weather.temp,
    conditions: weather.conditions,
    timestamp: new Date().toISOString(),
  };
}

and states "Handler receives a Request object and returns JSON-serializable data. No
x402 imports, no payment middleware, no blockchain code." I followed that literally. If
the runtime requires a Response, the quick-start and the bankr x402 add scaffold
should show Response.json(...).

Suggested disposition

I've retitled this to the part that is actually yours — the silent failure mode. Happy
for it to be closed instead if the docs are the only thing you want to change; the probe
endpoint can stay deployed if it is useful for reproducing the blank 500.

Also worth noting for anyone who lands here from a search: this is not the same as #4.
That one is BNKR + Permit2 returning HTTP 400 "Payment verification failed", a genuine
settlement failure. This was canonical Base USDC where settlement worked fine and the
handler was the problem.