docs: add a read-only BlockRun research agent example with payment safeguards #490

Activity

1. github-actions

   added

   need-triage

   on Oct 10, 2026
2. feafel commented on Oct 15, 2026

   

   feafel

   on Oct 15, 2026

   More actions

   I would like to take this one — could you please assign it to me?

   Plan, pending your confirmation of scope:

   • Add a new runnable example under `examples/` (next to the existing X402 examples) implementing a read-only BlockRun research agent: tool surface limited to `web_search`/`web_fetch`-style reads, no shell, no wallet-signing paths other than the X402 payment client itself.
   • Payment safeguards spelled out in the example README and enforced in code: per-run spend cap, explicit `.price`/`.maxAmount` bounds on the payment request, idempotency key per run, and a hard refusal path when the server price exceeds the configured cap.
   • Verify the example runs against localnet per the repo contributing docs; keep it self-contained (no new workspace dependencies beyond what existing examples already use).

   If you would rather this live somewhere else (e.g. the app-work directory or a separate cookbook repo), happy to follow that direction instead.
3. osr21 commented on Oct 15, 2026

   

   osr21

   on Oct 15, 2026

   Author

   More actions

   Thanks—this looks like a good fit for a separate, read-only example. One useful boundary to make explicit: keep BlockRun catalog discovery in the example/client layer; arc-node should demonstrate the x402 payment/resource flow without embedding BlockRun catalog URLs or schemas. That keeps dynamic service discovery out of node responsibilities, and is consistent with the per-route metadata gap tracked in #436.

   For acceptance criteria, I suggest covering two safeguards from the issue that aren’t explicit in this plan:

   • Require approval for each paid call, bound to the resolved service, canonicalized inputs, network/token, and a maximum amount. Reject if the quote, schema, or inputs change after approval.
   • Enforce both the per-call limit and a durable UTC-day aggregate cap, with an atomic reservation so concurrent calls cannot exceed the budget. Persist and display the payment receipt/result.

   An idempotency key helps only if the payment service actually honors it. On timeout or an ambiguous payment outcome, reconcile by receipt/status and fail closed rather than blindly resending. A useful test would change the quote after discovery and verify that the old approval cannot authorize the new price.