feat: add x402 Doctor action provider with preflight_x402_endpoint

[Fizzl13]

Checks an x402 endpoint before the agent pays it, using the x402 Doctor preflight ($0.001 in USDC via x402 from the agent's wallet on Base or Solana mainnet, capped at $0.002 and only on the wallet's network). Returns go, caution or no_go with reasons, the recommended payment option and advice. Complements the x402 action provider between make_http_request and retry_http_request_with_x402.

Description

Tests

Checklist

A couple of things to include in your PR for completeness:

• Added documentation to all relevant README.md files
• Added a changelog entry

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[Fizzl13]

Description

Adds an x402Doctor action provider with one action, preflight_x402_endpoint, which lets an agent check an x402 endpoint before paying it.

It complements the existing x402 action provider: after make_http_request returns a 402 for an endpoint the agent has not used before, the agent calls preflight_x402_endpoint, and only on go continues with retry_http_request_with_x402 (on caution it asks the user, on no_go it does not pay).

The check is done by x402 Doctor's preflight endpoint (GET /api/v1/preflight, listed in the CDP Bazaar). It reads the endpoint's payment requirements and checks the price against the budget and against what the service advertises, whether the option is payable on the wallet's network (USDC, a valid payout address, a Solana payout account that exists), HTTPS, the endpoint's payability track record and whether it is listed in the CDP Bazaar.

• Costs $0.001 in USDC, paid via x402 from the agent's wallet (Base mainnet or Solana mainnet), using the same @x402/fetch + registerExactEvmScheme / registerExactSvmScheme setup as the x402 provider.
• Safety: an x402 client policy only allows paying on the wallet's own network and never more than $0.002 for the preflight.
• No API key; optional doctorUrl config (or X402_DOCTOR_URL).
• Returns JSON with verdict, summary, advice, recommendedOption, reasons, signals and the paymentProof. A failed preflight returns an error ("do not pay without a verdict").

Disclosure: I maintain x402 Doctor.

Tests

Unit: 9 tests in x402DoctorActionProvider.test.ts (verdict handling, query parameters, spend-cap policy, unsupported network and wallet, failed preflight, custom URL). jest src/action-providers/x402Doctor, tsc --noEmit, eslint and prettier pass.

Live, on Base mainnet: AgentKit built from this branch, ViemWalletProvider with a funded test wallet, x402ActionProvider() + x402DoctorActionProvider(), action invoked through agentkit.getActions():

Network: {"protocolFamily":"evm","chainId":"8453","networkId":"base-mainnet"}
Action: X402DoctorActionProvider_preflight_x402_endpoint

Input: {"url":"https://ichimoku-signal.onrender.com/signal/BTC-USDT","maxUsd":0.05}
{ "success": true, "verdict": "go", "summary": "OK to pay: $0.02 on Base.",
  "advice": "Safe to pay: continue with retry_http_request_with_x402 using the recommended option.",
  "recommendedOption": { "network": "eip155:8453", "asset_symbol": "USDC", "amount": "20000", "usd": 0.02, "payable": true, ... },
  "paymentProof": { "success": true, "transaction": "0xea4458e2d0cdb2c4aafb64d88268b94f9da4ab114a4866a61d753b380a1f1273", "network": "eip155:8453" } }

Input: {"url":"https://ichimoku-signal.onrender.com/signal/BTC-USDT","maxUsd":0.01}
{ "success": true, "verdict": "no_go",
  "summary": "Do not pay: The cheapest payable option costs $0.02, above your max_usd of $0.01.",
  "advice": "Do not pay this endpoint: the payment would fail, is over budget, or should not be made.",
  "reasons": [{ "level": "no_go", "code": "over_budget", ... }],
  "paymentProof": { "success": true, "transaction": "0x1cf94a8b017dcd4b2f8fefab28804361d147491040d12499bc121822bb5a213c", "network": "eip155:8453" } }

Checklist

• Added documentation to all relevant README.md files (new x402Doctor/README.md; happy to add the entry to the main action list in typescript/agentkit/README.md too)
• Added a changelog entry