{"openapi":"3.1.0","info":{"title":"Pickr","version":"1.0.0","description":"Quality-first index for x402 APIs. Every endpoint is rated 0–5 by LLM and ranked by quality, latency, and availability. Send a natural language intent, Pickr routes to the best-rated match, handles the USDC micropayment, and returns the data. Requires a USDC-funded wallet on Base — no API key needed.","x-guidance":"# Pickr API\n\n> Quality-first index for x402 micropayment APIs. Every endpoint rated by LLM. Best one routed to your intent. $0.01 USDC per search, intent routing priced at upstream cost.\n\n## Endpoints\n\n### GET /search — Semantic endpoint discovery ($0.01 fixed)\n\nSend a natural language query. Pickr returns a scored, ranked list of x402 API endpoints matching your intent — with price, latency, input schema, and description. Useful when you want to choose and call an endpoint directly.\n\n### GET /intent — AI-routed data fetch (upstream price)\n\nSend a natural language intent. Pickr selects the best matching x402 endpoint, generates parameters, executes the payment, and returns the data. The 402 response tells you the exact upstream price before you commit.\n\n## Payment Flow (x402)\n\nBoth endpoints follow the x402 protocol:\n\n1. Call without PAYMENT-SIGNATURE header → receive 402 with PAYMENT-REQUIRED header (base64 JSON: price, asset, payTo).\n2. Sign a USDC transferWithAuthorization on Base, base64-encode the payload, re-send with PAYMENT-SIGNATURE header.\n3. Receive 200 with data and PAYMENT-RESPONSE header (base64 settlement receipt).\n\n## Retrying on 402 after payment\n\nIf you re-send the request *with* a valid PAYMENT-SIGNATURE and still receive a 402, this is expected — it means the upstream Pickr selected for you rejected the payment, errored, or is unreachable, and Pickr has already advanced to the next-best matching upstream. **Just call the endpoint again with a fresh payment for the new amount/payTo in the new 402.** Repeat up to 5 times; if you keep getting 402, no working upstream exists for this intent. Do not retry on other status codes (4xx/5xx) — surface those errors directly.\n\n## Network\n\n- Chain: Base (eip155:8453)\n- Asset: USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\n- Facilitator: https://facilitator.payai.network","contact":{"url":"https://x.com/0xr4re"}},"servers":[{"url":"https://pickr.market","description":"Production"}],"tags":[{"name":"x402","description":"Endpoints gated by the x402 micropayment protocol.","externalDocs":{"description":"x402 specification","url":"https://x402.org"}}],"paths":{"/intent":{"get":{"operationId":"intent","summary":"Intent-to-data (AI-routed)","description":"Send a plain-English intent. Pickr selects the best matching x402 API endpoint, generates the required parameters, and relays the response.","tags":["x402"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.0001","max":"5.00","note":"Priced at upstream endpoint cost. Phase 1 returns the exact amount."},"protocols":[{"x402":{}}]},"parameters":[{"name":"intent","in":"query","required":true,"description":"Natural language description of the data you want.","schema":{"type":"string","minLength":1,"maxLength":1000,"example":"What is the current ETH price in USD?"}}],"responses":{"200":{"description":"Upstream data returned successfully.","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded settlement receipt.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","source"],"properties":{"data":{"description":"The upstream API response payload."},"source":{"type":"string","format":"uri","description":"URL of the upstream API endpoint that fulfilled the request.","example":"https://api.example.com/v1/price/eth"}}}}}},"402":{"description":"Payment Required"},"404":{"description":"No x402 endpoint found for this intent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Intent is too ambiguous to route — try rephrasing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"All matching upstream endpoints are currently unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"search","summary":"Semantic endpoint search","description":"Returns a scored, ranked list of x402 API endpoints that best match the intent — with price, latency, input schema, and description. Flat $0.01 USDC per query.","tags":["x402"],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"parameters":[{"name":"intent","in":"query","required":true,"description":"Natural language description of the data you need.","schema":{"type":"string","minLength":1,"maxLength":1000,"example":"ETH price in USD"}}],"responses":{"200":{"description":"Ranked list of matching endpoints.","headers":{"PAYMENT-RESPONSE":{"description":"Base64-encoded settlement receipt.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["intent","results"],"properties":{"intent":{"type":"string","description":"The original intent string."},"results":{"type":"array","items":{"$ref":"#/components/schemas/EndpointResult"}}}}}}},"402":{"description":"Payment Required"}}}}},"components":{"schemas":{"EndpointResult":{"type":"object","description":"A single ranked x402 API endpoint.","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","example":"https://api.example.com/v1/price"},"method":{"type":"string","example":"GET"},"description":{"type":"string"},"inputSchema":{"type":["object","null"],"description":"JSON Schema describing accepted parameters."},"outputSchema":{"type":["object","null"],"description":"JSON Schema describing the response shape."},"score":{"type":["number","null"],"description":"Composite quality rating (0–5).","example":4.3},"similarity":{"type":"number","description":"Vector similarity to the query (0–1).","example":0.87},"priceUsdc":{"type":["number","null"],"description":"Last observed price in USDC.","example":0.001},"latencyAvgMs":{"type":["integer","null"],"description":"Average upstream latency in milliseconds.","example":340},"availability":{"type":["number","null"],"description":"Historical availability ratio (0–1).","example":0.98},"totalCalls":{"type":"integer","description":"Total calls recorded by Pickr.","example":128},"paymentAsset":{"type":["string","null"],"description":"ERC-20 asset contract address."},"paymentNetwork":{"type":["string","null"],"description":"EIP-155 network identifier.","example":"eip155:8453"},"lastChecked":{"type":["string","null"],"format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"detail":{"type":"string"}}}}}}