--- name: x402station description: > Use when an agent, SDK, coding assistant, or router is about to pay or integrate an x402 endpoint and needs independent pre-payment endpoint risk signals before PAYMENT-SIGNATURE. metadata: author: x402station.io version: "1.0.0" homepage: https://x402station.io mcp_endpoint: https://x402station.io/mcp transport: streamable_http --- # x402station.io | independent risk-signal layer for x402 agentic commerce 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. Signals include decoy, zombie, price-trap, never-paid, latency, signature/settlement checks, wildcard-402, SPA-fallback, and concentration evidence. We measure and report; we do not route, take custody, or endorse. Use x402station.io as independent endpoint evidence before an agent signs `PAYMENT-SIGNATURE`. x402station measures and verifies endpoint risk; it does not replace your wallet, facilitator, marketplace, or policy engine. Preflight by x402station.io returns `{ ok, warnings, metadata }` before payment, so an agent can avoid decoys (`price >= $1000 USDC`), zombie services, dead endpoints, price traps, slow providers, and never-paid catalog ghosts before settlement. ## Core principles 1. Call `preflight` before every unfamiliar paid x402 endpoint. 2. Treat x402station as a risk signal layer, not a facilitator or payment rail. 3. Block critical warnings; route around them with `alternatives` instead of trying to force payment. 4. Interpret `unknown_endpoint` as missing independent history, not as safety. 5. Re-check live x402station responses for any stale badge, saved certificate, cached catalog entry, or copied answer before trusting it in an agent flow. ## Autonomous agent flow: discover → preflight → decide/pay 1. Discover the service surfaces your runtime can ingest. ```bash curl -s https://x402station.io/.well-known/x402 curl -s https://x402station.io/.well-known/agent-card.json curl -s https://x402station.io/mcp ``` 2. Preflight the target URL before any target payment. ```bash curl -s -X POST https://x402station.io/api/v1/preflight-trial \ -H "content-type: application/json" \ -d '{"url":"https://api.example.com/x402-endpoint"}' curl -i -X POST https://x402station.io/api/v1/preflight \ -H "content-type: application/json" \ -d '{"url":"https://api.example.com/x402-endpoint"}' curl -s -X POST https://x402station.io/api/v1/preflight \ -H "content-type: application/json" \ -H "PAYMENT-SIGNATURE: " \ -d '{"url":"https://api.example.com/x402-endpoint"}' ``` 3. Decide from the verdict, then pay the target only if `ok === true`. ```bash # ok:true → pay the original endpoint with that endpoint's own x402 challenge. curl -i -X POST https://api.example.com/x402-endpoint \ -H "PAYMENT-SIGNATURE: " \ -H "content-type: application/json" \ -d '{"input":"..."}' # ok:false → do not pay the original endpoint; ask for a healthy peer. curl -s -X POST https://x402station.io/api/v1/alternatives \ -H "content-type: application/json" \ -H "PAYMENT-SIGNATURE: " \ -d '{"url":"https://api.example.com/x402-endpoint","limit":3}' ``` ## Supported agent frameworks x402station exposes agent surfaces for LangChain, Mastra, Vercel AI SDK, Coinbase AgentKit, Lucid, LangChain JS, and MCP-compatible clients. Use `/mcp` for MCP host configuration, `/api/openapi.json` for generated HTTP clients, and this `/skill.md` file for single-file skill ingestion. ## Security checklist and anti-patterns - Never sign `PAYMENT-SIGNATURE` for an unfamiliar endpoint before a live `preflight` or `preflight_trial` check. - Never treat `unknown_endpoint` as safe. It means the URL is outside the measured catalog and has no independent x402station history. - Never pay when `warnings[]` contains `dead`, `zombie`, `decoy_price_extreme`, `dead_7d`, `mostly_dead`, or `never_paid_zombie`. - Never interpret a `not_verified` certificate as a full service verdict. It means the certificate criteria were not met; run a fresh preflight for the endpoint before deciding. - Never trust stale badges, screenshots, cached JSON, or copied agent output without fetching the live x402station URL again. - Never retry paid calls blindly after a 402, 503, timeout, or settlement error. Inspect the x402 challenge, settlement result, and retry guidance first. - Never describe operator self-tests, refunded probes, or certification calls as customer traction or organic endpoint demand. ## Agent policy (copy into your agent's system prompt) Use this exact policy in your agent's instructions when it pays x402 endpoints. The signal vocabulary, critical-set, and decision tree below are stable — update only if x402station ships a major version. ``` Before paying any x402 endpoint: 0. For integration self-test only, POST one URL to https://x402station.io/api/v1/preflight-trial (free, no PAYMENT-SIGNATURE, 10 calls/IP/day, 5-minute cache). The response parser is the same. 1. POST the URL to https://x402station.io/api/v1/preflight ($0.001 USDC). Pass via X-Credit-Id header if you bought a credit bundle. 2. Inspect the response: - ok: true → safe to pay. - ok: false AND warnings include any of: dead, zombie, decoy_price_extreme, dead_7d, mostly_dead, never_paid_zombie → DO NOT PAY. The endpoint is broken, a honeypot, or has never been paid (CDP-confirmed). - ok: true AND warnings include slow / slow_p99 / new_provider → pay only if the task tolerates slowness or unproven providers; otherwise call /forensics. - metadata.has_free_trial: true → SIWE-verified free path; try $0 first. - metadata.established: true → ≥5 unique payers in 30d (positive). 3. If preflight blocked the URL, call POST https://x402station.io/api/v1/alternatives ($0.005 USDC) with the same { url } (or a { taskClass } hint). Pick the first returned alternative whose match_reason is same_service or same_provider; that is the closest swap-in. 4. For high-volume routing (>1000 preflight calls/month), buy POST /api/v1/credits ($0.50 = 1000 prepaid preflights, $0.0005/call effective) once and pass X-Credit-Id on every preflight call. 5. For long-running watches, subscribe via POST /api/v1/watch ($0.01 USDC = 30-day watch + 100 prepaid HMAC- signed alerts) — useful for trading agents that pay the same endpoint hourly. ``` ## Verify your work After adding this skill to an agent or SDK, verify behavior against a test URL before funding a wallet: 1. First request to a paid route returns HTTP 402 with a JSON x402 v2 `PaymentRequiredResponse` body and a base64 `payment-required` header. 2. The production x402 challenge uses Base mainnet (`eip155:8453`), USDC, scheme `exact`, and receiver `0x4053338C7cB38624C0bc23c900F78Cf8470b4E38`. 3. A signed retry returns JSON with `ok`, `warnings[]`, and `metadata`. 4. If `ok: false`, the agent must not pay the target endpoint. It should call `alternatives` or ask for human confirmation. 5. If the flow fails after two attempts, stop and surface the exact response instead of adding more payment retries. ## Common mistakes Bad: paying the target endpoint directly, then checking risk after money moved. ```ts const paidFetch = withX402Payment(fetch, wallet); const response = await paidFetch(endpointUrl); const verdict = await preflight(endpointUrl); ``` Correct: check endpoint risk first, then sign payment only if the verdict allows it. ```ts const verdict = await preflight(endpointUrl); if (!verdict.ok) { throw new Error("Blocked by x402station: " + verdict.warnings.join(", ")); } const paidFetch = withX402Payment(fetch, wallet); const response = await paidFetch(endpointUrl); ``` Bad: treating a saved verification status as current truth. ```ts if (savedCertificate.result === "verified") { await payEndpoint(savedCertificate.url); } ``` Correct: use saved certificates as provenance, then fetch live risk before a new payment. ```ts const verdict = await preflight(savedCertificate.url); if (verdict.ok) { await payEndpoint(savedCertificate.url); } ``` ## When to use this skill - About to pay any x402 endpoint URL → call `preflight` first ($0.001). Returns `{ ok, warnings[], metadata }`. `ok: false` means at least one critical signal fired (`dead`, `zombie`, `decoy_price_extreme`). - Testing your agent before funding a wallet → call `/api/v1/preflight-trial` directly (free, no PAYMENT-SIGNATURE). It accepts one `{ url }`, returns the same verdict shape as `preflight`, and is rate-limited to 10 calls per IP per UTC day with a 5-minute cache. - Evaluating 2–50 URLs at once (aggregator / router / crawler) → call `preflight_batch` ($0.025 flat). POST `{ urls: string[] }`, get one result entry per URL in input order. Same signal vocabulary + CDP enrichment as `preflight`. At full 50-URL batch: $0.0005/url (50% off). Response includes `summary { total, ok, blocked, by_recommended_action }` so the agent can branch without iterating results. - Need 7-day history (uptime, latency p50/p90/p99, decoy probability) on one URL → call `forensics` ($0.001). Superset of preflight. - Want a precomputed blacklist to filter URLs locally → call `catalog_decoys` ($0.005). Internal data refreshes every 10 min — pull hourly is plenty. - Preflight returned `ok: false` and you need a routing fallback → call `alternatives` ($0.005) with the flagged `url` (or a `taskClass` hint). Returns up to 5 healthy sibling endpoints in the same provider / domain / category / price-band, ranked by uptime + latency. - Polling for catalog changes (aggregator agents) → call `whats_new` ($0.001). Body `{ since?, limit? }` (default since=now-24h, limit=200, max 500). Returns added/removed endpoints + service-level counts. Internal ingest cron runs every 5 min — polling more often is wasted. - High-volume preflight workload (bot crawling many URLs) → `buy_credits` ($0.50) once, then pass the returned `creditId` via `X-Credit-Id` header on every `/api/v1/preflight` call. 1000 prepaid calls per bundle = $0.0005/call (50% off). On exhaustion/expiry the middleware falls through to per-call x402 automatically — no code change needed. `credits_status(creditId)` is free and returns current balance + expiry. - Need a webhook on endpoint state change → `watch_subscribe` ($0.01 = 30-day watch + 100 prepaid alerts). HMAC-SHA256-signed POSTs to your webhookUrl when subscribed signals fire/clear. ## When NOT to use this skill - For endpoints outside the agentic.market catalog. Calling `preflight` with a URL we don't track returns `{ ok: false, warnings: ["unknown_endpoint"] }` — and the call is still billed (the lookup costs the same). - As an x402 facilitator. We're an endpoint risk signal layer, not a facilitator; pay through your own (Coinbase CDP or x402.org/facilitator). - For endpoint discovery. We don't list available x402 endpoints. Use the [agentic.market](https://agentic.market) API or [Coinbase Bazaar](https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources) for that. ## Auth x402 v2 payment, EIP-712 authorization in the `PAYMENT-SIGNATURE` header. - Network: Base mainnet (`eip155:8453`) - Asset: USDC (Circle) - Scheme: `exact` - Receiver: `0x4053338C7cB38624C0bc23c900F78Cf8470b4E38` - Facilitator: `https://x402.org/facilitator` (Coinbase CDP for mainnet) The first request returns HTTP 402 with the same x402 v2 `PaymentRequiredResponse` in two places: JSON response body for body-first clients, and a base64-encoded `payment-required` header for header-first clients. Decode → sign EIP-712 → retry with `PAYMENT-SIGNATURE` header carrying the signed payload. ## Tools | Tool | Method + path | Price | |---|---|---| | `preflight_trial` | POST /api/v1/preflight-trial | free, rate-limited | | `preflight` | POST /api/v1/preflight | $0.001 (or X-Credit-Id) | | `preflight_batch` | POST /api/v1/preflight-batch | $0.025 (1–50 URLs) | | `forensics` | POST /api/v1/forensics | $0.001 | | `catalog_decoys` | POST /api/v1/catalog/decoys | $0.005 | | `alternatives` | POST /api/v1/alternatives | $0.005 | | `whats_new` | POST /api/v1/whats-new | $0.001 | | `buy_credits` | POST /api/v1/credits | $0.50 (= 1000 preflights) | | `credits_status` | GET /api/v1/credits/{id} | free, id-gated | | `watch_subscribe` | POST /api/v1/watch | $0.01 | | `watch_status` | GET /api/v1/watch/{id} | free, secret-gated | | `watch_unsubscribe` | DELETE /api/v1/watch/{id} | free, secret-gated | Body for paid POSTs: `{ "url": "" }`. `/api/v1/preflight-batch` accepts `{ "urls": ["", ...] }` (1–50 http(s) strings; duplicates are deduplicated). `/api/v1/watch` also accepts `webhookUrl` and an optional `signals` array. `/api/v1/alternatives` accepts `{ url?, taskClass?, limit? }` (at least one of `url` or `taskClass`; `limit` 1..10, default 5). `/api/v1/whats-new` accepts `{ since?, limit? }` (default since=now-24h max 30d back; limit 1..500 default 200). ## Signal vocabulary `warnings[]` strings returned by `preflight` / `forensics`. Critical signals (those that flip `ok` to `false`) are bold: - **`dead`** — ≥3 unhealthy probes in the last 30 min - **`zombie`** — ≥3 probes in the last hour, zero healthy - **`decoy_price_extreme`** — listed price ≥ $1000 USDC - **`dead_7d`** — ≥20 probes over 7 days, zero healthy (forensics-only) - **`mostly_dead`** — ≥20 probes over 7 days, uptime < 50% (forensics-only) - **`never_paid_zombie`** — CDP confirms zero paid calls in 30d, no historical lastCalledAt, endpoint older than 30d. Distinct from `zombie` (HTTP probes only) — checks the Coinbase paid-call ledger - `unknown_endpoint` — URL not in our catalog (informational; still billed) - `no_history` — in catalog but no probes in the last hour - `suspicious_high_price` — price $10–$1000 USDC - `slow` — avg latency ≥ 2000 ms in the last hour - `new_provider` — service first seen < 24h ago - `slow_p99` — latency_p99 ≥ 5000 ms (forensics-only) - `price_outlier_high` — current price > 10× provider-group median - `high_concentration` — endpoint's provider owns ≥ 5% of effective catalog supply - `wildcard_402` — provider returns x402 challenges for random non-catalog paths; raw path count is kept separate from effective supply - `spa_fallback` — provider returns a 200 HTML app shell for random non-catalog paths; raw path count is kept separate from effective supply - `proxy_markup` — catalog evidence suggests a third-party proxy/reseller; inspect `metadata.proxy_markup.estimated_markup_ratio` before auto-paying Positive informational flags surfaced under `metadata` (NOT in `warnings[]`): - `metadata.established` — CDP reports ≥ 5 distinct payer wallets in 30d (real-demand signal; useful for ranking `alternatives` candidates) - `metadata.has_free_trial` — endpoint advertises an `extensions.agentkit` (Exa-style) or `extensions.sign-in-with-x` SIWE handshake; agent can attempt `$0` first ## Adapter For Claude Code / Cursor / Windsurf / Continue agents speaking the Model Context Protocol: ```bash npx -y x402station-mcp ``` The adapter wraps all the paid tools above plus the free secret/id-gated ones (ten tools in total). Auto-signs PAYMENT-SIGNATURE through `AGENT_PRIVATE_KEY`. ## Links - Service: - Manifest: - OpenAPI: - A2A agent card: - API Catalog (RFC 9727): - Source: - npm: - MCP Registry: ## Contact - General + commercial: - Bug reports: - Security disclosures (RFC 9116): ## License MIT (source code). Data API is x402-paid, pay per call.