{"openapi":"3.1.0","info":{"title":"Pickr","version":"1.0.0","description":"Discovery, routing, and data quality layer on top of x402. Use when the user asks for data behind a paid API that cannot be retrieved for free. Send a natural language intent, Pickr finds and calls the right API, 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> Intent-to-data relay for x402 micropayment APIs. $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## Network\n\n- Chain: Base (eip155:8453)\n- Asset: USDC — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\n- Facilitator: https://x402.dexter.cash","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","note":"Priced at upstream endpoint cost. Phase 1 returns the exact amount."},"protocols":[{"x402":{}}]},"security":[{"x402":[]}],"parameters":[{"$ref":"#/components/parameters/PaymentSignature"},{"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. Re-send with PAYMENT-SIGNATURE header after signing.","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded JSON with payment requirements.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}},"text/html":{"schema":{"type":"string","description":"Browser paywall page (served when Accept: text/html)."}}}},"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":{}}]},"security":[{"x402":[]}],"parameters":[{"$ref":"#/components/parameters/PaymentSignature"},{"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 ($0.01 USDC).","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded JSON with payment requirements.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}}},"components":{"securitySchemes":{"x402":{"type":"http","scheme":"bearer","description":"x402 payment protocol. Send a base64-encoded USDC transferWithAuthorization as the PAYMENT-SIGNATURE request header."}},"parameters":{"PaymentSignature":{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64-encoded x402 payment payload (required on Phase 2).","schema":{"type":"string"}}},"schemas":{"PaymentRequired":{"type":"object","description":"x402 payment requirements returned on a 402 response.","required":["x402Version","error","accepts"],"properties":{"x402Version":{"type":"integer","example":2},"error":{"type":"string","example":"Payment required"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","required":["scheme","network","amount","asset","payTo"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"amount":{"type":"string","description":"Amount in atomic units (USDC = 6 decimals).","example":"10000"},"asset":{"type":"string","description":"ERC-20 token contract address.","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"payTo":{"type":"string","description":"Recipient wallet address.","example":"0xAbC...123"},"maxTimeoutSeconds":{"type":"integer","example":300},"extra":{"type":"object","description":"EIP-712 domain extras required by USDC on Base.","properties":{"name":{"type":"string","example":"USD Coin"},"version":{"type":"string","example":"2"}}}}}}}},"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","nullable":true,"description":"JSON Schema describing accepted parameters."},"outputSchema":{"type":"object","nullable":true,"description":"JSON Schema describing the response shape."},"score":{"type":"number","nullable":true,"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","nullable":true,"description":"Last observed price in USDC.","example":0.001},"latencyAvgMs":{"type":"integer","nullable":true,"description":"Average upstream latency in milliseconds.","example":340},"availability":{"type":"number","nullable":true,"description":"Historical availability ratio (0–1).","example":0.98},"totalCalls":{"type":"integer","description":"Total calls recorded by Pickr.","example":128},"paymentAsset":{"type":"string","nullable":true,"description":"ERC-20 asset contract address."},"paymentNetwork":{"type":"string","nullable":true,"description":"EIP-155 network identifier.","example":"eip155:8453"},"lastChecked":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"detail":{"type":"string"}}}}}}