{"openapi":"3.1.0","info":{"title":"true402","version":"0.2.0","description":"The machine-native marketplace (bazaar) for x402 services. Software agents discover stalls and pay per call with HTTP 402 (USDC on Base). Wallet = identity; no accounts, no API keys.","contact":{"url":"https://true402.dev"},"license":{"name":"Proprietary"},"x-guidance":"true402 is a machine-native marketplace of x402-gated services (\"stalls\"). Each paid endpoint returns HTTP 402 with payment options (USDC on Base, EIP-3009); sign and retry with the X-PAYMENT header to receive the result. No account or API key — your wallet is your identity. Free endpoints (/health, /v1/models, /v1/services) need no payment. Browse the live catalog at /v1/services."},"servers":[{"url":"https://true402.dev","description":"Production"}],"paths":{"/api/":{"get":{"operationId":"getServiceManifest","security":[],"summary":"Service manifest","description":"Machine-readable description of the service, its endpoints, payment requirements, and security settings.","tags":["Discovery"],"responses":{"200":{"description":"Service manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceManifest"}}}}}}},"/api/health":{"get":{"operationId":"healthCheck","security":[],"summary":"Health check","description":"Returns basic service health status. No authentication required.","tags":["Health"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"ok","service":"true402","version":"0.2.0","timestamp":"2026-03-14T12:00:00.000Z"}}}}}}},"/api/health/detailed":{"get":{"operationId":"healthDetailed","security":[],"summary":"Detailed health check","description":"Returns service health including which LLM providers and payment rails are configured.","tags":["Health"],"responses":{"200":{"description":"Detailed health information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealthResponse"}}}}}}},"/api/v1/models":{"get":{"operationId":"listModels","security":[],"summary":"List available models","description":"Returns all available LLM models in OpenAI-compatible format. Only models whose provider API key is configured are returned.","tags":["Models"],"responses":{"200":{"description":"List of available models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}}}}},"/api/v1/models/{modelId}":{"get":{"operationId":"getModel","security":[],"summary":"Get model details","description":"Returns details and pricing for a specific model.","tags":["Models"],"parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"},"description":"The model identifier (e.g. gpt-4o, claude-3-5-sonnet)","example":"gpt-4o"}],"responses":{"200":{"description":"Model details with pricing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelDetail"}}}},"404":{"description":"Model not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/chat/completions":{"post":{"operationId":"chatCompletions","summary":"Chat completions (x402 payment required)","x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.0001","max":"5.00"},"protocols":[{"x402":{}}]},"description":"OpenAI-compatible chat completions endpoint. Requires x402 payment.\n\n**Payment flow:**\n1. Send a request without payment — you will receive a 402 response with payment requirements.\n2. The 402 response contains an `accepts` array with one or more payment options (EVM USDC, Lightning BTC).\n3. Sign a payment matching one of the accepted options.\n4. Retry the request with the signed payment in the `X-PAYMENT` header (base64-encoded JSON).\n5. The service verifies payment and returns the chat completion.\n\nSupports both streaming (SSE) and non-streaming responses.","tags":["Chat"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64-encoded JSON payment payload. Required for successful completion. Omit to receive 402 payment requirements.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Chat completion response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"description":"Server-Sent Events stream (when stream: true)","schema":{"type":"string","description":"SSE stream of ChatCompletionChunk objects. Each event is prefixed with \"data: \". The stream ends with \"data: [DONE]\"."}}}},"400":{"description":"Invalid request (missing model, empty messages, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The response body contains accepted payment options.","headers":{"payment-required":{"description":"Base64-encoded JSON array of payment requirements","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"},"example":{"x402Version":2,"error":"Payment Required","accepts":[{"scheme":"exact","network":"eip155:8453","maxAmountRequired":"1000","maxTimeoutSeconds":300,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x1111111111111111111111111111111111111111","mimeType":"application/json","description":"USDC payment on Base"},{"scheme":"bolt11","network":"lightning:mainnet","maxAmountRequired":"100","maxTimeoutSeconds":600,"invoice":"lnbc...","amountSats":"100","expiresAt":1710417600,"paymentHash":"abc123...","description":"Lightning BTC payment"}]}}}},"403":{"description":"Payment invalid (signature mismatch, expired, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/seo-audit":{"post":{"operationId":"seoAudit","summary":"SEO/GEO audit (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.015"},"protocols":[{"x402":{}}]},"description":"Audit a web page for SEO + GEO (generative-engine optimization). POST `{ url, mode? }`; an unpaid request returns 402 with payment requirements. After payment, returns a structured JSON report (per-category scores + issues). Flat-priced per request.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64-encoded JSON payment payload. Omit to receive the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The page URL to audit (http/https)"},"mode":{"type":"string","enum":["both","seo","geo"],"description":"Which analysis to run (default both)"}}}}}},"responses":{"200":{"description":"SEO/GEO report","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or disallowed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/web-extract":{"post":{"operationId":"webExtract","summary":"Web extract (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"description":"Fetch a web page and return clean readable text + light markdown + title/description/links. POST `{ url }`; an unpaid request returns 402. Flat-priced per request.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64-encoded JSON payment payload. Omit to receive the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The page URL to extract (http/https)"}}}}}},"responses":{"200":{"description":"Extracted content","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or disallowed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/link-preview":{"post":{"operationId":"linkPreview","summary":"Link preview (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"description":"Fetch a URL and return its Open Graph card (title, description, image, site name, favicon, canonical). POST `{ url }`; an unpaid request returns 402. Flat-priced per request.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64-encoded JSON payment payload. Omit to receive the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The page URL (http/https)"}}}}}},"responses":{"200":{"description":"Open Graph card","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or disallowed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/robots-check":{"post":{"operationId":"robotsCheck","summary":"Robots / AI-crawler check (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"description":"Fetch a site's robots.txt + llms.txt and report whether the major AI crawlers are allowed/blocked, plus sitemaps. POST `{ url }`; unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Any URL on the site"}}}}}},"responses":{"200":{"description":"AI-crawler policy + sitemaps","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or disallowed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/headers-check":{"post":{"operationId":"headersCheck","summary":"HTTP security-headers check (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"description":"Fetch a URL and analyse its HTTP security headers (HSTS, CSP, X-Frame-Options, …) into present/missing + a 0–100 score. POST `{ url }`; unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The URL (http/https)"}}}}}},"responses":{"200":{"description":"Security-headers analysis","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or disallowed URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/token-safety":{"post":{"operationId":"tokenSafety","summary":"Token safety check (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"description":"Rug/honeypot safety check for an ERC-20 token on Base (from on-chain reads — no API key): ERC-20 conformance, ownership renounce, mint-capability, WETH/USDC liquidity depth across Uniswap V3 + Aerodrome, and a buy/sell honeypot simulation (a gas-free eth_call that round-trips a tiny WETH→token→WETH trade to detect tokens you can buy but not sell). Returns a 0–100 score + risk flags. POST `{ token }`; unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"ERC-20 contract address on Base"},"chain":{"type":"string","description":"'base' (default)"}}}}}},"responses":{"200":{"description":"Token safety report","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid token address or unsupported chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/new-pairs":{"post":{"operationId":"newPairs","summary":"Recently-created Base DEX pairs (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"description":"Recently-created Base DEX pairs (Uniswap V3 + Aerodrome) from a background log-watcher — fresh token launches for trading agents/snipers. POST `{ since?, limit?, dex?, withToken? }`; each pair gives the new token, quote (WETH/USDC), pool, fee|stable, block + approx age. Bundle with /v1/token-safety for a pre-trade rug/honeypot check. Unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"number","description":"Only pairs first seen at or after this block"},"limit":{"type":"number","description":"Max pairs (1–200, default 50)"},"dex":{"type":"string","enum":["uniswap-v3","aerodrome"],"description":"Filter: 'uniswap-v3' | 'aerodrome'"},"withToken":{"type":"boolean","description":"Only token launches (default true)"}}}}}},"responses":{"200":{"description":"Recent pairs","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/liquidity-pulls":{"post":{"operationId":"liquidityPulls","summary":"Liquidity-pull / rug alerts on Base (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003"},"protocols":[{"x402":{}}]},"description":"Liquidity-pull / rug alerts on Base — Burn (liquidity-removal) events on recently-launched DEX pools (the new-pairs watcher's set). POST `{ since?, limit?, dex?, minQuote? }`; each event gives the pool, token, and WETH/USDC amount removed (the rug magnitude). Cross-check the token with /v1/token-safety. Unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"number","description":"Only pulls first seen at or after this block"},"limit":{"type":"number","description":"Max pulls (1–200, default 50)"},"dex":{"type":"string","enum":["uniswap-v3","aerodrome"],"description":"Filter: 'uniswap-v3' | 'aerodrome'"},"minQuote":{"type":"number","description":"Only removals of at least this much WETH/USDC"}}}}}},"responses":{"200":{"description":"Recent liquidity pulls","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/whale-swaps":{"post":{"operationId":"whaleSwaps","summary":"Whale swaps on Base — large ($-value) DEX Swaps (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"description":"Recent large ($-value) DEX Swap events (Uniswap V3 + Aerodrome) on the Base pools the new-pairs watcher tracks — a whale-following / copy-trading signal. POST `{ min?, dex?, since?, limit?, direction? }`; each swap gives the pool, token, quote (WETH/USDC), USD size, direction (buy/sell of the token), block + approx age, txHash. usdValue is the quote side (WETH×ETH-USD or USDC). Unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"min":{"type":"number","description":"Only swaps of at least this USD size (default 10000)"},"dex":{"type":"string","enum":["uniswap-v3","aerodrome"],"description":"Filter: 'uniswap-v3' | 'aerodrome'"},"since":{"type":"number","description":"Only swaps at or after this block"},"limit":{"type":"number","description":"Max swaps (1–200, default 50)"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter: 'buy' | 'sell' (of the non-quote token)"}}}}}},"responses":{"200":{"description":"Recent whale swaps","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/token-report":{"post":{"operationId":"tokenReport","summary":"Token Report — flagship \"can I safely ape in?\" composite (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]},"description":"The flagship composite for a Base ERC-20 — one call instead of five. Runs the full token-safety check (ERC-20 conformance, ownership, mint-capability, WETH/USDC liquidity depth, buy/sell honeypot simulation), enriches it with the live recent liquidity-removal (rug) + whale-swap activity on the token, and returns a single avoid|caution|ok verdict with reasons plus the underlying reports. POST `{ token }`. Cheaper than buying token-safety + liquidity-pulls + whale-swaps separately. Unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"ERC-20 contract address (0x…) on Base"},"chain":{"type":"string","description":"Chain to check; only 'base' is supported (default)"}}}}}},"responses":{"200":{"description":"Composite token report (verdict + safety + recent rug/whale activity)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid token address or unsupported chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/address-safety":{"post":{"operationId":"addressSafety","summary":"Address Safety — structural profile + risk for any Base address (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005"},"protocols":[{"x402":{}}]},"description":"Structural safety profile for ANY Base address — an EOA or an arbitrary contract — before an agent sends funds to it, approves it, or calls it. Returns contract-vs-EOA, ETH + USDC balance, tx-count (activity), and for contracts: whether it is a recognised ERC-20, ownership state, a mint() selector, and whether it is an EIP-1967 upgradeable proxy (its logic can be swapped after you trust it). Coarse risk band + flags. On-chain reads only — no API key. POST `{ address }`. Unpaid returns 402.","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Any address (0x…) on Base — an EOA or a contract"},"chain":{"type":"string","description":"Chain to check; only 'base' is supported (default)"}}}}}},"responses":{"200":{"description":"Address profile + risk (type, balances, token/ownership, EIP-1967 proxy, score, flags)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid address or unsupported chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."}}}},"/api/v1/base/deployer-check":{"post":{"operationId":"deployerCheck","summary":"Deployer Reputation — who created a Base token + how established that wallet is (x402 payment required)","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.008"},"protocols":[{"x402":{}}]},"description":"Resolves the deployer of a Base token and profiles that wallet's reputation: age (tx-count), balance, contracts shipped, and whether it is a FRESH throwaway spun up for the launch (a common rug setup) — the discriminating caution. Reputation context a structural/honeypot check can't see; raw contract count is reported as context, NOT a rug verdict (legit protocols ship many). POST `{ token }`. Unpaid returns 402. Requires an explorer key on the server; returns 503 if not configured (and is not charged).","tags":["Services"],"parameters":[{"name":"X-PAYMENT","in":"header","required":false,"description":"Base64 payment payload; omit for the 402 challenge.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Token contract address (0x…) on Base"},"chain":{"type":"string","description":"Chain to check; only 'base' is supported (default)"},"deep":{"type":"boolean","description":"Opt-in: also classify the deployer's recent prior tokens as live/dead (no liquidity = rug outcome). Slower; the real serial-rugger signal."}}}}}},"responses":{"200":{"description":"Deployer profile + risk (deployer, txCount, contractsCreated, score, flags; + priorTokens when deep)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid token or unsupported chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required. The body contains accepted payment options."},"503":{"description":"Deployer check not configured (no explorer key) — not charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/services":{"get":{"operationId":"listServices","security":[],"summary":"List registered services","description":"Browse all registered x402-enabled services. Optionally filter by capability.","tags":["Registry"],"parameters":[{"name":"capability","in":"query","required":false,"schema":{"type":"string"},"description":"Filter services by capability (e.g. llm, summarize, translate)","example":"llm"}],"responses":{"200":{"description":"List of registered services","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceList"}}}}}}},"/api/v1/services/register":{"post":{"operationId":"registerService","security":[],"summary":"Register an x402 service","description":"Register a new x402-enabled service in the marketplace. Free — no payment or approval required.\n\nThe registry will attempt to fetch `/.well-known/x402-service.json` from the provided URL. If that fails, it falls back to the manifest in the request body.","tags":["Registry"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterServiceRequest"},"example":{"url":"https://my-service.example.com","manifest":{"name":"my-service","description":"A useful x402 service","capabilities":["summarize"],"pricing":{"currency":"USDC","base":"0.001","unit":"request"},"payment":{"address":"0x1234567890abcdef1234567890abcdef12345678","network":"eip155:8453"}}}}}},"responses":{"201":{"description":"Service registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisteredService"}}}},"400":{"description":"Invalid request or manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Manifest unavailable or registration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/.well-known/x402-manifest.json":{"get":{"operationId":"getX402Manifest","security":[],"summary":"x402 service catalog","description":"Machine-readable x402 service catalog describing available services, pricing, and payment options.","tags":["Discovery"],"responses":{"200":{"description":"x402 manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Manifest"}}}}}}},"/api/.well-known/ai-plugin.json":{"get":{"operationId":"getAiPlugin","security":[],"summary":"OpenAI plugin manifest","description":"AI agent discovery manifest following the OpenAI plugin specification.","tags":["Discovery"],"responses":{"200":{"description":"AI plugin manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiPluginManifest"}}}}}}},"/api/.well-known/mcp.json":{"get":{"operationId":"getMcpManifest","security":[],"summary":"MCP discovery manifest","description":"Model Context Protocol manifest describing available tools for MCP-compatible clients.","tags":["Discovery"],"responses":{"200":{"description":"MCP manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpManifest"}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenApiSpec","security":[],"summary":"OpenAPI specification","description":"Returns this OpenAPI 3.1.0 specification document.","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI 3.1.0 specification","content":{"application/json":{"schema":{"type":"object","description":"OpenAPI 3.1.0 specification document"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string","description":"Machine-readable error code","examples":["invalid_request","model_not_found","payment_required","payment_invalid","internal_error"]},"message":{"type":"string","description":"Human-readable error description"}}}}},"HealthResponse":{"type":"object","required":["status","service","version","timestamp"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"DetailedHealthResponse":{"type":"object","required":["status","service","version","timestamp","providers","x402"],"properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"providers":{"type":"object","description":"Boolean flags indicating which providers have API keys configured","additionalProperties":{"type":"boolean"}},"x402":{"type":"object","properties":{"recipientConfigured":{"type":"boolean"}}}}},"ModelList":{"type":"object","required":["object","data"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"Model":{"type":"object","required":["id","object","created","owned_by"],"properties":{"id":{"type":"string","description":"Model identifier","examples":["gpt-4o"]},"object":{"type":"string","enum":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string","description":"Provider name","examples":["openai","anthropic","google","groq","mistral","together"]}}},"ModelDetail":{"type":"object","required":["id","object","created","owned_by","pricing"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string"},"pricing":{"type":"object","required":["inputPricePerMillion","outputPricePerMillion","currency","markup"],"properties":{"inputPricePerMillion":{"type":"number","description":"USD price per million input tokens"},"outputPricePerMillion":{"type":"number","description":"USD price per million output tokens"},"currency":{"type":"string","enum":["USD"]},"markup":{"type":"string","description":"Markup percentage","examples":["3%"]}}}}},"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"type":["string","null"]},"name":{"type":"string"},"tool_call_id":{"type":"string"}}},"ChatCompletionRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"Model identifier from /v1/models","examples":["gpt-4o","claude-3-5-sonnet","gemini-2.0-flash"]},"messages":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/ChatMessage"}},"max_tokens":{"type":"integer","minimum":1,"maximum":128000},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number","minimum":0,"maximum":1},"n":{"type":"integer","minimum":1,"maximum":10},"stream":{"type":"boolean","default":false},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":4}]},"presence_penalty":{"type":"number","minimum":-2,"maximum":2},"frequency_penalty":{"type":"number","minimum":-2,"maximum":2},"user":{"type":"string","maxLength":256}}},"ChatCompletionResponse":{"type":"object","required":["id","object","created","model","choices","usage"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","required":["index","message","finish_reason"],"properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/ChatMessage"},"finish_reason":{"type":["string","null"],"enum":["stop","length","tool_calls","content_filter",null]}}}},"usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"PaymentRequired":{"type":"object","required":["x402Version","error","accepts"],"description":"Returned with HTTP 402 status. Contains payment options the client can choose from.","properties":{"x402Version":{"type":"integer","enum":[2]},"error":{"type":"string","enum":["Payment Required"]},"accepts":{"type":"array","description":"Available payment options. Client should pick one and pay.","items":{"oneOf":[{"$ref":"#/components/schemas/EVMPaymentRequirement"},{"$ref":"#/components/schemas/LightningPaymentRequirement"}]}}}},"EVMPaymentRequirement":{"type":"object","required":["scheme","network","maxAmountRequired","maxTimeoutSeconds","asset","payTo","facilitatorUrl","mimeType"],"description":"EVM payment option (USDC on Base via EIP-3009 gasless transfer)","properties":{"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","enum":["eip155:8453","eip155:84532","eip155:1"],"description":"CAIP-2 network identifier"},"maxAmountRequired":{"type":"string","description":"Maximum amount in token base units (USDC has 6 decimals)"},"maxTimeoutSeconds":{"type":"integer"},"asset":{"type":"string","description":"ERC-20 token contract address (USDC)","examples":["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"]},"payTo":{"type":"string","description":"Recipient wallet address"},"facilitatorUrl":{"type":"string","format":"uri","description":"Coinbase facilitator URL for payment verification"},"mimeType":{"type":"string"},"description":{"type":"string"}}},"LightningPaymentRequirement":{"type":"object","required":["scheme","network","maxAmountRequired","maxTimeoutSeconds","invoice","amountSats","expiresAt","paymentHash"],"description":"Lightning Network payment option (BTC via BOLT11 invoice)","properties":{"scheme":{"type":"string","enum":["bolt11"]},"network":{"type":"string","enum":["lightning:mainnet","lightning:testnet"]},"maxAmountRequired":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"invoice":{"type":"string","description":"BOLT11 encoded Lightning invoice"},"amountSats":{"type":"string","description":"Amount in satoshis"},"expiresAt":{"type":"integer","description":"Unix timestamp when the invoice expires"},"paymentHash":{"type":"string","description":"SHA-256 payment hash"},"nodePublicKey":{"type":"string","description":"Receiving node public key"},"description":{"type":"string"}}},"EVMPaymentPayload":{"type":"object","required":["x402Version","scheme","network","payload"],"description":"EVM payment payload to include in the X-PAYMENT header (base64-encoded JSON)","properties":{"x402Version":{"type":"integer","enum":[2]},"scheme":{"type":"string","enum":["exact"]},"network":{"type":"string","enum":["eip155:8453","eip155:84532","eip155:1"]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"}}},"payload":{"type":"object","required":["signature","authorization"],"properties":{"signature":{"type":"string","description":"EIP-712 signature (hex)"},"authorization":{"type":"object","required":["from","to","value","validAfter","validBefore","nonce"],"properties":{"from":{"type":"string","description":"Payer address"},"to":{"type":"string","description":"Recipient address"},"value":{"type":"string","description":"Amount in base units"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"nonce":{"type":"string"}}}}}}},"LightningPaymentPayload":{"type":"object","required":["x402Version","scheme","network","paymentHash"],"description":"Lightning payment payload to include in the X-PAYMENT header (base64-encoded JSON)","properties":{"x402Version":{"type":"integer","enum":[2]},"scheme":{"type":"string","enum":["bolt11"]},"network":{"type":"string","enum":["lightning:mainnet","lightning:testnet"]},"paymentHash":{"type":"string","description":"Payment hash from the invoice"},"preimage":{"type":"string","description":"Preimage (proof of payment)"}}},"ServiceList":{"type":"object","required":["object","data","total"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RegisteredService"}},"total":{"type":"integer"}}},"RegisterServiceRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Base URL of the service. The registry will attempt to fetch /.well-known/x402-service.json from it."},"manifest":{"type":"object","description":"Fallback manifest if /.well-known/x402-service.json cannot be fetched.","properties":{"name":{"type":"string"},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"pricing":{"type":"object","properties":{"currency":{"type":"string"},"base":{"type":"string"},"unit":{"type":"string"}}},"payment":{"type":"object","properties":{"address":{"type":"string"},"network":{"type":"string"}}}}}}},"RegisteredService":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"name":{"type":"string"},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"registeredAt":{"type":"string","format":"date-time"}}},"ServiceManifest":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"documentation":{"type":"string","format":"uri"},"endpoints":{"type":"object","additionalProperties":{"type":"string"}},"payment":{"type":"object","properties":{"protocol":{"type":"string"},"version":{"type":"integer"},"networks":{"type":"array","items":{"type":"string"}},"facilitator":{"type":"string","format":"uri"}}},"security":{"type":"object","properties":{"rateLimit":{"type":"string"},"bodyLimit":{"type":"string"},"timeout":{"type":"string"}}}}},"X402Manifest":{"type":"object","properties":{"x402Version":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"services":{"type":"array","items":{"type":"object"}},"registry":{"type":"object"}}},"AiPluginManifest":{"type":"object","properties":{"schema_version":{"type":"string"},"name_for_human":{"type":"string"},"name_for_model":{"type":"string"},"description_for_human":{"type":"string"},"description_for_model":{"type":"string"},"auth":{"type":"object"},"api":{"type":"object"}}},"McpManifest":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"tools":{"type":"array","items":{"type":"object"}},"payment":{"type":"object"}}}}},"tags":[{"name":"Discovery","description":"Machine discovery endpoints for agents and tools"},{"name":"Health","description":"Service health and status"},{"name":"Models","description":"LLM model catalog and pricing"},{"name":"Chat","description":"OpenAI-compatible chat completions (x402-gated)"},{"name":"Registry","description":"x402 service marketplace registry"}],"externalDocs":{"description":"x402 Protocol Specification","url":"https://x402.org"}}