{"openapi":"3.1.0","info":{"title":"true402","version":"0.2.0","description":"Machine-native marketplace for x402-enabled services. Access any LLM with your wallet. No accounts. No API keys.","contact":{"url":"https://true402.dev"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://true402.dev/api","description":"Production"}],"paths":{"/":{"get":{"operationId":"getServiceManifest","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"}}}}}}},"/health":{"get":{"operationId":"healthCheck","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"}}}}}}},"/health/detailed":{"get":{"operationId":"healthDetailed","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"}}}}}}},"/v1/models":{"get":{"operationId":"listModels","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"}}}}}}},"/v1/models/{modelId}":{"get":{"operationId":"getModel","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"}}}}}}},"/v1/chat/completions":{"post":{"operationId":"chatCompletions","summary":"Chat completions (x402 payment required)","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":{"X-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","facilitatorUrl":"https://api.cdp.coinbase.com/x402/v2","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"}}}}}}},"/v1/services":{"get":{"operationId":"listServices","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"}}}}}}},"/v1/services/register":{"post":{"operationId":"registerService","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"}}}}}}},"/.well-known/x402-manifest.json":{"get":{"operationId":"getX402Manifest","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"}}}}}}},"/.well-known/ai-plugin.json":{"get":{"operationId":"getAiPlugin","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"}}}}}}},"/.well-known/mcp.json":{"get":{"operationId":"getMcpManifest","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"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","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"}}