{"openapi":"3.1.0","info":{"title":"Clarity Agent API","version":"0.1.0","description":"Clarity provides pay-per-call AI inference for agents. OpenAI-compatible. $0.001 USDC per call over x402 on Base. Agent guide: /agents. Machine-readable skill: /skills.md.","contact":{"email":"onelovefuck@gmail.com"},"x-guidance":"Clarity provides pay-per-use AI inference. The simplest one-shot machine purchase is POST /v1/x402/chat/completions: send an OpenAI-style chat body, pay the live x402 v2 402 challenge, and receive the completion directly. No Clarity API key is required for that route. Initially only the local model local:qwen3:1.7b is supported (stream=false, max_tokens <= 128). Alternatively, POST /v1/x402/topup with an empty JSON object to purchase persistent gateway credit (a secret skey); keep that skey secret and use it as Authorization: Bearer <skey> when calling POST /v1/chat/completions. Pay exactly the network, asset and amount advertised by the live challenge."},"paths":{"/v1/x402/topup":{"post":{"operationId":"purchaseClarityInferenceCredit","summary":"Purchase Clarity AI inference credit","description":"Machine-payable top-up. The caller makes an x402 v2 payment and, after successful settlement, receives gateway credit plus a secret skey used to authenticate inference at POST /v1/chat/completions. Send an empty JSON object; an unpaid request returns a 402 payment challenge describing the exact network, asset, and amount to pay.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"responses":{"402":{"description":"Payment Required"},"200":{"description":"Successful x402 settlement and Clarity gateway credit","content":{"application/json":{"schema":{"type":"object","required":["id","skey","balance_usd","credited_usd","network","scheme","asset","payer","message"],"properties":{"id":{"type":"string"},"skey":{"type":"string"},"balance_usd":{"type":"number"},"credited_usd":{"type":"number"},"network":{"type":"string"},"scheme":{"type":"string"},"asset":{"type":"string"},"payer":{"type":"string"},"message":{"type":"string"}},"example":{"id":"example-key-id","skey":"gw_example_redacted","balance_usd":0.001,"credited_usd":0.001,"network":"eip155:8453","scheme":"exact","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payer":"0x1111111111111111111111111111111111111111","message":"Key funded after successful settlement."}}}}}}}},"/v1/x402/chat/completions":{"post":{"operationId":"purchaseClarityChatCompletion","summary":"Buy a Clarity AI chat completion","description":"Direct pay-per-request AI inference through Clarity using local:qwen3:1.7b. Pay the live x402 challenge and receive an OpenAI-compatible chat completion directly. No Clarity API key is required. stream=false and max_tokens <= 128.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","enum":["local:qwen3:1.7b"]},"messages":{"type":"array","minItems":1,"maxItems":16,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}}},"max_tokens":{"type":"integer","minimum":1,"maximum":128,"default":128},"temperature":{"type":"number","minimum":0,"maximum":2},"stream":{"type":"boolean","enum":[false],"default":false}}},"example":{"model":"local:qwen3:1.7b","messages":[{"role":"user","content":"Say hello in one sentence."}]}}}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.001000"},"protocols":[{"x402":{}}]},"responses":{"400":{"description":"Invalid request (bad model, messages, tokens, or streaming)"},"402":{"description":"Payment Required"},"503":{"description":"Local inference slot unavailable"},"200":{"description":"OpenAI-compatible chat completion","content":{"application/json":{"schema":{"type":"object","required":["id","object","model","choices","usage"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","required":["index","message","finish_reason"],"properties":{"index":{"type":"integer"},"message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string"},"content":{"type":"string"}}},"finish_reason":{"type":"string"}}}},"usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}},"example":{"id":"chatcmpl-example","object":"chat.completion","model":"qwen3:1.7b","choices":[{"index":0,"message":{"role":"assistant","content":"Hello from Clarity."},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}}}}}}}}}}