{"components":{"parameters":{"IdempotencyKey":{"description":"Optional idempotency key. Echoed back in the response headers and 402 bodies.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":128,"type":"string"}},"XCreditToken":{"description":"Optional credit token from /decision/outcome to reduce required_amount on paid calls.","in":"header","name":"X-Credit-Token","required":false,"schema":{"type":"string"}},"XPayer":{"in":"header","name":"X-Payer","required":false,"schema":{"type":"string"}},"XPaymentAmount":{"description":"Exact decimal amount that matches required_amount.","in":"header","name":"X-Payment-Amount","required":false,"schema":{"type":"string"}},"XPaymentAsset":{"in":"header","name":"X-Payment-Asset","required":false,"schema":{"enum":["USDC"],"type":"string"}},"XPaymentChain":{"in":"header","name":"X-Payment-Chain","required":false,"schema":{"type":"string"}},"XPaymentTx":{"in":"header","name":"X-Payment-Tx","required":false,"schema":{"type":"string"}}},"schemas":{"DecisionConstraints":{"additionalProperties":false,"properties":{"max_cost_usd":{"minimum":0,"type":"number"},"min_quality_score":{"maximum":1,"minimum":0,"type":"number"}},"required":["min_quality_score","max_cost_usd"],"type":"object"},"ErrorResponse":{"additionalProperties":true,"properties":{"error_code":{"type":"string"},"error_details":{"additionalProperties":true,"type":"object"}},"required":["error_code"],"type":"object"},"JobReceipt":{"additionalProperties":true,"properties":{"core_response_hash":{"description":"SHA-256 hash of the response body excluding job_receipt (0x + 32 bytes)","type":"string"},"eip712":{"additionalProperties":true,"description":"EIP-712 typed data + signature","type":"object"},"endpoint":{"type":"string"},"payment":{"additionalProperties":true,"type":"object"},"receipt_id":{"description":"Stable receipt id (0x + 32 bytes)","type":"string"},"receipt_version":{"enum":["v1"],"type":"string"},"request_hash":{"description":"SHA-256 hash of canonical request JSON (0x + 32 bytes)","type":"string"},"service":{"type":"string"}},"required":["receipt_version","service","endpoint","request_hash","core_response_hash","receipt_id","payment","eip712"],"type":"object"},"OptimizeRequest":{"additionalProperties":false,"properties":{"constraints":{"$ref":"#/components/schemas/DecisionConstraints"},"goal":{"maxLength":512,"type":"string"},"task_type":{"description":"Optional override for goal parsing (keeps routing deterministic).","enum":["summarize","extract","classify","coding","general"],"type":"string"},"workload":{"additionalProperties":false,"properties":{"images":{"minimum":0,"type":"number"},"input_cache_read_tokens":{"minimum":0,"type":"number"},"input_cache_write_tokens":{"minimum":0,"type":"number"},"input_tokens":{"minimum":0,"type":"number"},"internal_reasoning_tokens":{"minimum":0,"type":"number"},"output_tokens":{"minimum":0,"type":"number"},"requests":{"minimum":0,"type":"number"},"web_searches":{"minimum":0,"type":"number"}},"required":["input_tokens","output_tokens"],"type":"object"}},"required":["goal","constraints"],"type":"object"},"OptimizeResponse":{"additionalProperties":true,"properties":{"decision_id":{"type":"string"},"decision_version":{"type":"string"},"deterministic":{"type":"boolean"},"expected_cost":{"type":"number"},"expected_quality":{"type":"number"},"explainability":{"type":"object"},"fallback_plan":{"items":{"additionalProperties":false,"properties":{"option_id":{"type":"string"},"reason":{"type":"string"}},"required":["option_id","reason"],"type":"object"},"type":"array"},"human_review_required":{"type":"boolean"},"job_receipt":{"$ref":"#/components/schemas/JobReceipt"},"model_metadata":{"additionalProperties":true,"type":"object"},"payment":{"description":"Present when payment/credit verified","type":"object"},"recommended_model":{"type":"string"},"safe_to_execute":{"type":"boolean"},"scoring_version":{"type":"string"},"task_type":{"enum":["summarize","extract","classify","coding","general"],"type":"string"}},"required":["decision_id","decision_version","deterministic","scoring_version","recommended_model","expected_cost","expected_quality","safe_to_execute","human_review_required","explainability"],"type":"object"},"OutcomeRequest":{"additionalProperties":false,"properties":{"actual_cost":{"minimum":0,"type":"number"},"actual_latency":{"minimum":0,"type":"number"},"decision_id":{"type":"string"},"option_used":{"examples":["model_a"],"type":"string"},"quality_score":{"maximum":1,"minimum":0,"type":"number"},"success":{"type":"boolean"}},"required":["decision_id","option_used","actual_cost","actual_latency","quality_score","success"],"type":"object"},"OutcomeResponse":{"additionalProperties":true,"properties":{"decision_id":{"type":"string"},"outcome_hash":{"type":"string"},"refund_credit":{"type":"object"},"status":{"examples":["recorded"],"type":"string"}},"required":["status","decision_id","outcome_hash"],"type":"object"},"PaymentAccept":{"additionalProperties":false,"properties":{"asset":{"examples":["USDC"],"type":"string"},"chain":{"examples":["eip155:8453"],"type":"string"},"pay_to":{"description":"EVM address to pay","examples":["0x..."],"type":"string"},"scheme":{"enum":["exact"],"type":"string"}},"required":["chain","asset","pay_to","scheme"],"type":"object"},"PaymentRequired":{"additionalProperties":true,"properties":{"accepts":{"items":{"$ref":"#/components/schemas/PaymentAccept"},"type":"array"},"currency":{"examples":["USDC"],"type":"string"},"error_code":{"enum":["PAYMENT_REQUIRED"],"type":"string"},"idempotency_key":{"description":"Echo of Idempotency-Key when provided.","type":"string"},"payment_hint":{"additionalProperties":true,"description":"Machine-actionable hints for constructing the paid retry request.","type":"object"},"payment_reference":{"type":"string"},"required_amount":{"description":"Exact decimal USDC amount","type":"string"}},"required":["error_code","required_amount","currency","accepts","payment_reference"],"type":"object"},"SimulateResponse":{"additionalProperties":true,"properties":{"decision_id":{"type":"string"},"job_receipt":{"$ref":"#/components/schemas/JobReceipt"},"models":{"items":{"type":"object"},"type":"array"},"payment":{"type":"object"},"ranked_models":{"items":{"type":"object"},"type":"array"}},"required":["decision_id","models"],"type":"object"}}},"info":{"description":"Deterministic model-selection API for agents. Core endpoints: /decision/optimize and /decision/outcome. Paid endpoints use HTTP 402 and accept exact USDC on supported EVM chains. Wallet signing stays local; the API only verifies public payment proof. /decision/simulate is available when EXPANDED_PAID_FEATURES=1.","title":"which-llm Decision Economic Optimizer API","version":"v1"},"openapi":"3.1.0","paths":{"/decision/optimize":{"post":{"description":"Returns a single recommended option plus a fallback plan. Requires payment or credit (HTTP 402 model).\n\nTry it:\n\n```bash\nBASE_URL=\"https://api.which-llm.com\"\n\n# 1) First call (expect 402 PAYMENT_REQUIRED)\ncurl -sS -i -X POST \"$BASE_URL/decision/optimize\" \\\n  -H \"content-type: application/json\" \\\n  -H \"Idempotency-Key: demo_1\" \\\n  -d '{\"goal\":\"Choose an LLM model for summarizing user feedback emails.\",\"constraints\":{\"min_quality_score\":0.8,\"max_cost_usd\":0.01}}'\n\n# 2) Pay exact USDC to accepts[].pay_to on your chosen accepts[].chain, then retry with headers:\ncurl -sS -i -X POST \"$BASE_URL/decision/optimize\" \\\n  -H \"content-type: application/json\" \\\n  -H \"Idempotency-Key: demo_1\" \\\n  -H \"X-Payment-Chain: eip155:8453\" \\\n  -H \"X-Payment-Tx: 0x<tx_hash_32_bytes>\" \\\n  -H \"X-Payer: 0x<your_wallet_address>\" \\\n  -H \"X-Payment-Amount: <required_amount_from_402>\" \\\n  -H \"X-Payment-Asset: USDC\" \\\n  -d '{\"goal\":\"Choose an LLM model for summarizing user feedback emails.\",\"constraints\":{\"min_quality_score\":0.8,\"max_cost_usd\":0.01}}'\n```","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/XCreditToken"},{"$ref":"#/components/parameters/XPaymentChain"},{"$ref":"#/components/parameters/XPaymentTx"},{"$ref":"#/components/parameters/XPayer"},{"$ref":"#/components/parameters/XPaymentAmount"},{"$ref":"#/components/parameters/XPaymentAsset"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptimizeResponse"}}},"description":"Decision recommendation"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}},"description":"Payment required (USDC exact)"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limited"}},"summary":"Choose the recommended option","tags":["decision"],"x-payment":{"accepts":[{"asset":"USDC","chain":"eip155:8453","scheme":"exact"},{"asset":"USDC","chain":"eip155:1","scheme":"exact"},{"asset":"USDC","chain":"eip155:42161","scheme":"exact"},{"asset":"USDC","chain":"eip155:10","scheme":"exact"},{"asset":"USDC","chain":"eip155:43114","scheme":"exact"}],"asset":"USDC","scheme":"exact"}}},"/decision/outcome":{"post":{"description":"Report the outcome of a previously paid decision. If eligible, returns a credit token that can reduce the next required payment.\n\nTry it:\n\n```bash\nBASE_URL=\"https://api.which-llm.com\"\n\ncurl -sS -i -X POST \"$BASE_URL/decision/outcome\" \\\n  -H \"content-type: application/json\" \\\n  -H \"Idempotency-Key: outcome_1\" \\\n  -d '{\n    \"decision_id\": \"<decision_id_from_optimize_or_simulate>\",\n    \"option_used\": \"<recommended_model>\",\n    \"actual_cost\": 0.01,\n    \"actual_latency\": 650,\n    \"quality_score\": 0.78,\n    \"success\": true\n  }'\n```","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeResponse"}}},"description":"Outcome recorded (may include refund_credit)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request"}},"summary":"Report what happened and receive a credit token","tags":["decision"]}},"/erc8004/auth/siwe":{"post":{"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"message":{"type":"string"},"signature":{"type":"string"}},"required":["message","signature"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Gateway token"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid SIWE"}},"summary":"SIWE auth for gateway discovery","tags":["payments"]}},"/erc8004/gateway":{"get":{"parameters":[{"in":"header","name":"Authorization","required":false,"schema":{"examples":["Bearer <gateway_token>"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Endpoints"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing/invalid token"}},"summary":"Private endpoint discovery gateway","tags":["payments"]}},"/erc8004/public-capabilities":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Capabilities"}},"summary":"Public capabilities (redacted endpoints)","tags":["payments"]}},"/erc8004/reputation/prepare":{"post":{"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Transaction data"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"}},"summary":"Prepare an on-chain reputation post (calldata)","tags":["payments"]}},"/erc8004/service-agent.json":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Service agent metadata"}},"summary":"ERC-8004 service agent metadata (public)","tags":["payments"]}},"/report/wrong_address":{"post":{"description":"Free endpoint for reporting issues with receiver address validation. Submit optional details about validation problems from 'well known', 'api', or 'ENS' sources. At least one field is required.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"minProperties":1,"properties":{"ENS":{"description":"Issue with ENS validation","type":"string"},"api":{"description":"Issue with API-based validation","type":"string"},"well known":{"description":"Issue with .well-known validation","type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"report_id":{"format":"uuid","type":"string"},"reported_at_epoch":{"type":"integer"},"status":{"enum":["recorded"],"type":"string"}},"required":["status","report_id","reported_at_epoch"],"type":"object"}}},"description":"Report recorded successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rate limited"}},"summary":"Report address validation issues","tags":["reporting"]}}},"servers":[{"url":"https://api.which-llm.com"}],"tags":[{"description":"Core decision endpoints","name":"decision"},{"description":"HTTP 402 payment model (USDC)","name":"payments"},{"description":"Free reporting endpoints","name":"reporting"}]}