# x402station

> Pre-flight oracle for the x402 agentic-commerce network. AI agents call us before any paid x402 request to avoid decoys, zombie endpoints, and price traps. All 33,541 endpoints on agentic.market are probed independently every 10 minutes.

## What we do

- Probe every x402 endpoint (HTTP naked call, no payment) to measure uptime, latency, and status
- Snapshot every service's quality / totalCalls / uniquePayers / lastCalledAt from the catalog API
- Detect: zombie services, price-drift, decoy endpoints ($1000+ traps), catalog gaming, new-provider risk
- Expose all this to agents via x402-paid JSON endpoints

## Paid agent endpoints

- [POST /api/v1/preflight](https://x402station.io/api/v1/preflight): $0.001 USDC. Returns {ok, warnings, metadata}
- [POST /api/v1/forensics](https://x402station.io/api/v1/forensics): $0.001 USDC. 7-day uptime + latency p50/p90/p99 + status-code distribution + concentration-group stats + decoy probability (superset of preflight)
- [POST /api/v1/catalog/decoys](https://x402station.io/api/v1/catalog/decoys): $0.005 USDC. Full blacklist of active endpoints flagged as decoy / zombie / dead_7d / mostly_dead — internal data refreshes every 10 min, no point polling more often
- [POST /api/v1/watch](https://x402station.io/api/v1/watch): $0.01 USDC = 30-day subscription + 100 prepaid alerts on one URL. HMAC-SHA256-signed POSTs to the agent's webhookUrl when subscribed signals fire/clear. `GET /api/v1/watch/<id>?secret=...` (free) for status, `DELETE` (free) to unsubscribe. Worker diff-loop runs every 5 min; alert delivery has 5s timeout, 5 retries with implicit 5min backoff via the next tick
- [POST /api/v1/alternatives](https://x402station.io/api/v1/alternatives): $0.005 USDC. Given a URL flagged by preflight (or a `taskClass` hint), returns up to 5 healthy sibling endpoints in the same provider/domain/category/price-band. Filters out 7-day-dead and 1-hour-erroring candidates; ranks by uptime + latency. Solves the routing-fallback question after `ok=false` from preflight
- [POST /api/v1/whats-new](https://x402station.io/api/v1/whats-new): $0.001 USDC. Catalog diff polling. Body `{ since?, limit? }` (default since=now-24h, limit=200, max 500). Returns `added_endpoints[]` (`first_seen_at >= since` AND `is_active=true`), `removed_endpoints[]` (flipped to `is_active=false` since), and counts. Polling-friendly — internal data refreshes every 5 min via the ingest cron, so polling more often than that returns identical data
- [POST /api/v1/credits](https://x402station.io/api/v1/credits): **$0.50 USDC** = 1000 prepaid `/api/v1/preflight` calls. Effective rate $0.0005/call (50% off the per-call $0.001 tier). Returns `{ creditId, balance: 1000, expiresAt }` — store the creditId, it's the bearer token. Use via `X-Credit-Id` header on subsequent /api/v1/preflight calls. On exhaustion/expiry the middleware falls through to per-call x402 automatically. `GET /api/v1/credits/<id>` (free) returns balance + expiry

## Agent middleware (one-line auto-shielding)

For agents that already wrap fetch with `@x402/fetch`, [`x402station-middleware`](https://www.npmjs.com/package/x402station-middleware) is a drop-in: `wrapWithPreflight(x402Fetch, { account })` calls `/preflight` before every paid x402 request and refuses decoy/zombie/dead endpoints automatically (throws `PreflightBlockedError`).

```ts
import { wrapWithPreflight } from "x402station-middleware";
const safeFetch = wrapWithPreflight(x402Fetch, { account });
await safeFetch("https://api.example.com/x402-route");  // throws if decoy
```

Default fail-closed (refuses if preflight unreachable). Per-instance TTL cache (5 min default, matches our internal probe cadence). `creditId` option threads bulk credits → $0.0005/call.

## MCP adapter (Claude Code, Cursor, Windsurf, Continue)

For agents speaking the Model Context Protocol, install once and call the three tools without writing any x402 plumbing:

```bash
npx -y x402station-mcp
```

In your MCP client config:

```json
{
  "mcpServers": {
    "x402station": {
      "command": "npx",
      "args": ["-y", "x402station-mcp"],
      "env": { "AGENT_PRIVATE_KEY": "0x..." }
    }
  }
}
```

Tools exposed (ten): paid — `preflight`, `forensics`, `catalog_decoys`, `alternatives`, `whats_new`, `watch_subscribe`, `buy_credits`. Free + secret-gated/id-gated — `watch_status`, `watch_unsubscribe`, `credits_status`. Wallet must hold Base mainnet USDC. Source: [npm](https://www.npmjs.com/package/x402station-mcp), [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers/io.github.sF1nX/x402station).

## Signal vocabulary

What `warnings[]` strings mean (from preflight + forensics):

| Signal | Tier | When it fires |
|---|---|---|
| `unknown_endpoint` | info | URL not in our catalog at all |
| `no_history` | info | In catalog but no probes in the last hour |
| `dead` | **critical** | ≥3 unhealthy probes in last 30 min |
| `zombie` | **critical** | ≥3 probes in last hour, zero healthy |
| `decoy_price_extreme` | **critical** | Price ≥ $1000 USDC (anti-scraper honeypot zone) |
| `suspicious_high_price` | warn | Price $10–$1000 USDC (unusual, verify) |
| `slow` | warn | Avg latency ≥ 2000 ms in last hour |
| `new_provider` | warn | Service first seen < 24h ago |
| `dead_7d` | **critical** | ≥20 probes in last 7d, zero healthy |
| `mostly_dead` | **critical** | ≥20 probes in last 7d, uptime < 50% |
| `slow_p99` | warn | latency_p99_ms ≥ 5000 |
| `price_outlier_high` | warn | Current price > 10× provider-group median |
| `high_concentration` | warn | Endpoint's provider owns ≥ 5% of the catalog |

`ok: true` ⇔ NONE of the **critical** signals fire. Non-critical signals can be present alongside `ok: true`. An endpoint that's not in our catalog returns `{ ok: false, warnings: ["unknown_endpoint"] }` — this IS billed ($0.001) because the lookup itself uses the same query path; agents should expect this for any URL outside the agentic.market index.

## Manifest + docs

- [/.well-known/x402](https://x402station.io/.well-known/x402): agent-readable manifest (JSON, live counts)
- [/.well-known/agent-card.json](https://x402station.io/.well-known/agent-card.json): Google A2A agent card
- [/.well-known/agent-skills](https://x402station.io/.well-known/agent-skills): agent-skills v1 (when-to-use / when-not-to-use)
- [/.well-known/api-catalog](https://x402station.io/.well-known/api-catalog): RFC 9727 linkset+json — every machine-readable artefact in one fetch
- [/.well-known/mcp/server-card.json](https://x402station.io/.well-known/mcp/server-card.json): MCP server card
- [/.well-known/oauth-protected-resource](https://x402station.io/.well-known/oauth-protected-resource): RFC 9728 stub (empty arrays — payment is x402, not OAuth)
- [/.well-known/oauth-authorization-server](https://x402station.io/.well-known/oauth-authorization-server): RFC 8414 stub (same)
- [/api](https://x402station.io/api): developer documentation (HTML)
- [/api/openapi.json](https://x402station.io/api/openapi.json): OpenAPI 3.1 spec

## Free public surfaces

- [Live dashboard](https://x402station.io): human-readable stats
- [State of x402](https://x402station.io/state-of-x402): data-first ecosystem snapshot
- [Sector heatmap](https://x402station.io/heatmap): live by-sector breakdown of the catalog — services, endpoints, hourly uptime, decoy density, median price per category. Hybrid classifier (agentic.market category + keyword heuristic), 9 sectors + Aggregator + Other
- [Per-service pages](https://x402station.io/service/[id]): 586 service detail pages with uptime + latency history
- [GitHub repository (client SDKs)](https://github.com/sF1nX/x402station-mcp): MCP adapter, AgentKit action provider, demo shielded-agent (oracle backend kept private)

## Articles

- [We probed 20,338 x402 endpoints. 161 are agent honeypots.](https://dev.to/afx/we-probed-20338-x402-endpoints-161-are-agent-honeypots-4c3n) — methodology, decoy distribution, CDP-mainnet $0.001 floor, first on-chain settlement (2026-04-26)
- [We graded every x402 endpoint with Cloudflare's agent-readiness scanner](https://x402station.io/blog/cloudflare-x402-readiness) — Cloudflare isitagentready.com run against the entire active x402 catalog, level distribution, the Bazaar-registration finding, level-4 path (2026-04-27). Markdown source: [/blog/raw/cloudflare-x402-readiness](https://x402station.io/blog/raw/cloudflare-x402-readiness)
- [Blog index](https://x402station.io/blog): full list of long-form posts

## Payment details

- Protocol: [x402 v2](https://x402.org)
- Networks: Base mainnet (eip155:8453) and Base Sepolia (eip155:84532)
- Asset: USDC (Circle)
- Scheme: exact
- Recipient: 0x4053338C7cB38624C0bc23c900F78Cf8470b4E38
- Facilitator: https://x402.org/facilitator

## Why pre-flight matters

- 74 active endpoints currently priced at $1000+ USDC — "anti-scraper" decoys. An agent paying one of them drains its wallet.
- 52% of the catalog is a single provider (lowpaymentfee.com has 10,657 sub-endpoints) — agents should understand this concentration.
- ~10 services are 100% dead but still listed (solopreneur.apitoai.xyz etc).
- Facilitator-based monitors (Dexter, x402list.fun) see only successful payments. We see everything.

## Contact

- General + commercial: hello@x402station.io
- Bug reports: https://github.com/sF1nX/x402station-mcp/issues
- Security disclosures (RFC 9116): https://x402station.io/.well-known/security.txt

## License

Source code: MIT. Data API: x402-paid, pay per call.