Add x402station action provider — pre-flight oracle for x402 endpoints

[sF1nX]

Summary

Adds a new x402station action provider — a wrapper around the public oracle at x402station.io that gives any AgentKit-built agent six tools for safely paying x402 endpoints:

Action	Cost	Purpose
preflight	$0.001	{ok, warnings[], metadata} for any URL — fast safety check
forensics	$0.001	7-day uptime + latency p50/p90/p99 + decoy probability + concentration
catalog_decoys	$0.005	Full known-bad blacklist as one cacheable JSON
watch_subscribe	$0.01	30-day webhook subscription + 100 prepaid HMAC-signed alerts on endpoint state changes
watch_status	free	Secret-gated read-back of an existing watch
watch_unsubscribe	free	Secret-gated soft-delete

Networks: Base mainnet (eip155:8453) and Base Sepolia (eip155:84532). Payments auto-signed through whatever EvmWalletProvider the agent is already configured with.

Why pre-flight?

The agentic.market catalog has 25,000+ x402 endpoints. A non-trivial fraction are honeypots or unreachable:

• Decoys priced ≥ $1,000 USDC per call. An agent that pays one drains its wallet on the first request.
• Zombies that 402-handshake fine but always 4xx after settlement (the call-side payment goes through, the agent gets nothing back).
• Dead endpoints that return network errors or 5xx every probe.

x402station independently probes every active catalog endpoint every ~10 minutes (not facilitator-reported) so it surfaces what facilitator-only monitors miss. Calling preflight before each paid x402 request costs $0.001 USDC — typically 20× cheaper than the request the agent would otherwise lose to a decoy.

A recent independent run on the entire catalog (blog post — methodology + raw JSONL) found 53% of endpoints at Cloudflare-isitagentready.com level 0 and 1.5% with x402 actually detected — so the "is this a real endpoint?" filter is doing real work.

Implementation

Mirrors the shape of the existing x402 action provider and reuses its EvmWalletProvider signer-wrapping pattern, so the four paid actions auto-sign x402 challenges through the agent's existing wallet without extra plumbing.

The baseUrl is allow-listed: only https://x402station.io (canonical) or any http(s)://localhost* (development) is accepted. Any other host throws at construction time so a misconfigured agent can't sign x402 payments against an unknown host.

Test coverage

pnpm test src/action-providers/x402station/ — 21/21 passing locally.

• constructor (6): default URL, localhost dev URL, trailing-slash handling, malformed URL rejection, non-canonical host rejection, port-bypass rejection (e.g. https://x402station.io:9999 is rejected even though .hostname matches).
• supportsNetwork (4): base-mainnet ✓, base-sepolia ✓, ethereum-mainnet ✗, non-EVM ✗.
• preflight (3): POST + URL bound correctly, paymentReceipt decoded from x-payment-response header, error envelope on non-2xx.
• forensics + catalog_decoys + watch_subscribe (4): correct paths, empty body for decoys, signals omitted-vs-included.
• watch_status (3): does NOT use the paying-fetch wrapper, parses 200 body, error envelope on 404.
• watch_unsubscribe (1): issues DELETE.

Manual end-to-end against the prod oracle ($0.018 USDC settled from a test wallet on Base mainnet) — 7/7 PASS via the consumer-side demo agent in the public repo.

Quick start

import {
  AgentKit,
  CdpEvmServerWalletProvider,
  x402stationActionProvider,
} from "@coinbase/agentkit";

const walletProvider = await CdpEvmServerWalletProvider.configureWithWallet({
  apiKeyId: process.env.CDP_API_KEY_ID!,
  apiKeySecret: process.env.CDP_API_KEY_SECRET!,
  walletSecret: process.env.CDP_WALLET_SECRET!,
  networkId: "base-mainnet",
});

const agentKit = await AgentKit.from({
  walletProvider,
  actionProviders: [x402stationActionProvider()],
});

The LLM can then call preflight, forensics, etc. via agentKit.getActions().

Existing alternatives

For agents that speak Model Context Protocol (Claude Code / Cursor / Windsurf / Continue), the same six tools are already available via the x402station-mcp npm package and the official MCP Registry. This PR is the AgentKit-native equivalent for the non-MCP path.

Test plan

• pnpm test src/action-providers/x402station/ — 21/21 passing
• pnpm check — 0 type errors in x402station/ files (15 pre-existing errors elsewhere — cdp/, opensea/, zora/ — are not from this PR)
• Manual end-to-end on Base mainnet via the demo agent in the public repo ($0.018 settled, 7/7 PASS)
• CI run against this PR

Links

• Service: https://x402station.io
• Manifest: https://x402station.io/.well-known/x402
• OpenAPI: https://x402station.io/api/openapi.json
• Agent skills (v0.2.0): https://x402station.io/.well-known/agent-skills
• API catalog (RFC 9727): https://x402station.io/.well-known/api-catalog
• Public client SDKs (this provider snapshot + MCP adapter + demo agent): https://github.com/sF1nX/x402station-mcp
• npm (MCP adapter): https://www.npmjs.com/package/x402station-mcp

The oracle backend (probe pipeline, signal logic, ingest, internal stats history) lives in a private repo — by design. This PR's source is fully visible in the diff above and snapshotted at https://github.com/sF1nX/x402station-mcp/tree/main/examples/agentkit-action-provider for browseability.

[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 1 Sum 2