{"openapi":"3.1.0","info":{"title":"x402station.io API | independent risk-signal layer for x402 agentic commerce","version":"1.0.0","description":"Independent risk-signal layer for x402 agentic commerce — endpoint evidence (decoy / zombie / price-trap / never-paid) before an agent authorizes payment.","contact":{"name":"x402station.io","email":"hello@x402station.io","url":"https://github.com/sF1nX/x402station-mcp"},"license":{"name":"MIT","url":"https://github.com/sF1nX/x402station-mcp/blob/main/LICENSE"}},"servers":[{"url":"https://x402station.io"}],"x-x402":{"version":2,"facilitator":"https://x402.org/facilitator","networks":["eip155:8453","eip155:84532"],"asset":"USDC","scheme":"exact","payTo":"0x4053338C7cB38624C0bc23c900F78Cf8470b4E38"},"x-datasets":[{"id":"x402station/preflight-dataset-v0_1","name":"x402station.io Preflight Dataset v0.1","url":"https://huggingface.co/datasets/x402station/preflight-dataset-v0_1","license":"CC-BY-4.0","refreshCadence":"weekly snapshot","boundary":"Endpoint-level aggregate probe data is open; raw probe-by-probe time-series remains gated."}],"x-response-provenance":{"description":"Ten product routes include passive, machine-readable attribution. This is provenance only: it identifies x402station.io as the signal authority and is not merchant endorsement or a trust guarantee.","bodyField":"attribution","bodyShape":{"authority":"x402station.io","product":"<Product> by x402station.io","claim":"machine-readable response provenance, not merchant endorsement","url":"https://x402station.io","spec":"https://x402station.io/spec"},"headers":{"X-x402station-Authority":"https://x402station.io","X-x402station-Product":"<Product> by x402station.io","Link":"<https://x402station.io/spec>; rel=\"describedby\""},"routes":["/api/v1/preflight-trial","/api/v1/preflight","/api/v1/preflight-batch","/api/v1/forensics","/api/v1/catalog/decoys","/api/v1/whats-new","/api/v1/alternatives","/api/v1/credits","/api/v1/watch","/api/v1/verified"]},"paths":{"/api/v1/preflight-trial":{"post":{"operationId":"preflightTrial","summary":"Free Preflight self-test for one x402 endpoint URL","description":"Anonymous first-call trial. No PAYMENT-SIGNATURE required. POST one {url}; returns the same verdict shape as paid /api/v1/preflight. Rate-limited to 10 calls per IP per UTC day and 50 calls per target host per UTC day, one URL per call, with a 5-minute cache. Production agents should use paid /preflight for fresh data, bulk, and SLA.","x-x402-price":"free","x-price-usdc":0,"x-risk-tier":"safety","x-agent-use-cases":["Agent self-test before wiring a funded wallet.","Validate parser compatibility with the paid /api/v1/preflight response shape."],"x-rate-limit":{"ip_per_utc_day":10,"target_host_per_utc_day":50,"cache_ttl_seconds":300,"max_urls_per_call":1},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Full URL of the x402 endpoint the agent wants to test","example":"https://api.venice.ai/api/v1/chat/completions"}}}}}},"responses":{"200":{"description":"Preflight report without x402 payment","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"},"risk_score":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"recommended_action":{"type":"string","enum":["pay","skip","use_alternatives","investigate"]},"reason_codes":{"type":"array","items":{"type":"string"}},"observed_at":{"type":"string","format":"date-time"},"evidence":{"type":"object"}}}}}},"400":{"description":"Malformed body — one `url` required"},"429":{"description":"Trial rate limit exceeded. Read retry-after / x-rate-limit-reset headers."},"503":{"description":"DB query exceeded statement_timeout. Retry after the next probe/cache window."}}}},"/api/v1/preflight":{"post":{"operationId":"preflight","summary":"Preflight risk check for any x402 endpoint URL","description":"Preflight x402 scam check: endpoint risk before you pay — decoy / zombie / price-trap / never-paid? Trust verdict in ~200ms before PAYMENT-SIGNATURE.","x-x402-price":"$0.001","x-price-usdc":0.001,"x-risk-tier":"safety","x-agent-use-cases":["Before signing PAYMENT-SIGNATURE for any third-party x402 URL — gate the payment on the verdict.","When a workflow's paid step targets an unfamiliar endpoint sourced from agentic.market."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Full URL of the x402 endpoint the agent is about to pay","example":"https://api.venice.ai/api/v1/chat/completions"}}}}}},"responses":{"200":{"description":"Preflight report (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"true only when no critical warning"},"warnings":{"type":"array","items":{"type":"string","enum":["unknown_endpoint","no_history","dead","zombie","decoy_price_extreme","suspicious_high_price","slow","new_provider","never_paid_zombie","proxy_markup","wildcard_402","spa_fallback"]}},"metadata":{"type":"object","properties":{"url":{"type":"string"},"service":{"type":"string"},"service_id":{"type":"string"},"price_usdc":{"type":"string"},"currency":{"type":"string"},"uptime_1h_pct":{"type":["integer","null"]},"avg_latency_ms":{"type":["integer","null"]},"is_active":{"type":"boolean"},"proxy_markup":{"type":"object","description":"Present when `warnings` includes `proxy_markup`. Heuristic proxy/resell evidence and a conservative estimated markup ratio.","properties":{"detected":{"type":"boolean","const":true},"confidence":{"type":"string","enum":["medium","high"]},"observed_price_usdc":{"type":["number","null"]},"reference_price_usdc":{"type":["number","null"]},"estimated_markup_ratio":{"type":["number","null"]},"basis":{"type":"string","enum":["service_median","x402_floor"]},"evidence":{"type":"array","items":{"type":"string"}}}},"wildcard_402_detected":{"type":"boolean","description":"true when the provider has been confirmed to return x402 challenges for random non-catalog paths."},"wildcard_402_checked_at":{"type":["string","null"],"format":"date-time"},"spa_fallback_detected":{"type":"boolean","description":"true when the provider has been confirmed to return a 200 HTML app shell for random non-catalog paths."},"spa_fallback_checked_at":{"type":["string","null"],"format":"date-time"},"effective_count_basis":{"type":["string","null"],"enum":["sitemap_url_count","manifest_resource_count","canonical_homepage",null]}}},"risk_score":{"type":"number","minimum":0,"maximum":1,"description":"Float [0, 1]. 0 = clean, 1 = critical. Saturates at the most-severe warning. Stable across calls for the same input + signal set."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Float [0, 1]. Reflects probe sample size in the relevant window. Low confidence (<0.4) → treat the verdict as a hint, not a guarantee."},"recommended_action":{"type":"string","enum":["pay","skip","use_alternatives","investigate"],"description":"Stable enum for agent code-branching. `skip` = wallet-drain risk. `use_alternatives` = blocked but in catalog (call /api/v1/alternatives). `investigate` = ok=true with caveats OR low-confidence ok=false. `pay` = clean."},"reason_codes":{"type":"array","description":"Stable enum aligned with `warnings`; named separately so future versions can diverge if needed.","items":{"type":"string"}},"observed_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the assessment. Use this to detect stale cached responses."},"evidence":{"type":"object","description":"The raw counters that backed the verdict. Lets agents re-derive their own scores or build their own thresholds.","properties":{"probes_1h":{"type":"integer"},"healthy_1h":{"type":"integer"},"errors_30m":{"type":"integer"},"price_amount_usdc":{"type":["string","null"]},"service_age_hours":{"type":["number","null"]},"proxy_markup":{"type":"object"},"wildcard_402_detected":{"type":"boolean"}}}}}}}},"400":{"description":"Malformed body — `url` required and must start with http(s)"},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query exceeded statement_timeout before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry after the next probe/cache window.","content":{"application/json":{}}}}}},"/api/v1/preflight-batch":{"post":{"operationId":"preflightBatch","summary":"Batch preflight for 1–50 x402 endpoint URLs","description":"Batch x402 endpoint risk check: preflight many endpoints before paying any of them.","x-x402-price":"$0.025","x-price-usdc":0.025,"x-risk-tier":"safety","x-agent-use-cases":["aggregator","bulk-routing","catalog-crawler"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":50,"description":"Full URLs of x402 endpoints to evaluate. 1–50 per call. Duplicates are deduplicated; input order is preserved in results.","example":["https://api.venice.ai/api/v1/chat/completions","https://api.exa.ai/search"]}}}}}},"responses":{"200":{"description":"Batch preflight report (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","description":"One entry per deduplicated input URL, in input order.","items":{"type":"object","properties":{"url":{"type":"string","description":"The input URL this entry describes."},"ok":{"type":"boolean","description":"true only when no critical warning fires."},"warnings":{"type":"array","items":{"type":"string","enum":["unknown_endpoint","no_history","dead","zombie","decoy_price_extreme","suspicious_high_price","slow","new_provider","never_paid_zombie","proxy_markup","wildcard_402","spa_fallback"]}},"metadata":{"type":"object","properties":{"url":{"type":"string"},"service":{"type":"string"},"service_id":{"type":"string"},"price_usdc":{"type":"string"},"currency":{"type":"string"},"uptime_1h_pct":{"type":["integer","null"]},"avg_latency_ms":{"type":["integer","null"]},"is_active":{"type":"boolean"},"established":{"type":"boolean"},"has_free_trial":{"type":"boolean"},"proxy_markup":{"type":"object","description":"Present when `warnings` includes `proxy_markup`. Heuristic proxy/resell evidence and a conservative estimated markup ratio."},"wildcard_402_detected":{"type":"boolean"},"wildcard_402_checked_at":{"type":["string","null"],"format":"date-time"},"spa_fallback_detected":{"type":"boolean"},"spa_fallback_checked_at":{"type":["string","null"],"format":"date-time"},"effective_count_basis":{"type":["string","null"],"enum":["sitemap_url_count","manifest_resource_count","canonical_homepage",null]}}},"risk_score":{"type":"number","minimum":0,"maximum":1,"description":"Float [0, 1]. 0 = clean, 1 = critical."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Float [0, 1]. Reflects probe sample size in the relevant window."},"recommended_action":{"type":"string","enum":["pay","skip","use_alternatives","investigate"]},"reason_codes":{"type":"array","items":{"type":"string"}},"evidence":{"type":"object","properties":{"probes_1h":{"type":"integer"},"healthy_1h":{"type":"integer"},"errors_30m":{"type":"integer"},"price_amount_usdc":{"type":["string","null"]},"service_age_hours":{"type":["number","null"]}}}}}},"summary":{"type":"object","properties":{"total":{"type":"integer","description":"Deduplicated URL count."},"ok":{"type":"integer"},"blocked":{"type":"integer"},"by_recommended_action":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count per recommended_action value (pay / skip / use_alternatives / investigate)."}}},"observed_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the batch assessment."},"paid_amount":{"type":"string","description":"Fixed cost of this batch call. Always \"0.025\"."},"effective_price_per_url":{"type":"string","description":"paid_amount / deduplicated URL count, decimal string."}}}}}},"400":{"description":"Malformed request — urls must be an array of 1–50 http(s) strings; any malformed URL is reported as urls[N]: <reason>."},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query exceeded statement_timeout (15s) before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement. Returns { error, payment_settled: false, settlement_skipped: true, retry_after_seconds, detail }.","content":{"application/json":{}}}}}},"/api/v1/forensics":{"post":{"operationId":"forensics","summary":"Deep 7-day forensics report for an x402 endpoint","description":"Forensic x402 scam/risk report for a suspicious endpoint: probe history, signatures, decoy / price-trap patterns.","x-x402-price":"$0.001","x-price-usdc":0.001,"x-risk-tier":"analytics","x-agent-use-cases":["Decide whether to budget a long-running task on an endpoint with known latency tail (p99).","Investigate why preflight returned ok=false — full status-code distribution + 7-day timeline.","Provider concentration check before depending on a single high-share namespace."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Full URL of the x402 endpoint to analyse","example":"https://api.venice.ai/api/v1/chat/completions"}}}}}},"responses":{"200":{"description":"Forensics report (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string","enum":["unknown_endpoint","no_history","dead","zombie","decoy_price_extreme","suspicious_high_price","slow","new_provider","dead_7d","mostly_dead","slow_p99","price_outlier_high","high_concentration","never_paid_zombie","proxy_markup","wildcard_402","spa_fallback"]}},"decoy_probability":{"type":"number","minimum":0,"maximum":1,"description":"Blended risk score. 0 = clean, 1 = almost certainly a decoy."},"metadata":{"type":"object"},"uptime":{"type":"object","properties":{"probes_7d":{"type":"integer"},"healthy_7d":{"type":"integer"},"errors_7d":{"type":"integer"},"uptime_7d_pct":{"type":["integer","null"]},"uptime_1h_pct":{"type":["integer","null"]},"avg_latency_1h_ms":{"type":["integer","null"]},"hourly":{"type":"array","description":"Hourly buckets over the last 7 days, most recent first.","items":{"type":"object","properties":{"bucket":{"type":"string","format":"date-time"},"probes":{"type":"integer"},"healthy":{"type":"integer"},"avg_latency_ms":{"type":["integer","null"]}}}}}},"latency":{"type":"object","properties":{"p50_ms":{"type":["integer","null"]},"p90_ms":{"type":["integer","null"]},"p99_ms":{"type":["integer","null"]},"max_ms":{"type":["integer","null"]}}},"status_codes":{"type":"object","description":"Map of HTTP status code (or 'network_error') → count over the 7-day window.","additionalProperties":{"type":"integer"}},"concentration":{"type":"object","properties":{"group_size":{"type":"integer","description":"Effective endpoint count for the provider/domain group. Confirmed catch-all providers separate raw paths from effective supply."},"raw_group_size":{"type":"integer"},"effective_group_size":{"type":"integer"},"catalog_total":{"type":"integer"},"raw_catalog_total":{"type":"integer"},"effective_catalog_total":{"type":"integer"},"concentration_pct":{"type":["number","null"],"description":"effective_group_size / effective_catalog_total × 100, rounded to 1 decimal."},"wildcard_402_detected":{"type":"boolean"},"spa_fallback_detected":{"type":"boolean"},"effective_count_basis":{"type":["string","null"],"enum":["sitemap_url_count","manifest_resource_count","canonical_homepage",null]},"group_median_price_usdc":{"type":["number","null"]},"group_p90_price_usdc":{"type":["number","null"]},"price_ratio_to_median":{"type":["number","null"],"description":"Current price / group median. ≥10 → price_outlier_high."}}},"risk_score":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"recommended_action":{"type":"string","enum":["pay","skip","use_alternatives","investigate"]},"reason_codes":{"type":"array","items":{"type":"string"}},"observed_at":{"type":"string","format":"date-time"},"evidence":{"type":"object","properties":{"probes_1h":{"type":"integer"},"healthy_1h":{"type":"integer"},"probes_7d":{"type":"integer"},"healthy_7d":{"type":"integer"},"errors_30m":{"type":"integer"},"price_amount_usdc":{"type":["string","null"]},"service_age_hours":{"type":["number","null"]},"concentration_pct":{"type":["number","null"]},"raw_concentration_group_size":{"type":["integer","null"]},"effective_concentration_group_size":{"type":["integer","null"]},"wildcard_402_detected":{"type":"boolean"},"decoy_probability":{"type":"number"}}}}}}}},"400":{"description":"Malformed body — `url` required and must start with http(s)"},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query exceeded statement_timeout before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry after the next probe/cache window.","content":{"application/json":{}}}}}},"/api/v1/catalog/decoys":{"post":{"operationId":"catalogDecoys","summary":"Catalog of x402 endpoints with decoys flagged","description":"Searchable catalog of x402 endpoint risk signals; scam-like decoys, zombies, and price-traps flagged.","x-x402-price":"$0.005","x-price-usdc":0.005,"x-risk-tier":"blacklist","x-agent-use-cases":["Pull hourly into an in-process Set; reject any URL in it before going through preflight.","Cold-cache populator for new agent deployments — establish a baseline blacklist on startup."],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"description":"No parameters. POST with {} or no body."}}}},"responses":{"200":{"description":"Known-bad list (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"generated_at":{"type":"string","format":"date-time"},"counts":{"type":"object","properties":{"total":{"type":"integer"},"by_reason":{"type":"object","additionalProperties":{"type":"integer"}},"wildcard_402_services":{"type":"integer"},"spa_fallback_services":{"type":"integer"}}},"truncated":{"type":"boolean","description":"True if result hit the MAX_ENTRIES cap and was cut off."},"wildcard_402_hosts":{"type":"array","description":"Service-level warning list. These providers return x402 challenges for random non-catalog paths, so raw_count and effective_count are kept separate.","items":{"type":"object","properties":{"service_id":{"type":"string"},"service_name":{"type":"string"},"provider":{"type":["string","null"]},"raw_count":{"type":"integer"},"effective_count":{"type":"integer"},"synthetic_count":{"type":"integer"},"wildcard_402_checked_at":{"type":["string","null"],"format":"date-time"}}}},"spa_fallback_hosts":{"type":"array","description":"Service-level warning list. These providers return 200 HTML shells for random non-catalog paths, so raw_count and effective_count are kept separate."},"entries":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"service_id":{"type":"string"},"service_name":{"type":"string"},"provider":{"type":["string","null"]},"price_usdc":{"type":["string","null"]},"currency":{"type":["string","null"]},"reasons":{"type":"array","items":{"type":"string","enum":["decoy_price_extreme","zombie","dead_7d","mostly_dead"]}},"probes_7d":{"type":"integer"},"healthy_7d":{"type":"integer"},"uptime_7d_pct":{"type":["integer","null"]},"last_probe_at":{"type":["string","null"],"format":"date-time"},"wildcard_402_detected":{"type":"boolean"},"wildcard_402_checked_at":{"type":["string","null"],"format":"date-time"},"spa_fallback_detected":{"type":"boolean"},"spa_fallback_checked_at":{"type":["string","null"],"format":"date-time"}}}}}}}}},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query exceeded statement_timeout before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry after the next probe/cache window.","content":{"application/json":{}}}}}},"/api/v1/alternatives":{"post":{"operationId":"alternatives","summary":"Routing fallback — siblings to a flagged x402 endpoint","description":"Avoid paying unsafe x402 endpoints: ranked safe alternatives for the same capability.","x-x402-price":"$0.005","x-price-usdc":0.005,"x-risk-tier":"routing","x-agent-use-cases":["After preflight returns ok=false — find the closest healthy swap-in (same_service > same_provider > same_domain > same_category > similar_price).","Category-only discovery — pass `taskClass` alone to find endpoints by capability without a starting URL."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://api.venice.ai/api/v1/chat/completions","description":"URL to find alternatives for. x402station looks up the target's service / provider / domain / category / price band and matches siblings against any one of those keys."},"taskClass":{"type":"string","maxLength":80,"description":"Service category hint (e.g. \"llm-completions\"). Used as a fallback match key when `url` is unknown to the catalog, OR by itself when the agent only has a task class in mind."},"limit":{"type":"integer","minimum":1,"maximum":10,"default":5}},"description":"At least one of `url` or `taskClass` is required."}}}},"responses":{"200":{"description":"Alternatives list (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"object","description":"Target endpoint metadata when `url` resolved to a known catalog row. When the URL is unknown, returns `{ url, known: false }`. When only `taskClass` was supplied, returns `{ task_class }`."},"match_strategy":{"type":"string","enum":["url_target","task_class_only","url_target_unknown_fallback"]},"alternatives":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"service":{"type":"string"},"service_id":{"type":"string"},"provider":{"type":["string","null"]},"domain":{"type":["string","null"]},"category":{"type":["string","null"]},"price_usdc":{"type":["string","null"]},"currency":{"type":["string","null"]},"uptime_1h_pct":{"type":["number","null"]},"uptime_7d_pct":{"type":["number","null"]},"avg_latency_1h_ms":{"type":["integer","null"]},"match_reason":{"type":"string","enum":["same_service","same_provider","same_domain","same_category","similar_price"]}}}},"candidate_count":{"type":"integer","description":"Eligible candidates BEFORE the display LIMIT was applied (capped at candidate_search_limit). Lets agents detect 'we returned 5 but there were 200 more'."},"candidate_search_limit":{"type":"integer","description":"Upper bound on the candidate search window; candidate_count is capped at this value."},"reason_no_alternatives":{"type":["string","null"],"description":"When `alternatives` is empty, why: one of target_unknown_and_no_taskClass | no_match_keys_provided | no_healthy_siblings_in_match_set | null."}}}}}},"400":{"description":"Malformed body — at least one of `url` (http(s), <=2048 chars) or `taskClass` (<=80 chars) required; `limit` must be an integer in [1, 10]."},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query exceeded statement_timeout (alternatives 8s) before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry later.","content":{"application/json":{}}}}}},"/api/v1/credits":{"post":{"operationId":"buyCredits","summary":"Prepaid credit pack for preflight / verified","description":"Prepaid credit pack for high-frequency x402 scam checks, preflight, and verified calls.","x-x402-price":"$0.50","x-price-usdc":0.5,"x-risk-tier":"billing","x-agent-use-cases":["High-volume agent crawling >1000 unique URLs/month — halve the per-preflight cost.","Pre-fund a research run so wallet signing latency stays out of the hot path."],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"description":"No parameters. POST with {} or no body."}}}},"responses":{"200":{"description":"Credit bundle issued (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"creditId":{"type":"string","format":"uuid"},"balance":{"type":"integer","description":"Calls remaining (= initialBalance on issue)."},"initialBalance":{"type":"integer"},"paidAmount":{"type":"string","description":"USDC, decimal string."},"payerAddress":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"usage":{"type":"object","description":"Hint object showing the X-Credit-Id header pattern + status URL."}}}}}},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}}}}},"/api/v1/credits/{id}":{"get":{"operationId":"getCreditStatus","summary":"Read a credit's current state (balance, expiry)","description":"Free, no payment required. UUID-only access — anyone holding the creditId can read state. 404 covers both 'malformed UUID' and 'no such credit' so an attacker scraping random UUIDs can't tell them apart.","x-x402-price":"free","x-risk-tier":"billing","x-agent-use-cases":["Check balance + expiry before deciding whether to top up via /api/v1/credits.","Audit point: how many preflights of this bundle have actually been redeemed."],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Credit state","content":{"application/json":{"schema":{"type":"object","properties":{"creditId":{"type":"string","format":"uuid"},"balance":{"type":"integer"},"initialBalance":{"type":"integer"},"used":{"type":"integer","description":"initialBalance - balance"},"paidAmount":{"type":"string"},"payerAddress":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"paymentTx":{"type":["string","null"]},"paymentNetwork":{"type":["string","null"]}}}}}},"404":{"description":"Malformed UUID OR unknown credit (same response body for both)."}}}},"/api/v1/whats-new":{"post":{"operationId":"whatsNew","summary":"Catalog diff polling — what was added / removed since `since`","description":"New/removed x402 resources: discover unknown endpoints, then preflight before PAYMENT-SIGNATURE.","x-x402-price":"$0.001","x-price-usdc":0.001,"x-risk-tier":"catalog","x-agent-use-cases":["Aggregator agents that need a fresh delta of catalog state without re-pulling everything.","Trading-bot operator detecting newly-listed services to scan for arbitrage."],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time","description":"ISO 8601 timestamp. Default = now - 24h. Cannot be older than 30 days or in the future."},"limit":{"type":"integer","minimum":1,"maximum":500,"default":200,"description":"Per-list cap. Applied independently to added_endpoints and removed_endpoints. `truncated` flag indicates the cap was hit AND more rows existed."}}}}}},"responses":{"200":{"description":"Catalog diff (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"window_hours":{"type":"number"},"added_endpoints":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"service_id":{"type":"string"},"service_name":{"type":"string"},"provider":{"type":["string","null"]},"domain":{"type":["string","null"]},"category":{"type":["string","null"]},"price_usdc":{"type":["string","null"]},"currency":{"type":["string","null"]},"first_seen_at":{"type":"string","format":"date-time"}}}},"removed_endpoints":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"service_id":{"type":"string"},"service_name":{"type":"string"},"provider":{"type":["string","null"]},"domain":{"type":["string","null"]},"category":{"type":["string","null"]},"price_usdc":{"type":["string","null"]},"currency":{"type":["string","null"]},"last_seen_at":{"type":"string","format":"date-time"}}}},"summary":{"type":"object","properties":{"added_endpoints_count":{"type":"integer"},"removed_endpoints_count":{"type":"integer"},"added_services_count":{"type":"integer"},"removed_services_count":{"type":"integer"},"polls_in_window":{"type":"integer"},"first_poll_at":{"type":["string","null"],"format":"date-time"},"last_poll_at":{"type":["string","null"],"format":"date-time"},"current_active_endpoints":{"type":"integer"},"current_active_services":{"type":"integer"}}},"truncated":{"type":"boolean"},"limit":{"type":"integer"}}}}}},"400":{"description":"Malformed body — `since` not a valid ISO timestamp / older than 30 days / in the future; `limit` not an integer in [1, 500]."},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB query failed (statement_timeout=5s) before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry later.","content":{"application/json":{}}}}}},"/api/v1/watch":{"post":{"operationId":"watchSubscribe","summary":"Subscribe to webhook alerts on x402 endpoint state changes","description":"Monitor x402 endpoint risk; webhook on scam-like decoy / zombie / price-trap status changes.","x-x402-price":"$0.01","x-price-usdc":0.01,"x-risk-tier":"subscription","x-agent-use-cases":["Long-lived trading agent depending on a single endpoint — get notified the moment it goes zombie or its price flips into decoy territory.","Aggregator that wants alerting on a curated provider set without polling preflight every minute."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","webhookUrl"],"properties":{"url":{"type":"string","format":"uri","description":"The x402 endpoint URL to watch."},"webhookUrl":{"type":"string","format":"uri","description":"Where x402station will POST alert payloads. Must be reachable from the public internet."},"signals":{"type":"array","items":{"type":"string","enum":["unknown_endpoint","no_history","dead","zombie","decoy_price_extreme","suspicious_high_price","slow","new_provider","dead_7d","mostly_dead","slow_p99","price_outlier_high","high_concentration","never_paid_zombie","proxy_markup","wildcard_402","spa_fallback"]},"minItems":1,"maxItems":20,"description":"Optional. Defaults to ['dead', 'zombie', 'decoy_price_extreme']. Whitelisted to known signal vocabulary so a typo doesn't silently never fire."}}}}}},"responses":{"200":{"description":"Subscription created (after successful payment)","content":{"application/json":{"schema":{"type":"object","properties":{"watchId":{"type":"string","format":"uuid"},"secret":{"type":"string","description":"64-char hex HMAC seed. Returned ONCE here. Store it."},"expiresAt":{"type":"string","format":"date-time"},"signals":{"type":"array","items":{"type":"string"}},"alertsPaid":{"type":"integer"},"alertsRemaining":{"type":"integer"},"endpointKnown":{"type":"boolean","description":"true if the watched URL is in our catalog. false ⇒ alerts will fire only after ingest picks the URL up."},"deliveryFormat":{"type":"object","description":"Documents how to verify HMAC signatures + the JSON shape of alert payloads."}},"required":["watchId","secret","expiresAt","signals","alertsPaid"]}}}},"400":{"description":"Bad input (malformed URL, unknown signal, etc.)"},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}},"503":{"description":"DB write timed out (statement_timeout=5s) before x402 settlement finalized. The request returns 503 and the x402 wrapper skips settlement; retry later.","content":{"application/json":{}}}}}},"/api/v1/watch/{watchId}":{"get":{"operationId":"getWatchStatus","x-x402-price":"free","x-risk-tier":"subscription","summary":"Watch subscription status + recent alert history","description":"Returns the current state of a watch (active/expired, alerts remaining, last_state snapshot, last 10 alert deliveries). Free, secret-gated. Pass the secret in header `x-x402station-secret` (preferred) or as `?secret=...` query string. Mismatched secret returns 404 (not 401) so an attacker scraping IDs can't distinguish 'exists with wrong secret' from 'doesn't exist'.","parameters":[{"name":"watchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-x402station-secret","in":"header","required":false,"schema":{"type":"string","minLength":64,"maxLength":64},"description":"64-char hex secret. Either this header or ?secret=… must be set."},{"name":"secret","in":"query","required":false,"schema":{"type":"string","minLength":64,"maxLength":64}}],"responses":{"200":{"description":"Watch state + recent alerts","content":{"application/json":{"schema":{"type":"object","properties":{"watchId":{"type":"string","format":"uuid"},"endpointUrl":{"type":"string"},"webhookUrl":{"type":"string"},"signals":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"alertsPaid":{"type":"integer"},"alertsSent":{"type":"integer"},"alertsRemaining":{"type":"integer"},"lastState":{"type":["object","null"]},"isActive":{"type":"boolean"},"expired":{"type":"boolean"},"recentAlerts":{"type":"array"}}}}}},"400":{"description":"Malformed watchId UUID"},"401":{"description":"Secret missing"},"404":{"description":"Watch not found OR secret mismatched (intentionally indistinguishable)"}}},"delete":{"operationId":"unsubscribeWatch","x-x402-price":"free","x-risk-tier":"subscription","summary":"Unsubscribe (deactivate) a watch","description":"Sets is_active=false. No further alerts are queued or delivered. Free, secret-gated (same auth as GET). Watch row + alert history are retained for audit. There is no refund for unused prepaid alerts.","parameters":[{"name":"watchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-x402station-secret","in":"header","required":false,"schema":{"type":"string","minLength":64,"maxLength":64}},{"name":"secret","in":"query","required":false,"schema":{"type":"string","minLength":64,"maxLength":64}}],"responses":{"200":{"description":"Unsubscribed (or already-unsubscribed)","content":{"application/json":{"schema":{"type":"object","properties":{"watchId":{"type":"string","format":"uuid"},"isActive":{"type":"boolean","const":false},"message":{"type":"string"}}}}}},"400":{"description":"Malformed watchId UUID"},"401":{"description":"Secret missing"},"404":{"description":"Watch not found OR secret mismatched (intentionally indistinguishable)"}}}},"/api/v1/verified":{"post":{"operationId":"verifiedBadge","x-x402-price":"$1.00","x-price-usdc":1,"x-risk-tier":"certification","x-agent-use-cases":["provider-side-marketing","trust-signal-issuance"],"summary":"Signed verification certificate for one x402 endpoint","description":"Verify x402 endpoint before paying: signed certificate with deeper, auditable evidence for agents/policies that need a safety record.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Full URL of the x402 endpoint to audit."},"name":{"type":"string","maxLength":200,"description":"Optional display name for the badge."}}}}}},"responses":{"200":{"description":"Certificate issued (verified=true|false; both paid)","content":{"application/json":{"schema":{"type":"object","properties":{"certId":{"type":"string","format":"uuid"},"verified":{"type":"boolean"},"tier":{"type":"string","enum":["verified","verified_plus","not_verified"]},"url":{"type":"string"},"pattern":{"type":["string","null"]},"covers_child_urls":{"type":"integer","minimum":0},"name":{"type":["string","null"]},"issuedAt":{"type":"string","format":"date-time"},"validUntil":{"type":"string","format":"date-time"},"paidAmount":{"type":"string"},"payerAddress":{"type":["string","null"]},"badgeUrl":{"type":"string","format":"uri"},"pageUrl":{"type":"string","format":"uri"},"jsonUrl":{"type":"string","format":"uri"},"htmlSnippet":{"type":"string"},"reasons_pass":{"type":"array","items":{"type":"string"}},"reasons_fail":{"type":"array","items":{"type":"string"}},"snapshot":{"type":"object"},"idempotentReplay":{"type":"boolean"}}}}}},"400":{"description":"Malformed URL"},"402":{"description":"Payment required — read the x402 v2 PaymentRequiredResponse from the JSON body or the base64 payment-required header, sign PAYMENT-SIGNATURE, and retry.","headers":{"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequiredResponse. Mirrors the JSON response body for header-based clients.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["x402Version","resource","accepts"],"properties":{"x402Version":{"type":"integer","const":2},"error":{"type":"string"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","minItems":1,"items":{"type":"object","required":["scheme","network","asset","amount","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string"},"amount":{"type":"string"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"}}}},"extensions":{"type":"object"}}}}}}}}},"/api/v1/verified/{id}":{"get":{"operationId":"getVerifiedCertificate","x-x402-price":"free","x-risk-tier":"certification","summary":"Read verified certificate + live re-audit","description":"Free read of one certificate. Returns the cert metadata + a fresh audit re-check against current probe + CDP data. Combines `verified` (cert non-expired AND live audit passes) with full pass/fail diagnostic. Designed for any agent that sees a `verified by x402station` badge in a third-party doc — paste this URL to confirm the cert is still valid right now. 404 indistinguishable from any other unknown path (anti-enumeration).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Certificate found + live audit results","content":{"application/json":{"schema":{"type":"object","properties":{"certId":{"type":"string","format":"uuid"},"url":{"type":"string"},"pattern":{"type":["string","null"]},"covers_child_urls":{"type":"integer","minimum":0},"name":{"type":["string","null"]},"tier":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"validUntil":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"verified":{"type":"boolean"},"live_audit":{"type":"object"},"snapshot_at_issuance":{"type":"object"},"payerAddress":{"type":["string","null"]},"paidAmount":{"type":"string"}}}}}},"404":{"description":"Cert not found OR malformed UUID"}}}},"/.well-known/x402":{"get":{"operationId":"getX402Manifest","x-x402-price":"free","x-risk-tier":"discovery","summary":"Service manifest (agent-readable)","description":"Describes all paid endpoints, pricing, and signals in one JSON document.","responses":{"200":{"description":"Manifest JSON","content":{"application/json":{}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","x-x402-price":"free","x-risk-tier":"discovery","summary":"AI-crawler-readable description (markdown by llms.txt convention)","responses":{"200":{"description":"Markdown body — emitted as text/markdown so Cloudflare's isitagentready scanner accepts it via Accept: text/markdown content negotiation.","content":{"text/markdown":{}}}}}}}}