KeeperHub / KeeperHub/keeperhub
Add x402 paid-data action: fetch HTTP resources that require x402 payment
- Dominant language
- TypeScript
- Stars
- 24
- Forks
- 93
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 266
Description
## Reason
Keeper workflows cannot consume pay-per-call x402 APIs (the machine-economy standard where a server answers 402 with payment requirements, the client pays a few cents in USDC, and retries with an X-PAYMENT signature). KeeperHub itself sells workflow calls over x402 (`lib/payments/x402/`), but no workflow action can *buy* from an x402 endpoint.
Today the Webhook action hits a paid endpoint, gets 402, and surfaces an opaque `HTTP 402: ...` error. The workaround is hand-rolling fetch-then-402 logic in Code steps per workflow: no shared SSRF guard, no spend-cap discipline, duplicated everywhere. Evidence: `plugins/webhook/steps/send-webhook.ts` returns `HTTP ${status}` for any non-OK status with no 402 awareness.
Checked on staging @ `f8c8f18c7`; no x402 buyer exists in `plugins/` or `lib/` (only the seller-side gate).
## Scope
- New `x402` plugin with ONE action, `fetch-paid-resource`: GET/POST a URL via `safeFetch` + `assertUrlIsPublic` (same SSRF posture as webhook), parse x402 v1/v2 402 payment requirements, enforce a user-configured `maxPriceUsdc` spend cap, and retry with a caller-supplied `X-PAYMENT` value to return the paid data.
- Signing stays where it belongs: the signature comes from a template variable (agentic-wallet sign entrypoint / Code step), never from keys held by this node. No new key custody, no bypass of the A-06 fund-moving guard in `sign-typed-data`.
- Egress `user-destination` (plan-gated like webhook via the catch-all), unit tests in `tests/unit/`.
- NOT in scope: embedded wallet signing, new triggers, facilitator verify/settle (that is the resource server's job), protocol changes.
## Plan
Implement the plugin (`index.ts`, `icon.tsx`, `credentials.ts`, `test.ts`, `steps/fetch-paid-resource.ts`), register in `plugins/plugin-allowlist.json`, run `pnpm discover-plugins`, add unit tests, verify with `pnpm type-check`, `pnpm check`, and `pnpm test:unit`, then open a PR against `staging`.
Contributor guide
Research direction
Start with plugins/webhook/steps/send-webhook.ts and the seller-side code under lib/payments/x402/ to understand existing HTTP and x402 behavior. Implement the listed files for the new plugin, register it in plugins/plugin-allowlist.json, and add unit tests in tests/unit/. Done means the discovery, type-check, checks, and unit-test commands pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend, payments, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 56/100