--- name: x402station.io description: x402station.io provides safety and discovery infrastructure for the x402 payment protocol. It offers preflight checks, batch endpoint vetting, a blacklist catalog of known-bad endpoints, fallback alternative discovery, and a diff feed for tracking catalog changes over time. host: x402station.io --- # x402station.io x402station.io is a safety and catalog layer purpose-built for agents operating within the x402 payment ecosystem. It serves agents that need to vet endpoints before committing funds, discover healthy alternatives when an endpoint fails, maintain a local blacklist of dangerous URLs, and track catalog additions or removals over time. It does not execute payments or provide price feeds for non-x402 assets. ## When to use this host Use x402station.io when an agent operates within the x402 payment protocol and needs to gate payments on safety verdicts, maintain a blacklist of dangerous endpoints, discover fallback alternatives, or track catalog changes over time. Use check-x402-preflight for single-URL pre-payment checks and check-x402-endpoints-batch for bulk vetting in aggregator or catalog-crawling workflows. Use fetch-decoy-catalog on startup to seed a local blacklist cheaply before any probing. Do not use this host for real-time uptime monitoring, streaming health checks, non-x402 URL validation, cross-chain routing, or asset price feeds — those require dedicated monitoring services or exchange APIs outside this catalog. ## Capabilities ### Pre-Payment Safety Checks Validates x402 endpoints before an agent commits funds, returning machine-readable verdicts, risk scores, and warnings for one or many URLs at once. - **`check-x402-preflight`** — Validates whether a target x402 endpoint is safe to pay by returning a machine-readable verdict with warnings, risk score, and endpoint metadata. - **`check-x402-endpoints-batch`** — Evaluates 1–50 x402 endpoint URLs in a single call, returning per-URL safety verdicts, risk scores, warnings, and CDP-enriched metadata for $0.025 USDC flat. ### Blacklist and Decoy Detection Provides a pre-built oracle-flagged blacklist of known-bad endpoints (decoys, zombies, dead URLs) so agents can reject dangerous targets without probing them individually. - **`fetch-decoy-catalog`** — Returns the full oracle-flagged blacklist of dangerous x402 endpoints (decoy_price_extreme, zombie, dead_7d, mostly_dead) with per-entry metadata and per-reason counts, priced at $0.005 USDC. ### Fallback and Alternative Discovery Given a failed or flagged endpoint, returns ranked healthy alternatives in the same service category or price band, enabling agents to reroute without manual catalog searches. - **`fetch-endpoint-alternatives`** — Given a flagged URL or a task-class hint, returns up to 10 healthy sibling endpoints ranked by 7-day uptime and 1-hour latency, filtered for dead or erroring candidates. ### Catalog Change Tracking Surfaces newly added or removed x402 endpoints since a given timestamp, allowing agents to keep a local catalog view current without re-fetching the full dataset. - **`fetch-catalog-diff`** — Returns a catalog diff of x402 endpoints added or removed since a given timestamp, including per-endpoint metadata such as URL, service name, provider, category, and price in USDC. ## Workflows ### Safe Bulk Routing with Fallback *Use when an agent needs to route traffic across multiple x402 endpoints and must handle failures gracefully by finding healthy alternatives.* 1. **`fetch-decoy-catalog`** — On startup or refresh, populate a local blacklist of known-bad URLs to skip before any vetting. 2. **`check-x402-endpoints-batch`** — Submit the candidate URL list (excluding blacklisted entries) for batch preflight vetting, receiving per-URL verdicts and risk scores. 3. **`fetch-endpoint-alternatives`** — For any URL that returned ok=false, retrieve ranked healthy alternatives in the same category or price band to substitute into the routing plan. ### Incremental Catalog Refresh with Safety Gate *Use when an agent needs to discover newly listed x402 endpoints on a schedule and vet them before adding them to an active routing table.* 1. **`fetch-catalog-diff`** — Poll for endpoints added or removed since the last known timestamp to identify net-new candidates. 2. **`check-x402-endpoints-batch`** — Submit newly added endpoints for batch preflight vetting to confirm they are safe before routing traffic to them. ### Single-Endpoint Pre-Payment Gate *Use when an agent is about to sign a payment for a specific x402 endpoint and needs a safety verdict before committing funds, with a fallback if the check fails.* 1. **`check-x402-preflight`** — Run a single-URL preflight check to obtain a verdict, risk score, and warnings for the target endpoint. 2. **`fetch-endpoint-alternatives`** — If ok=false, retrieve ranked healthy alternatives in the same service or category to substitute for the rejected endpoint. ## Skill reference ### `check-x402-endpoints-batch` **Batch Preflight Checker** — Evaluates 1–50 x402 endpoint URLs in a single call, returning per-URL safety verdicts, risk scores, warnings, and CDP-enriched metadata for $0.025 USDC flat. *Use when:* Use when an agent needs to vet multiple x402 payment endpoints before routing traffic or making payments, especially in aggregator, bulk-routing, or catalog-crawling workflows where checking each URL individually would be costly. *Not for:* Do not use for checking non-x402 URLs or for real-time streaming health monitoring; use a dedicated uptime monitor instead. Not a substitute for single-URL preflight when only one URL needs checking. **Inputs:** - `urls` (array, required) — Full URIs of x402 endpoints to evaluate. 1–50 per call. Duplicates are deduplicated server-side; input order is preserved in results. **Returns:** Returns a results array with one entry per URL containing ok boolean, warnings list, risk_score, confidence, recommended_action, reason_codes, CDP-enriched metadata, and raw evidence fields. **Example:** `{"urls":["https://api.venice.ai/api/v1/chat/completions","https://api.exa.ai/search"]}` --- ### `fetch-catalog-diff` **What's New Feed — Catalog Diff** — Returns a catalog diff of x402 endpoints added or removed since a given timestamp, including per-endpoint metadata such as URL, service name, provider, category, and price in USDC. *Use when:* Use when an agent needs to detect newly listed or recently removed x402 API endpoints since a known point in time, without re-fetching the entire catalog. Suitable for polling on a schedule no more frequent than every 5 minutes. *Not for:* Do not use for real-time streaming of catalog changes; the ingest cron runs every 5 minutes so more frequent calls return identical data. Not suitable for fetching full catalog state — use a full catalog endpoint instead. **Inputs:** - `since` (string) — ISO 8601 timestamp marking the start of the diff window. Defaults to now minus 24 hours. Cannot be older than 30 days or set in the future. - `limit` (integer) — Per-list cap applied independently to added_endpoints and removed_endpoints. Range 1–500, default 200. If the cap is hit and more rows existed, the truncated flag is set to true. **Returns:** Returns since/until window metadata, window_hours, an added_endpoints array with per-endpoint url/service/price fields, a removed_endpoints array, and a truncated flag if the limit was reached. **Example:** `{"since": "2026-04-22T12:34:56Z", "limit": 200}` --- ### `fetch-endpoint-alternatives` **X402 Station Endpoint Alternatives** — Given a flagged URL or a task-class hint, returns up to 10 healthy sibling endpoints ranked by 7-day uptime and 1-hour latency, filtered for dead or erroring candidates. *Use when:* Use when a preflight check returns ok=false for a target endpoint and the agent needs ranked fallback alternatives in the same service, provider, domain, category, or price band — or when the agent only has a task class and wants to discover capable endpoints. *Not for:* Do not use for real-time price feeds or live health checks on a single endpoint; use a preflight or health-check API instead. Not suitable for cross-chain or cross-protocol routing outside the x402station catalog. **Inputs:** - `url` (string) — URI of the flagged endpoint to find alternatives for. The catalog matches siblings by service, provider, domain, category, and price band. At least one of url or taskClass is required. - `taskClass` (string) — Service category hint (e.g. 'llm-completions'). Used as a fallback match key when url is unknown to the catalog, or alone when the agent only has a capability in mind. Max 80 chars. - `limit` (integer) — Maximum number of alternatives to return. Integer between 1 and 10, default 5. **Returns:** Returns a target metadata object, match_strategy string, an alternatives array of ranked healthy sibling endpoints (empty when none qualify), candidate counts, and an attribution provenance block. **Example:** `{"url": "https://api.venice.ai/api/v1/chat/completions", "taskClass": "llm-completions", "limit": 5}` --- ### `fetch-decoy-catalog` **Decoy Catalog** — Returns the full oracle-flagged blacklist of dangerous x402 endpoints (decoy_price_extreme, zombie, dead_7d, mostly_dead) with per-entry metadata and per-reason counts, priced at $0.005 USDC. *Use when:* Use when an agent needs to populate or refresh a local blacklist of known-bad x402 endpoints before making preflight calls, or on startup to establish a baseline set of URLs to reject without further probing. *Not for:* Do not use for real-time per-URL risk checks on a single endpoint; use a preflight/oracle lookup for that. Not a substitute for live health probing — data reflects oracle state at generation time and may be truncated at 2000 entries. **Inputs:** - `body` (object) — No parameters required. POST with an empty JSON object {} or no body. **Returns:** Returns a snapshot with generated_at timestamp, counts.total (up to 2000), per-reason breakdown, truncated flag, and an entries array where each item includes url, service_id, reasons, probes_7d, healthy_7d, uptime_7d_pct, and last_probe_at. **Example:** `POST https://x402station.io/api/v1/catalog/decoys Content-Type: application/json {}` --- ### `check-x402-preflight` **x402 Preflight Check** — Validates whether a target x402 endpoint is safe to pay by returning a machine-readable verdict with warnings, risk score, and endpoint metadata. *Use when:* Use when an agent is about to sign a PAYMENT-SIGNATURE for any x402 endpoint URL — especially unfamiliar or third-party ones — and needs to gate the payment on a safety verdict before committing funds. *Not for:* Do not use as a real-time uptime monitor or streaming health check; this is a single-shot pre-payment safety check, not a continuous availability probe. **Inputs:** - `url` (string, required) — Full URI of the x402 endpoint the agent is about to pay. **Returns:** Returns ok (boolean), a warnings array with codes like unknown_endpoint or dead, a metadata object with endpoint details, a risk_score float, and an attribution provenance block. **Example:** `{"url": "https://api.venice.ai/api/v1/chat/completions"}` ---