{"openapi":"3.1.0","info":{"title":"PricePilot402 Provisional x402 Paid API","version":"2.1.0","description":"Machine-readable discovery contract for PricePilot402 live x402 resources. Full public Phase 1 remains locked until release gates pass; currently live routes are capped provisional paid routes.","x-guidance":"Use the listed routes to discover PricePilot402's live x402 payment metadata. PHASE1_PAID_API_ENABLED remains false; provisional caps and route allowlist control the live surface.","x-phase1-paid-api-enabled":false,"x-phase1-provisional-paid-api-enabled":true,"x-live-route-count":4},"servers":[{"url":"https://pricepilot402.pricepilot402-arya.workers.dev"}],"externalDocs":{"description":"Public x402 buyer example","url":"https://pricepilot402.pricepilot402-arya.workers.dev/examples/x402-buyer"},"paths":{"/v1/market/hot-categories":{"get":{"operationId":"pricepilotHotCategories","summary":"Find active x402 categories with payer density","description":"Find active x402 categories with payer density. Requires an x402 payment unless the response is a 402 challenge.","tags":["x402","pricepilot402","hot-categories"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xD8b028757631Af0F42b38f7a4E638ACebe764187"}}],"provisional":true},"responses":{"200":{"description":"Paid x402 response","content":{"application/json":{"schema":{"type":"object","properties":{"benchmark_id":{"type":"string"},"payment":{"type":"object"},"confidence_rating":{"type":"string"},"source_trail":{"type":"array","items":{"type":"object"}},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"why_hot":{"type":"string"},"category_density_score":{"type":"number"},"comparable_endpoint_cluster":{"type":"object"},"price_dispersion":{"type":"object","properties":{"p10":{"type":["number","null"]},"p25":{"type":["number","null"]},"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"spread":{"type":["number","null"]}}},"price_percentile":{"type":["number","null"]},"category_price_percentile":{"type":["number","null"]},"payer_density":{"type":"object"},"call_density":{"type":"object"},"visible_gmv_estimate":{"type":"object"},"underpriced_overpriced_score":{"type":["number","null"]},"opportunity_flags":{"type":"array","items":{"type":"string"}},"suggested_test_price_band":{"type":"object"},"confidence_explanation":{"type":"string"},"seller_entity_mapping":{"type":"object"},"endpoint_survival_activity_trend":{"type":"object"},"benchmark_summary":{"type":"string"},"decision_notes":{"type":"array","items":{"type":"string"}},"recommended_followup_route":{"type":"object"}}}}}},"examples":{"hotCategoriesPaid":{"summary":"Paid hot categories benchmark","value":{"benchmark_id":"benchmark_example","payment":{"status":"settled","amount_usd":0.02,"route":"/v1/market/hot-categories"},"confidence_rating":"high","source_trail":[{"source_url":"https://public-source.example/listing","observed_at":"2026-07-02T10:00:00.000Z"}],"categories":[{"category":"web-search","why_hot":"web-search is hot because visible payer and GMV samples are high.","category_density_score":82.5,"comparable_endpoint_cluster":{"category":"web-search","sample_size":4,"active_endpoint_count":4},"price_dispersion":{"p10":0.01,"p25":0.02,"p50":0.03,"p75":0.05,"p90":0.08,"spread":0.07},"price_percentile":null,"category_price_percentile":null,"payer_density":{"median":30,"top_decile":60,"percentile":null},"call_density":{"median":1000,"top_decile":2000,"percentile":null},"visible_gmv_estimate":{"low":175.2,"mid":219,"high":262.8,"cluster_mid":219,"target_mid":null},"underpriced_overpriced_score":null,"opportunity_flags":["visible_payer_sample","visible_gmv_sample"],"suggested_test_price_band":{"low":0.02,"mid":0.03,"high":0.05,"status":"derived_from_category_price_distribution"},"confidence_explanation":"high confidence from public observations; estimates are directional.","seller_entity_mapping":{"seller_count":4,"summary":"4 seller labels across 4 active endpoints."},"endpoint_survival_activity_trend":{"status":"needs_more_history","latest_observed_at":"2026-07-02T10:00:00.000Z"},"benchmark_summary":"Decision-grade x402 benchmark summary derived from public observations.","decision_notes":["price position is derived from observed category comparables.","payer density uses visible public samples."],"recommended_followup_route":{"method":"POST","path":"/v1/benchmark/category","input":{"category":"web-search"}}}]}}}}}},"402":{"description":"Payment Required with PAYMENT-REQUIRED header"},"409":{"description":"Payment replay rejected"},"423":{"description":"Route locked by Phase 1 or provisional cap policy"},"429":{"description":"Provisional daily paid request cap reached"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}]}},"/v1/market/top-gmv":{"get":{"operationId":"pricepilotTopGmv","summary":"Estimate visible GMV for x402 endpoints. Rank Base USDC x402 API categories by market activity","description":"Estimate visible GMV for x402 endpoints. Rank Base USDC x402 API categories by market activity. Requires an x402 payment unless the response is a 402 challenge.","tags":["x402","pricepilot402","top-gmv"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xD8b028757631Af0F42b38f7a4E638ACebe764187"}}],"provisional":true},"responses":{"200":{"description":"Paid x402 response","content":{"application/json":{"schema":{"type":"object","properties":{"benchmark_id":{"type":"string"},"payment":{"type":"object"},"confidence_rating":{"type":"string"},"source_trail":{"type":"array","items":{"type":"object"}},"endpoints":{"type":"array","items":{"type":"object","properties":{"endpoint_url":{"type":"string","format":"uri"},"gmv_rank_explanation":{"type":"string"},"comparable_endpoint_cluster":{"type":"object"},"price_dispersion":{"type":"object","properties":{"p10":{"type":["number","null"]},"p25":{"type":["number","null"]},"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"spread":{"type":["number","null"]}}},"price_percentile":{"type":["number","null"]},"category_price_percentile":{"type":["number","null"]},"payer_density":{"type":"object"},"call_density":{"type":"object"},"visible_gmv_estimate":{"type":"object"},"underpriced_overpriced_score":{"type":["number","null"]},"opportunity_flags":{"type":"array","items":{"type":"string"}},"suggested_test_price_band":{"type":"object"},"confidence_explanation":{"type":"string"},"seller_entity_mapping":{"type":"object"},"endpoint_survival_activity_trend":{"type":"object"},"benchmark_summary":{"type":"string"},"decision_notes":{"type":"array","items":{"type":"string"}},"recommended_followup_route":{"type":"object"}}}}}},"examples":{"topGmvPaid":{"summary":"Paid top GMV endpoint benchmark","value":{"benchmark_id":"benchmark_example","payment":{"status":"settled","amount_usd":0.05,"route":"/v1/market/top-gmv"},"confidence_rating":"high","source_trail":[{"source_url":"https://public-source.example/listing","observed_at":"2026-07-02T10:00:00.000Z"}],"endpoints":[{"endpoint_url":"https://api.example.com/search","gmv_rank_explanation":"This endpoint ranks by visible GMV estimate.","comparable_endpoint_cluster":{"category":"web-search","sample_size":4,"active_endpoint_count":4},"price_dispersion":{"p10":0.01,"p25":0.02,"p50":0.03,"p75":0.05,"p90":0.08,"spread":0.07},"price_percentile":62.5,"category_price_percentile":62.5,"payer_density":{"median":30,"top_decile":60,"percentile":75},"call_density":{"median":1000,"top_decile":2000,"percentile":75},"visible_gmv_estimate":{"low":175.2,"mid":219,"high":262.8,"cluster_mid":219,"target_mid":160},"underpriced_overpriced_score":1.666667,"opportunity_flags":["visible_payer_sample","visible_gmv_sample"],"suggested_test_price_band":{"low":0.02,"mid":0.03,"high":0.05,"status":"derived_from_category_price_distribution"},"confidence_explanation":"high confidence from public observations; estimates are directional.","seller_entity_mapping":{"seller_count":4,"summary":"4 seller labels across 4 active endpoints."},"endpoint_survival_activity_trend":{"status":"needs_more_history","latest_observed_at":"2026-07-02T10:00:00.000Z"},"benchmark_summary":"Decision-grade x402 benchmark summary derived from public observations.","decision_notes":["price position is derived from observed category comparables.","payer density uses visible public samples."],"recommended_followup_route":{"method":"POST","path":"/v1/benchmark/category","input":{"category":"web-search"}}}]}}}}}},"402":{"description":"Payment Required with PAYMENT-REQUIRED header"},"409":{"description":"Payment replay rejected"},"423":{"description":"Route locked by Phase 1 or provisional cap policy"},"429":{"description":"Provisional daily paid request cap reached"}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}]}},"/v1/benchmark/category":{"post":{"operationId":"pricepilotCategory","summary":"Compare paid MCP tool endpoint prices by category","description":"Compare paid MCP tool endpoint prices by category. Requires an x402 payment unless the response is a 402 challenge.","tags":["x402","pricepilot402","category"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.02"},"protocols":[{"x402":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xD8b028757631Af0F42b38f7a4E638ACebe764187"}}],"provisional":true},"responses":{"200":{"description":"Paid x402 response","content":{"application/json":{"schema":{"type":"object","properties":{"benchmark_id":{"type":"string"},"payment":{"type":"object"},"confidence_rating":{"type":"string"},"source_trail":{"type":"array","items":{"type":"object"}},"benchmark":{"type":"object","properties":{"comparable_endpoint_cluster":{"type":"object"},"price_dispersion":{"type":"object","properties":{"p10":{"type":["number","null"]},"p25":{"type":["number","null"]},"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"spread":{"type":["number","null"]}}},"price_percentile":{"type":["number","null"]},"category_price_percentile":{"type":["number","null"]},"payer_density":{"type":"object"},"call_density":{"type":"object"},"visible_gmv_estimate":{"type":"object"},"underpriced_overpriced_score":{"type":["number","null"]},"opportunity_flags":{"type":"array","items":{"type":"string"}},"suggested_test_price_band":{"type":"object"},"confidence_explanation":{"type":"string"},"seller_entity_mapping":{"type":"object"},"endpoint_survival_activity_trend":{"type":"object"},"benchmark_summary":{"type":"string"},"decision_notes":{"type":"array","items":{"type":"string"}},"recommended_followup_route":{"type":"object"}}}}},"examples":{"paidBenchmark":{"summary":"Paid benchmark response","value":{"benchmark_id":"benchmark_example","payment":{"status":"settled","amount_usd":0.02,"route":"/v1/benchmark/category"},"confidence_rating":"high","source_trail":[{"source_url":"https://public-source.example/listing","observed_at":"2026-07-02T10:00:00.000Z"}],"benchmark":{"comparable_endpoint_cluster":{"category":"web-search","sample_size":4,"active_endpoint_count":4},"price_dispersion":{"p10":0.01,"p25":0.02,"p50":0.03,"p75":0.05,"p90":0.08,"spread":0.07},"price_percentile":null,"category_price_percentile":null,"payer_density":{"median":30,"top_decile":60,"percentile":null},"call_density":{"median":1000,"top_decile":2000,"percentile":null},"visible_gmv_estimate":{"low":175.2,"mid":219,"high":262.8,"cluster_mid":219,"target_mid":null},"underpriced_overpriced_score":null,"opportunity_flags":["visible_payer_sample","visible_gmv_sample"],"suggested_test_price_band":{"low":0.02,"mid":0.03,"high":0.05,"status":"derived_from_category_price_distribution"},"confidence_explanation":"high confidence from public observations; estimates are directional.","seller_entity_mapping":{"seller_count":4,"summary":"4 seller labels across 4 active endpoints."},"endpoint_survival_activity_trend":{"status":"needs_more_history","latest_observed_at":"2026-07-02T10:00:00.000Z"},"benchmark_summary":"Decision-grade x402 benchmark summary derived from public observations.","decision_notes":["price position is derived from observed category comparables.","payer density uses visible public samples."],"recommended_followup_route":{"method":"POST","path":"/v1/benchmark/category","input":{"category":"web-search"}}}}}}}}},"402":{"description":"Payment Required with PAYMENT-REQUIRED header"},"409":{"description":"Payment replay rejected"},"423":{"description":"Route locked by Phase 1 or provisional cap policy"},"429":{"description":"Provisional daily paid request cap reached"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category"],"additionalProperties":false,"properties":{"category":{"type":"string","examples":["web-search"]},"network":{"type":"string","examples":["eip155:8453"]}}},"examples":{"webSearch":{"summary":"Benchmark a category","value":{"category":"web-search","network":"eip155:8453"}}}}}}}},"/v1/benchmark/endpoint":{"post":{"operationId":"pricepilotEndpoint","summary":"Get x402 market price benchmarks for data APIs","description":"Get x402 market price benchmarks for data APIs. Requires an x402 payment unless the response is a 402 challenge.","tags":["x402","pricepilot402","endpoint"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{"network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0xD8b028757631Af0F42b38f7a4E638ACebe764187"}}],"provisional":true},"responses":{"200":{"description":"Paid x402 response","content":{"application/json":{"schema":{"type":"object","properties":{"benchmark_id":{"type":"string"},"payment":{"type":"object"},"confidence_rating":{"type":"string"},"source_trail":{"type":"array","items":{"type":"object"}},"benchmark":{"type":"object","properties":{"comparable_endpoint_cluster":{"type":"object"},"price_dispersion":{"type":"object","properties":{"p10":{"type":["number","null"]},"p25":{"type":["number","null"]},"p50":{"type":["number","null"]},"p75":{"type":["number","null"]},"p90":{"type":["number","null"]},"spread":{"type":["number","null"]}}},"price_percentile":{"type":["number","null"]},"category_price_percentile":{"type":["number","null"]},"payer_density":{"type":"object"},"call_density":{"type":"object"},"visible_gmv_estimate":{"type":"object"},"underpriced_overpriced_score":{"type":["number","null"]},"opportunity_flags":{"type":"array","items":{"type":"string"}},"suggested_test_price_band":{"type":"object"},"confidence_explanation":{"type":"string"},"seller_entity_mapping":{"type":"object"},"endpoint_survival_activity_trend":{"type":"object"},"benchmark_summary":{"type":"string"},"decision_notes":{"type":"array","items":{"type":"string"}},"recommended_followup_route":{"type":"object"}}}}},"examples":{"paidBenchmark":{"summary":"Paid benchmark response","value":{"benchmark_id":"benchmark_example","payment":{"status":"settled","amount_usd":0.05,"route":"/v1/benchmark/endpoint"},"confidence_rating":"high","source_trail":[{"source_url":"https://public-source.example/listing","observed_at":"2026-07-02T10:00:00.000Z"}],"benchmark":{"comparable_endpoint_cluster":{"category":"web-search","sample_size":4,"active_endpoint_count":4},"price_dispersion":{"p10":0.01,"p25":0.02,"p50":0.03,"p75":0.05,"p90":0.08,"spread":0.07},"price_percentile":62.5,"category_price_percentile":62.5,"payer_density":{"median":30,"top_decile":60,"percentile":75},"call_density":{"median":1000,"top_decile":2000,"percentile":75},"visible_gmv_estimate":{"low":175.2,"mid":219,"high":262.8,"cluster_mid":219,"target_mid":160},"underpriced_overpriced_score":1.666667,"opportunity_flags":["visible_payer_sample","visible_gmv_sample"],"suggested_test_price_band":{"low":0.02,"mid":0.03,"high":0.05,"status":"derived_from_category_price_distribution"},"confidence_explanation":"high confidence from public observations; estimates are directional.","seller_entity_mapping":{"seller_count":4,"summary":"4 seller labels across 4 active endpoints."},"endpoint_survival_activity_trend":{"status":"needs_more_history","latest_observed_at":"2026-07-02T10:00:00.000Z"},"benchmark_summary":"Decision-grade x402 benchmark summary derived from public observations.","decision_notes":["price position is derived from observed category comparables.","payer density uses visible public samples."],"recommended_followup_route":{"method":"POST","path":"/v1/benchmark/category","input":{"category":"web-search"}}}}}}}}},"402":{"description":"Payment Required with PAYMENT-REQUIRED header"},"409":{"description":"Payment replay rejected"},"423":{"description":"Route locked by Phase 1 or provisional cap policy"},"429":{"description":"Provisional daily paid request cap reached"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["endpoint_url"],"additionalProperties":false,"properties":{"endpoint_url":{"type":"string","format":"uri","examples":["https://api.exa.ai/search"]},"category_hint":{"type":"string","examples":["web-search"]}}},"examples":{"endpoint":{"summary":"Benchmark an endpoint","value":{"endpoint_url":"https://api.exa.ai/search","category_hint":"web-search"}}}}}}}}}}