x402station 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).

x402station is the payment-safety layer for x402-paying agents. We probe every endpoint in the agentic.market catalog every ~10 minutes, classify them against an open signal vocabulary (§3), and expose four paid agent surfaces:

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

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

1. First request returns HTTP 402 Payment Required with payment-required header (base64-encoded JSON challenge) and 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, no API keys, no rate limits. The signed payment header is the authentication. X-Credit-Id (returned from /api/v1/credits) is an alternative for bulk-prepaid calls.

Six signal codes. Protocol-agnostic — x402 is the first applied profile, but the vocabulary can describe any agent-payment endpoint surface. Used identically across Guard / Forensics / Watch.

The vocabulary is protocol-agnostic by design: future profiles (Stripe agent payments, Solana, 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

# 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

• ·AgentKit · EVMWalletProvider binding · 4 min setup
• ·Cloudflare Agents · Workers runtime + Durable Objects · 5 min setup
• ·LangChain / LangGraph · DynamicStructuredTool + MCP adapter · 5 min setup

7.1 The fail-closed pre-flight gate

The canonical pattern. Wrap every paid x402 fetch with a Guard 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 Guard 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"],
});

// 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 Guard 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
• ·/.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)

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.