{"openapi":"3.1.0","info":{"title":"Vokko","version":"0.1.9","description":"Cached host lookup is free. Live refresh is paid (Vokko Pro or x402 on eip155:8453). Host reports include paymentRails. payable is true only after a parsed challenge. Changes: last 5 summaries free, full history for a subscriber of that origin. find_payable is evidence, not a rank. When cache.callabilityStale is true, pay a refresh route."},"tags":[{"name":"paid","description":"x402 USDC on Base (eip155:8453). Full refresh $0.02. One protocol $0.005. Batch $0.01 + $0.002 × N."}],"paths":{"/api/v1/hosts/{domain}":{"get":{"operationId":"lookupHost","summary":"Cached host report","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Free cached host report. Does not 402. Always includes cache (presenceStale, callabilityStale, presenceMaxAgeSec, callabilityMaxAgeSec) and refresh (payable, priceUsd, network, rest GET /api/v1/hosts/{domain}/refresh, mcp tool refresh_host at /api/v1/mcp, docs). Live data is the refresh route.","content":{"application/json":{"schema":{"type":"object","required":["cache","refresh"],"properties":{"probedAt":{"type":"string","format":"date-time"},"cache":{"type":"object","required":["presenceMaxAgeSec","callabilityMaxAgeSec","presenceStale","callabilityStale"],"properties":{"presenceMaxAgeSec":{"type":"integer","const":86400},"callabilityMaxAgeSec":{"type":"integer","const":900},"presenceStale":{"type":"boolean"},"callabilityStale":{"type":"boolean"}}},"refresh":{"type":"object","required":["payable","priceUsd","network","rest","mcp","docs"],"properties":{"payable":{"type":"boolean","const":true},"priceUsd":{"type":"number","description":"USDC. Same as GET /refresh. Default 0.02."},"network":{"type":"string","description":"CAIP-2. Default eip155:8453 (Base)."},"rest":{"type":"object","required":["method","url"],"properties":{"method":{"type":"string","const":"GET"},"url":{"type":"string"}}},"mcp":{"type":"object","required":["tool","path"],"properties":{"tool":{"type":"string","const":"refresh_host"},"path":{"type":"string","const":"/api/v1/mcp"}}},"docs":{"type":"string"}}}}}}}}}}},"/api/v1/hosts/{domain}/refresh":{"get":{"operationId":"refreshHost","tags":["paid"],"summary":"Paid live re-probe","description":"$0.02 USDC on eip155:8453 (Base). ?refresh=1 on GET /api/v1/hosts/{domain} is the same paywall. 402 body includes x402Version and accepts.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Fresh host report"},"402":{"description":"Payment required. Body includes x402Version and accepts."}}}},"/api/v1/hosts/{domain}/changes":{"get":{"operationId":"listChanges","summary":"Capability drift, newest first","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Change summaries or full events"}}}},"/api/v1/hosts/{domain}/protocols/{protocol}/refresh":{"get":{"operationId":"refreshHostProtocol","tags":["paid"],"summary":"Paid live probe of one protocol ($0.005 USDC on Base)","description":"$0.005 USDC on eip155:8453 (Base). protocol is a detector id (ucp, acp, ap2, tap, mcp, a2a, x402, mpp, llms, ai-plugin, openapi). Unknown protocol is 400. Full-host refresh stays $0.02. Response is that protocol's capability cell only.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Protocol cell: domain, protocol, probedAt, cell"},"400":{"description":"Unknown protocol"},"402":{"description":"Payment required at $0.005. Body includes x402Version, accepts, and payTo."}}}},"/api/v1/hosts/refresh":{"post":{"operationId":"refreshHostsBatch","tags":["paid"],"summary":"Paid batch live re-probe ($0.01 + $0.002 × N USDC on Base)","description":"$0.01 + $0.002 × N USDC on eip155:8453 (Base). Body { domains: string[], mode: \"full\" }. Cap 10. One 402 for the batch price. Probe failures are per-item errors.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains","mode"],"properties":{"domains":{"type":"array","maxItems":10,"items":{"type":"string"}},"mode":{"type":"string","const":"full"}}}}}},"responses":{"200":{"description":"mode, priceUsd, and results[] of per-host summaries or errors"},"400":{"description":"Over cap, empty domains, or mode is not full"},"402":{"description":"Single payment required for $0.01 + $0.002 × N. Body includes x402Version and accepts."}}}},"/api/v1/mcp":{"post":{"operationId":"mcp","tags":["paid"],"summary":"MCP JSON-RPC tools for lookup_host, refresh_host, refresh_host_protocol, refresh_hosts_batch, pay_preflight, endpoint_health, payto_check, and verify_receipt","description":"lookup_host, participation_check, list_changes, and find_payable are free. On eip155:8453 (Base): refresh_host is $0.02 USDC, refresh_host_protocol is $0.005 USDC, refresh_hosts_batch is $0.01 + $0.002 × N USDC, pay_preflight is $0.001 USDC, endpoint_health is $0.001 USDC, payto_check is $0.002 USDC, verify_receipt is $0.001 USDC. Unpaid paid tools return 402 with x402Version and accepts.","responses":{"200":{"description":"JSON-RPC result"},"402":{"description":"Unpaid paid tool. refresh_host is $0.02. refresh_host_protocol is $0.005. refresh_hosts_batch is $0.01 + $0.002 × N. pay_preflight is $0.001. endpoint_health is $0.001. payto_check is $0.002. verify_receipt is $0.001. Body includes x402Version and accepts."}}}},"/api/v1/hosts/{domain}/pay-preflight":{"get":{"tags":["paid"],"operationId":"pay_preflight","summary":"Can an agent pay at this host? Rails, endpoint, price, freshness.","description":"Can an agent pay at this host? Rails, endpoint, price, freshness. $0.001 USDC on eip155:8453 (Base).","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"intent","in":"query","required":false,"schema":{"type":"string","enum":["checkout","api","any"]}}],"responses":{"200":{"description":"Paid JSON envelope"},"400":{"description":"Invalid input. Returned before the payment gate."},"402":{"description":"Payment required. Body includes sku, priceUsd, x402Version, and accepts."},"429":{"description":"Rate limit. Returned before the payment gate."}},"x-x402":{"priceUsd":0.001,"network":"eip155:8453","asset":"USDC","mcpTool":"pay_preflight"}}},"/api/v1/endpoints/health":{"get":{"tags":["paid"],"operationId":"endpoint_health","summary":"Is this paid API up, and what does it charge right now?","description":"Is this paid API up, and what does it charge right now? $0.001 USDC on eip155:8453 (Base).","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"}},{"name":"method","in":"query","required":false,"schema":{"type":"string","enum":["GET","POST"]}}],"responses":{"200":{"description":"Paid JSON envelope"},"400":{"description":"Invalid input. Returned before the payment gate."},"402":{"description":"Payment required. Body includes sku, priceUsd, x402Version, and accepts."},"429":{"description":"Rate limit. Returned before the payment gate."}},"x-x402":{"priceUsd":0.001,"network":"eip155:8453","asset":"USDC","mcpTool":"endpoint_health"}}},"/api/v1/hosts/{domain}/payto-check":{"get":{"tags":["paid"],"operationId":"payto_check","summary":"Does this payTo address belong to the domain? Evidence, not a guarantee.","description":"Does this payTo address belong to the domain? Evidence, not a guarantee. $0.002 USDC on eip155:8453 (Base).","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["eip155:8453"]}}],"responses":{"200":{"description":"Paid JSON envelope"},"400":{"description":"Invalid input. Returned before the payment gate."},"402":{"description":"Payment required. Body includes sku, priceUsd, x402Version, and accepts."},"429":{"description":"Rate limit. Returned before the payment gate."}},"x-x402":{"priceUsd":0.002,"network":"eip155:8453","asset":"USDC","mcpTool":"payto_check"}}},"/api/v1/receipts/{tx}/verify":{"get":{"tags":["paid"],"operationId":"verify_receipt","summary":"Did this USDC transfer settle to the expected address and amount?","description":"Did this USDC transfer settle to the expected address and amount? $0.001 USDC on eip155:8453 (Base).","parameters":[{"name":"tx","in":"path","required":true,"schema":{"type":"string"},"description":"Transaction hash"},{"name":"payTo","in":"query","required":true,"description":"Expected recipient address","schema":{"type":"string"}},{"name":"network","in":"query","required":false,"description":"CAIP-2. Default eip155:8453 (Base).","schema":{"type":"string","enum":["eip155:8453","eip155:84532"]}},{"name":"asset","in":"query","required":false,"description":"USDC or the USDC contract address for the network. Default USDC.","schema":{"type":"string"}},{"name":"amount","in":"query","required":false,"description":"Atomic USDC amount. Exactly one of amount or amountUsd is required.","schema":{"type":"string"}},{"name":"amountUsd","in":"query","required":false,"description":"USDC decimal amount. Exactly one of amount or amountUsd is required.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paid JSON envelope. data.verdict and data.finality report settlement.","content":{"application/json":{"schema":{"type":"object","required":["sku","data"],"properties":{"sku":{"type":"string","const":"receipt_verify"},"data":{"type":"object","nullable":true,"required":["verdict","finality"],"properties":{"verdict":{"type":"string","enum":["settled","mismatch","reverted","pending","not_found","truncated","unavailable"]},"finality":{"type":["string","null"],"enum":["unconfirmed","confirmed","finalized",null]},"final":{"type":"boolean"},"txHash":{"type":"string"},"network":{"type":"string"}}}}}}}},"400":{"description":"Invalid input. Returned before the payment gate.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required. Body includes sku, priceUsd, x402Version, and accepts.","content":{"application/json":{"schema":{"type":"object","required":["error","sku","priceUsd"],"properties":{"error":{"type":"string"},"sku":{"type":"string","const":"receipt_verify"},"priceUsd":{"type":"number","const":0.001},"x402Version":{"type":"integer"},"accepts":{"type":"array","items":{"type":"object"}}}}}}},"429":{"description":"Rate limit. Returned before the payment gate."}},"x-x402":{"priceUsd":0.001,"network":"eip155:8453","asset":"USDC","mcpTool":"verify_receipt"}}}}}