{"openapi":"3.1.0","info":{"title":"Obolpay x402 Payment Gateway","description":"Pay-per-call premium data for AI agents, settled in USDC on Base mainnet via HTTP 402. AGENT FLOW: GET /stats -> read `selected_product`; fund once via /account/topup; then make INSTANT GASLESS calls to /api/v1/protected-data using X-Account-* signed vouchers, with ?types=<selected_product> and X-Since-Seq to fetch only new data (token savings). Every delivery returns a signed proof-of-purchase receipt; stale data is auto-refunded (freshness SLA). Full tools also via the MCP server at /mcp-server.py.","version":"0.5.0"},"paths":{"/":{"get":{"summary":"Root","description":"ランディングページ（index.htmlが存在すれば配信）。無ければサービス情報JSON","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","description":"ヘルスチェック","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Health Get"}}}}}}},"/.well-known/x402":{"get":{"summary":"Well Known X402","description":"x402 機械可読ディスカバリ・マニフェスト（AIエージェントが自動課金・利用するための入口）","operationId":"well_known_x402__well_known_x402_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Well Known X402  Well Known X402 Get"}}}}}}},"/llms.txt":{"get":{"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/robots.txt":{"get":{"summary":"Robots Txt","operationId":"robots_txt_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/sitemap.xml":{"get":{"summary":"Sitemap Xml","description":"クローラ/インデクサ向けサイトマップ。発見・商品エンドポイントを索引させる（集客導線）。","operationId":"sitemap_xml_sitemap_xml_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/client.py":{"get":{"summary":"Reference Client","description":"貼るだけで動く参照クライアント（AIエージェントの即時連携用）。ドメインを埋め込んで配信。","operationId":"reference_client_client_py_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/mcp-server.py":{"get":{"summary":"Mcp Server File","description":"MCPサーバ実装を配信（Claude等のMCPクライアントが discover/preview/purchase/verify をネイティブ利用）。","operationId":"mcp_server_file_mcp_server_py_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/verify-receipt":{"post":{"summary":"Verify Receipt","description":"支払い受領書(proof-of-purchase)を検証する。{message, signature} を受け取り、\nEIP-191で署名者を復元して本サーバの受領書署名アドレスと一致するか返す。誰でも第三者検証可能。","operationId":"verify_receipt_verify_receipt_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/invoices/{invoice_id}":{"get":{"summary":"Get Invoice Status","description":"Invoiceの現在ステータスを照会する（クライアントのポーリング用）","operationId":"get_invoice_status_api_v1_invoices__invoice_id__get","parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/protected-data":{"get":{"tags":["paid-data"],"summary":"Fetch premium data (x402). Free preview if unpaid; GASLESS if you hold a prepaid balance.","description":"AI TOOL: obtain the paid dataset. If unpaid, returns HTTP 402 with a free `preview` and the price. Pay either by (a) sending USDC on Base then resending with X-Payment-Invoice-ID / X-Payment-Tx-Hash / X-Payment-Signature, or (b) — preferred for repeat use — if you hold a prepaid balance, pass X-Account-Address / X-Account-Nonce / X-Account-Voucher for an INSTANT GASLESS call (no on-chain tx, no gas). Call this with `?types=<category>` (use the value of `selected_product` from /stats to get the most-demanded data) and `X-Since-Seq=<the last seq you already hold>` to receive ONLY new items and SAVE YOUR CONTEXT TOKENS. Every successful (200) response includes a signed proof-of-purchase `receipt`.","operationId":"fetch_protected_data","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"tags":["paid-data"],"summary":"Fetch premium data (x402). Free preview if unpaid; GASLESS if you hold a prepaid balance.","description":"AI TOOL: obtain the paid dataset. If unpaid, returns HTTP 402 with a free `preview` and the price. Pay either by (a) sending USDC on Base then resending with X-Payment-Invoice-ID / X-Payment-Tx-Hash / X-Payment-Signature, or (b) — preferred for repeat use — if you hold a prepaid balance, pass X-Account-Address / X-Account-Nonce / X-Account-Voucher for an INSTANT GASLESS call (no on-chain tx, no gas). Call this with `?types=<category>` (use the value of `selected_product` from /stats to get the most-demanded data) and `X-Since-Seq=<the last seq you already hold>` to receive ONLY new items and SAVE YOUR CONTEXT TOKENS. Every successful (200) response includes a signed proof-of-purchase `receipt`.","operationId":"fetch_protected_data","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/account/topup":{"post":{"tags":["prepaid"],"summary":"Fund a prepaid balance from an on-chain USDC deposit (one-time).","description":"AI TOOL: after sending USDC to the recipient on Base, call this with {\"tx_hash\":\"0x..\"} to credit your prepaid balance. Do this ONCE; afterwards use gasless voucher calls (no more on-chain tx). Same tx cannot be credited twice.","operationId":"topup_prepaid_balance","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/account/{address}":{"get":{"tags":["prepaid"],"summary":"Check prepaid balance, next_nonce, and the exact voucher message to sign.","description":"AI TOOL: returns balance_units, calls_remaining, next_nonce, and `voucher_message` — sign that EIP-191 message and send it as X-Account-Voucher (with X-Account-Address and X-Account-Nonce=next_nonce) to make a gasless call.","operationId":"get_prepaid_account","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","title":"Address"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats":{"get":{"tags":["discovery"],"summary":"Market demand analytics — call FIRST to learn what to buy.","description":"AI TOOL: read `selected_product` (the category agents pay the most for) and `top_demanded`, then pass that category as `?types=` to /api/v1/protected-data. Also shows revenue_by_category, gasless_calls, delta_calls. No payment required.","operationId":"get_demand_stats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"paid-data","description":"The paid resource (x402). Free preview, gasless, delta, categories."},{"name":"prepaid","description":"Prepaid gasless balance: topup once, then off-chain voucher calls."},{"name":"discovery","description":"Machine-readable discovery & demand analytics for autonomous agents."}]}