x402station.io specification

Three lines, in order. If your agent only reads §0, it should still be safe.

// before signing PAYMENT-SIGNATURE for any unfamiliar x402 URL:
const verdict = await fetch("https://x402station.io/api/v1/preflight", {
  method: "POST",
  headers: { "content-type": "application/json", /* x402 PAYMENT-SIGNATURE */ },
  body: JSON.stringify({ url: targetUrl }),
}).then(r => r.json()); // { ok, warnings, metadata }

if (!verdict.ok) {
  // do not pay. consult /api/v1/alternatives for a healthy peer.
  return abort();
}

Cost: $0.001 USDC per pre-flight. Settled via x402 itself. Bulk credits available at $0.0005/call (/guard).

First-call self-test: POST /api/v1/preflight-trial accepts the same {url} body without PAYMENT-SIGNATURE. It is rate-limited to 10 calls per IP per UTC day, one URL per call, and cached for 5 minutes. Production agents should use paid Preflight for fresh data, batch support, and SLA.

Independent risk-signal layer for x402 agentic commerce — endpoint evidence (decoy / zombie / price-trap / never-paid) before an agent authorizes payment. x402station.io continuously probes x402 endpoints and returns evidence so an AI agent, wallet, or policy engine can decide before authorizing USDC payment. We probe every endpoint in the agentic.market catalog every ~10 minutes, classify results against an open signal vocabulary (§3), and expose live paid agent surfaces:

All four surfaces share the same signal vocabulary. The provider that pays for Verified cannot pay to remove a Preflight signal — different paths, different gates.

Every paid endpoint follows the canonical x402 v2 challenge-response:

1. First request returns HTTP 402 Payment Required with the x402 v2 challenge in both places: JSON response body for body-first clients, and payment-required header (base64-encoded mirror) for header-first clients. It also includes www-authenticate: x402.
2. Client signs the challenge per x402 spec, retries with PAYMENT-SIGNATURE header.
3. Facilitator (x402.org/facilitator) settles the USDC transfer on Base mainnet (or Base Sepolia for testnet). Server returns HTTP 200 with the response body.

No accounts and no API keys. The signed payment header is the authentication. X-Credit-Id (returned from /api/v1/credits) is an alternative for bulk-prepaid calls.

The only unauthenticated evaluation surface is /api/v1/preflight-trial: free trial for agent self-test, rate-limited and 5-minute cached. It returns the same Preflight verdict shape so client code can switch to /api/v1/preflight without changing its parser.

Core signal codes plus x402station operational extensions. Protocol-agnostic — x402 is the first applied profile, but the vocabulary can describe any agent-payment endpoint surface. Used across Preflight / Forensics / Watch where the underlying evidence is available.

The vocabulary is protocol-agnostic by design: future profiles (Stripe agent payments, AP2, generic HTTP 402) reuse the same codes. Each profile maps codes to its own evidence shape.

Iron rule: a provider can pay for an audit, but cannot pay to remove a risk signal. Signal classification is 100% probe-data-driven.

6.1 npm middleware (recommended)

npm install x402station-middleware @x402/fetch @x402/evm viem

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { wrapWithPreflight } from "x402station-middleware";

const x402Fetch = wrapFetchWithPaymentFromConfig(fetch, { schemes: [...] });
const safeFetch = wrapWithPreflight(x402Fetch);

// fail-closed: throws PreflightBlockedError on any critical signal
await safeFetch("https://api.example.com/x402-endpoint", {
  method: "POST",
  body: JSON.stringify({ /* ... */ }),
});

6.2 MCP server (Claude Code / Cursor / Windsurf / Continue)

npx -y x402station-mcp

Exposes ten tools to the host: preflight, forensics, alternatives, catalog_decoys, whats_new, buy_credits, watch_subscribe, plus free credits_status / watch_status / watch_unsubscribe. Auto-signs PAYMENT-SIGNATURE via AGENT_PRIVATE_KEY (Base mainnet wallet).

MCP Registry: io.github.sF1nX/x402station

6.3 Raw API (any HTTP client)

# 1. cold call returns 402 with payment requirements
curl -i -X POST https://x402station.io/api/v1/preflight \
  -H "content-type: application/json" \
  -d '{"url":"https://api.example.com/x402-endpoint"}'
→ HTTP/1.1 402 Payment Required
   payment-required: <base64 challenge>
   www-authenticate: x402
   content-type: application/json; charset=utf-8

{
  "x402Version": 2,
  "resource": { "url": "https://x402station.io/api/v1/preflight" },
  "accepts": [{ "scheme": "exact", "network": "eip155:8453", "...": "..." }]
}

# 2. retry with signed PAYMENT-SIGNATURE header
curl -i -X POST https://x402station.io/api/v1/preflight \
  -H "content-type: application/json" \
  -H "PAYMENT-SIGNATURE: <signed challenge>" \
  -d '{"url":"https://api.example.com/x402-endpoint"}'
→ HTTP/1.1 200 OK
   { "ok": true, "warnings": [], "metadata": {...} }

6.4 Framework templates

Explicitly supported agent surfaces: LangChain, Mastra, Vercel AI SDK, Coinbase AgentKit, Lucid, LangChain JS, and MCP-compatible clients. Use /mcp for MCP host configuration and /api/openapi.json for generated HTTP clients.

• ·AgentKit · EVMWalletProvider binding · 4 min setup
• ·Cloudflare Agents · Workers runtime + Durable Objects · 5 min setup
• ·LangChain / LangGraph · DynamicStructuredTool + MCP adapter · 5 min setup
• ·Mastra · wrap the action execution boundary with x402station-middleware or spawn the MCP adapter from /mcp
• ·LangChain JS · use the same DynamicStructuredTool boundary as LangChain, or run through any MCP-compatible host.
• ·MCP-compatible clients · install x402station-mcp and expose preflight / forensics / alternatives as tools.
• ·Lucid / Daydreams · guarded action boundary · 5 min setup
• ·Vercel AI SDK · tool execute boundary · 5 min setup

7.1 The fail-closed pre-flight gate

The canonical pattern. Wrap every paid x402 fetch with a Preflight call. On any critical warning, abort.

async function paidFetch(url, init) {
  const verdict = await stationFetch.preflight(url);
  if (!verdict.ok) {
    throw new PreflightBlockedError(verdict.warnings, verdict.metadata);
  }
  return await x402Fetch(url, init);
}

7.2 Routing fallback

When pre-flight blocks a payment, ask /alternatives for a healthy peer in the same task class. Only one extra paid call.

async function paidFetchWithFallback(url, taskClass) {
  const verdict = await stationFetch.preflight(url);
  if (!verdict.ok) {
    const { alternatives } = await stationFetch.alternatives({
      flaggedUrl: url,
      taskClass,
    });
    if (alternatives.length === 0) throw new NoAlternativesError(verdict);
    return paidFetchWithFallback(alternatives[0].url, taskClass); // recurse
  }
  return await x402Fetch(url, /* ... */);
}

7.3 Long-running policy mode

For agents running >1 hour, subscribe a Watch on each integrated URL. The agent doesn't poll pre-flight; it only consults Preflight if the local cache says the URL is dirty (received Watch alert).

// at integration time:
await stationFetch.watchSubscribe({
  url: "https://api.example.com/x402-endpoint",
  webhook: "https://your-agent.example/x402-alerts",
  signals: ["dead", "zombie", "decoy_price_extreme", "high_concentration", "wildcard_402", "spa_fallback"],
});

// in your webhook handler:
app.post("/x402-alerts", (req) => {
  const { url, signal } = req.body;
  agentDirtyCache.add(url, signal);
});

// in the paid path:
async function paidFetch(url, init) {
  if (agentDirtyCache.isDirty(url)) {
    const verdict = await stationFetch.preflight(url);
    if (!verdict.ok) throw new PreflightBlockedError(verdict.warnings);
  }
  return await x402Fetch(url, init);
}

7.4 Bulk pre-flight via credits

For agents making many paid calls per minute, buy 1,000 prepaid credits at $0.50 (50% off per-call rate).

const { creditId } = await stationFetch.buyCredits();
// pass credit id on every call; auto-fallthrough to per-call when balance hits 0
const verdict = await stationFetch.preflight(url, { creditId });

All prices in USDC on Base mainnet (eip155:8453). Settled via x402.org/facilitator.

• ·No per-IP / per-account rate limit for paid endpoints — payment is the throttle.
• ·Pre-flight statement timeout: 5 s. On timeout, server returns 503; agent should treat as ok: false.
• ·Free endpoints (credits/status, watch/status) are softly rate-limited at 60 rpm per IP.
• ·Webhook delivery for Watch retries 5× with exponential backoff (1s / 2s / 4s / 8s / 16s) before burning a quota credit and giving up.

Properties guaranteed by the implementation. Agents may rely on these.

1. Signal independence. A provider that pays for Verified status cannot pay to remove a Preflight warning. The two code paths are orthogonal.
2. Probe transparency. Every signal fires from raw probe data; the evidence shape is public in §3 and the source SQL is open in the public mirror.
3. Settlement idempotency. Each endpoint accepts the same payment_tx at most once. Retries with the same signed payment return the prior response, never double-charge.
4. Catalog identity. An endpoint is identified by canonical URL (lowercased host, no trailing slash, query params normalised). The same URL always maps to the same endpoint_id.
5. Time monotonicity. All timestamps are UTC ISO 8601 from a single Postgres clock. No client timestamps cross the API boundary.

For AI scrapers / agent runtimes that prefer structured ingestion over this HTML page:

• ·/llms.txt — short AI-scraper summary (RFC for llms.txt standard)
• ·/api/openapi.json — OpenAPI 3.1 spec covering every paid + free endpoint
• ·x402station.io Preflight Dataset v0.1 — CC-BY-4.0 weekly aggregate probe snapshot; raw probe time-series stays gated
• ·/.well-known/x402 — x402 protocol manifest (resource list, payment contracts, networks)
• ·/.well-known/agent-card.json — Agent Card spec
• ·/.well-known/mcp/server-card.json — MCP server card
• ·/skill.md — agent skill definition (single-file ingestible)
• ·/mcp — HTML install guide for the x402station MCP adapter

12.1 Minimal Bun agent

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { wrapWithPreflight } from "x402station-middleware";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY!);
const x402Fetch = wrapFetchWithPaymentFromConfig(fetch, {
  account,
  facilitator: "https://x402.org/facilitator",
});
const safeFetch = wrapWithPreflight(x402Fetch);

const res = await safeFetch("https://api.exa.ai/search", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "x402 agent payments" }),
});
console.log(await res.json());

12.2 Cloudflare Workers

export default {
  async fetch(request, env) {
    const account = privateKeyToAccount(env.AGENT_PRIVATE_KEY);
    const x402Fetch = wrapFetchWithPaymentFromConfig(fetch, { account });
    const safeFetch = wrapWithPreflight(x402Fetch);
    try {
      const r = await safeFetch(targetUrl, { method: "POST", body });
      return r;
    } catch (e) {
      if (e instanceof PreflightBlockedError) {
        return new Response(JSON.stringify({ blocked: e.warnings }), { status: 422 });
      }
      throw e;
    }
  }
}

12.3 LangChain DynamicStructuredTool

const safePayTool = new DynamicStructuredTool({
  name: "safe_x402_pay",
  description: "Pay an x402 endpoint after pre-flight check. Use for any paid HTTP call.",
  schema: z.object({ url: z.string().url(), body: z.unknown() }),
  func: async ({ url, body }) => {
    const r = await safeFetch(url, { method: "POST", body: JSON.stringify(body) });
    return await r.text();
  },
});

Bugs, feature requests, edge cases, ideas: hello@x402station.io. Operator input shapes the roadmap directly.

Changelog and 60-day data: /blog. Source mirrors: x402station-mcp · x402station-middleware.

This specification covers v1 (stable). v2 will add a protocol-agnosticx402-signals open-spec repository; the signal vocabulary in §3 is the v2 candidate.