{"openapi":"3.1.0","info":{"title":"Karatum API","version":"0.1.0","description":"Outcome Oracle for AI agents: verified verdicts, K-ratings, routing and certificates. Verdicts are decided from evidence only; an agent's own claim is E0 and never an input. Success responses are `{ data }`, errors `{ error: { code, message } }`. Paid endpoints (route, verify, rating?detail=full) accept an API key or, where enabled, an x402 payment instead."},"servers":[{"url":"/"}],"security":[{},{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer kt_live_… (prepaid / enterprise: never charged per call)"},"x402":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 pay-per-call, USDC on Base Sepolia (eip155:84532), testnet only. Call without credentials, receive 402 + PAYMENT-REQUIRED, retry with PAYMENT-SIGNATURE = base64(JSON PaymentPayload). Settlement runs after the handler and only for responses below 400, so a rejected request is not charged. Use @x402/fetch (wrapFetchWithPayment) to automate this."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Check":{"type":"object","properties":{"name":{"type":"string"},"pass":{"type":"boolean"},"expected":{"type":"string"},"actual":{"type":"string"}},"required":["name","pass","expected","actual"]},"Distribution":{"type":"object","properties":{"min":{"type":"number"},"p50":{"type":"number"},"p90":{"type":"number"},"max":{"type":"number"},"mean":{"type":"number"}},"required":["min","p50","p90","max","mean"]},"Certificate":{"type":"object","properties":{"id":{"type":"string"},"buildId":{"type":"string"},"taskClass":{"type":"string"},"status":{"type":"string","enum":["VALID","STALE","EXPIRED","REVOKED","INSUFFICIENT"]},"effectiveStatus":{"type":"string","enum":["VALID","STALE","EXPIRED","REVOKED","INSUFFICIENT"]},"karats":{"type":"integer"},"sample":{"type":"integer"},"ciLow":{"type":"number"},"ciHigh":{"type":"number"},"evidenceClass":{"type":"string","enum":["E0","E1","E2","E3","E4"]},"fingerprintHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"reason":{"type":"string"},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","buildId","taskClass","status","effectiveStatus","karats","sample","ciLow","ciHigh","evidenceClass","fingerprintHash","reason","issuedAt","expiresAt"]},"Verdict":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["trial","verify"]},"taskId":{"type":"string"},"taskType":{"anyOf":[{"type":"string"},{"type":"null"}]},"trialId":{"anyOf":[{"type":"string"},{"type":"null"}]},"buildId":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent":{"anyOf":[{"type":"string"},{"type":"null"}]},"claim":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["success","failure","refused"]},"note":{"type":"string"}},"required":["status"]},{"type":"null"}]},"status":{"type":"string","enum":["SUCCESS","PARTIAL","FAILURE","UNKNOWN","DISPUTED","REVOKED"]},"evidenceClass":{"type":"string","enum":["E0","E1","E2","E3","E4"]},"checks":{"type":"array","items":{"$ref":"#/components/schemas/Check"}},"reason":{"type":"string"},"txHashes":{"type":"array","items":{"type":"string"}},"verdictHash":{"type":"string"},"attestation":{"anyOf":[{"type":"object","properties":{"uid":{"type":"string"},"tx":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"}},"required":["uid","tx","url"]},{"type":"null"}]},"metrics":{"anyOf":[{"type":"object","properties":{"steps":{"type":"integer"},"gasUsed":{"type":"string"},"llmCostUsd":{"type":"number"},"latencyMs":{"type":"number"}},"required":["steps","gasUsed","llmCostUsd","latencyMs"]},{"type":"null"}]},"startedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"finishedAt":{"type":"string","format":"date-time"}},"required":["id","source","taskId","taskType","trialId","buildId","agent","claim","status","evidenceClass","checks","reason","txHashes","verdictHash","attestation","metrics","startedAt","finishedAt"]},"VerifyResult":{"type":"object","properties":{"id":{"type":"string"},"chainId":{"type":"integer"},"agent":{"type":"string"},"taskId":{"type":"string"},"taskType":{"type":"string","enum":["web3.transfer","web3.swap"]},"status":{"type":"string","enum":["SUCCESS","PARTIAL","FAILURE","UNKNOWN","DISPUTED","REVOKED"]},"evidenceClass":{"type":"string","enum":["E0","E1","E2","E3","E4"]},"checks":{"type":"array","items":{"$ref":"#/components/schemas/Check"}},"reason":{"type":"string"},"verdictHash":{"type":"string"},"txHashes":{"type":"array","items":{"type":"string"}},"referenceBlock":{"type":"string","description":"first tx block − 1"},"referenceQuoteOut":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","chainId","agent","taskId","taskType","status","evidenceClass","checks","reason","verdictHash","txHashes","referenceBlock","referenceQuoteOut","createdAt"]},"RouteOption":{"type":"object","properties":{"buildId":{"type":"string"},"taskType":{"type":"string"},"pSuccess":{"type":"number"},"ciLow":{"type":"number"},"ciHigh":{"type":"number"},"sample":{"type":"integer"},"expectedCostUsd":{"type":"number"},"expectedLatencyMs":{"type":"number"},"basis":{"type":"string","enum":["task","build","prior"]},"label":{"type":"string"},"utilityUsd":{"type":"number"},"eligible":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["buildId","taskType","pSuccess","ciLow","ciHigh","sample","expectedCostUsd","expectedLatencyMs","basis","label","utilityUsd","eligible","reasons"]},"RouteRequest":{"type":"object","properties":{"taskType":{"type":"string","enum":["web3.transfer","web3.swap","web3.swap.budget","web3.multistep","web3.trap","web3.transfer.injected","web3.swap.volatile","software.bugfix"]},"valueUsd":{"type":"number","minimum":0,"maximum":1000000000},"maxCostUsd":{"type":"number","minimum":0,"maximum":1000000000},"maxLatencyMs":{"type":"integer","exclusiveMinimum":0,"maximum":86400000},"minSuccess":{"type":"number","minimum":0,"maximum":1}},"required":["taskType"],"additionalProperties":false},"VerifyRequest":{"type":"object","properties":{"task":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.transfer"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["token","to","amount"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.swap"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"tokenIn":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"tokenOut":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountIn":{"type":"string","pattern":"^\\d+$"},"maxSlippageBps":{"type":"integer","minimum":1,"maximum":5000}},"required":["tokenIn","tokenOut","amountIn","maxSlippageBps"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.swap.budget"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"tokenIn":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"tokenOut":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountIn":{"type":"string","pattern":"^\\d+$"},"maxSlippageBps":{"type":"integer","minimum":1,"maximum":5000},"maxBlocks":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"maxGas":{"type":"string","pattern":"^\\d+$"}},"required":["tokenIn","tokenOut","amountIn","maxSlippageBps","maxBlocks","maxGas"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.multistep"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"tokenIn":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"tokenOut":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountIn":{"type":"string","pattern":"^\\d+$"},"maxSlippageBps":{"type":"integer","minimum":1,"maximum":5000},"recipient":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["tokenIn","tokenOut","amountIn","maxSlippageBps","recipient"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.trap"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"inner":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"transfer"},"params":{"type":"object","properties":{"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"}},"required":["token","to","amount"]}},"required":["kind","params"]},{"type":"object","properties":{"kind":{"type":"string","const":"swap"},"params":{"type":"object","properties":{"tokenIn":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"tokenOut":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountIn":{"type":"string","pattern":"^\\d+$"},"maxSlippageBps":{"type":"integer","minimum":1,"maximum":5000}},"required":["tokenIn","tokenOut","amountIn","maxSlippageBps"]}},"required":["kind","params"]}]},"reason":{"type":"string","enum":["insufficient_balance","unreachable_slippage"]}},"required":["inner","reason"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.transfer.injected"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"to":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["token","to","amount","note"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"web3.swap.volatile"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"tokenIn":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"tokenOut":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amountIn":{"type":"string","pattern":"^\\d+$"},"maxSlippageBps":{"type":"integer","minimum":1,"maximum":5000},"moveBps":{"type":"integer","minimum":10,"maximum":2000}},"required":["tokenIn","tokenOut","amountIn","maxSlippageBps","moveBps"]}},"required":["id","type","version","params"]},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"software.bugfix"},"version":{"type":"number","const":1},"params":{"type":"object","properties":{"fixture":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]*$"},"allowedPaths":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"required":["fixture","allowedPaths"]}},"required":["id","type","version","params"]}]},"agent":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"txHashes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}},"required":["task","agent","txHashes"],"additionalProperties":false}}},"paths":{"/v1/health":{"get":{"summary":"Liveness and database status","security":[{}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"version":{"type":"string"},"database":{"type":"string","enum":["ok","down"]},"time":{"type":"string"}},"required":["status","version","database","time"]}}}}}}}}},"/v1/openapi.json":{"get":{"summary":"This document (not enveloped)","security":[{}],"responses":{"200":{"description":"OpenAPI 3.1"}}}},"/v1/agents":{"get":{"summary":"List agents with their builds","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"owner":{"type":"string"},"internal":{"type":"boolean"},"builds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"model":{"type":"string"}},"required":["id","label","model"]}}},"required":["id","name","owner","internal","builds"]}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/builds/{id}":{"get":{"summary":"Build genome, latest fingerprint and certificates","parameters":[{"name":"id","in":"path","required":true,"description":"Build id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"label":{"type":"string"},"genome":{"type":"object"},"agent":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"owner":{"type":"string"},"internal":{"type":"boolean"}},"required":["id","name","owner","internal"]},{"type":"null"}]},"fingerprint":{"anyOf":[{"type":"object","properties":{"hash":{"type":"string"},"drift":{"type":"number"},"takenAt":{"type":"string"}},"required":["hash","drift","takenAt"]},{"type":"null"}]},"certificates":{"type":"array","items":{"$ref":"#/components/schemas/Certificate"}}},"required":["id","agentId","label","genome","agent","fingerprint","certificates"]}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/builds/{id}/rating":{"get":{"summary":"P(success) and K-rating per task type and per task class. detail=full is paid (API key or x402).","security":[{},{"apiKey":[]},{"x402":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Build id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}},{"name":"taskType","in":"query","schema":{"type":"string","enum":["web3.transfer","web3.swap","web3.swap.budget","web3.multistep","web3.trap","web3.transfer.injected","web3.swap.volatile","software.bugfix"]}},{"name":"detail","in":"query","description":"full: adds outcome distributions, certificates and the latest fingerprint (paid)","schema":{"type":"string","enum":["full"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["buildId","taskTypes","classes"],"properties":{"buildId":{"type":"string"},"taskTypes":{"type":"array","items":{"type":"object","properties":{"buildId":{"type":"string"},"taskType":{"type":"string"},"pSuccess":{"type":"number"},"ciLow":{"type":"number"},"ciHigh":{"type":"number"},"sample":{"type":"integer"},"expectedCostUsd":{"type":"number"},"expectedLatencyMs":{"type":"number"},"basis":{"type":"string","enum":["task","build","prior"]},"kRating":{"type":"object","properties":{"karats":{"type":"integer"},"low":{"type":"number"},"high":{"type":"number"},"successes":{"type":"integer"},"total":{"type":"integer"}},"required":["karats","low","high","successes","total"]}}}},"classes":{"type":"array","items":{"type":"object","properties":{"taskClass":{"type":"string"},"kRating":{"type":"object","properties":{"karats":{"type":"integer"},"low":{"type":"number"},"high":{"type":"number"},"successes":{"type":"integer"},"total":{"type":"integer"}},"required":["karats","low","high","successes","total"]}},"required":["taskClass","kRating"]}},"detail":{"description":"Only with detail=full","type":"object","properties":{"outcomes":{"type":"array","items":{"type":"object","properties":{"taskType":{"type":"string"},"total":{"type":"integer"},"successes":{"type":"integer"},"costUsd":{"anyOf":[{"$ref":"#/components/schemas/Distribution"},{"type":"null"}]},"latencyMs":{"anyOf":[{"$ref":"#/components/schemas/Distribution"},{"type":"null"}]}},"required":["taskType","total","successes","costUsd","latencyMs"]}},"certificates":{"type":"array","items":{"$ref":"#/components/schemas/Certificate"}},"fingerprint":{"anyOf":[{"type":"object","properties":{"hash":{"type":"string"},"drift":{"type":"number"},"takenAt":{"type":"string"}},"required":["hash","drift","takenAt"]},{"type":"null"}]}},"required":["outcomes","certificates","fingerprint"]}}}}}}},"headers":{"PAYMENT-RESPONSE":{"description":"x402 only: base64(JSON SettleResponse) with success, payer, transaction, network","schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402 v2, only when x402 is enabled on this deployment and no API key was sent). Decode the base64 `PAYMENT-REQUIRED` header, sign one of `accepts[]`, and retry with `PAYMENT-SIGNATURE`. Also returned when a payment fails verification or settlement.","headers":{"PAYMENT-REQUIRED":{"description":"base64(JSON PaymentRequired): x402Version, resource, accepts[{scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra}]","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/route":{"post":{"summary":"Pick the build with the best expected utility under constraints (API key or x402 payment)","security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/RouteRequest"},"recommended":{"anyOf":[{"$ref":"#/components/schemas/RouteOption"},{"type":"null"}]},"options":{"type":"array","items":{"$ref":"#/components/schemas/RouteOption"}}},"required":["request","recommended","options"]}}}}},"headers":{"PAYMENT-RESPONSE":{"description":"x402 only: base64(JSON SettleResponse) with success, payer, transaction, network","schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402 v2, only when x402 is enabled on this deployment and no API key was sent). Decode the base64 `PAYMENT-REQUIRED` header, sign one of `accepts[]`, and retry with `PAYMENT-SIGNATURE`. Also returned when a payment fails verification or settlement.","headers":{"PAYMENT-REQUIRED":{"description":"base64(JSON PaymentRequired): x402Version, resource, accepts[{scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra}]","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trials":{"get":{"summary":"List trials","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"taskClass":{"type":"string"},"seed":{"type":"integer"},"mirror":{"type":"object","properties":{"chain":{"type":"string"},"forkBlock":{"type":"string"},"harness":{"type":"string"}},"required":["chain","forkBlock","harness"]},"status":{"type":"string","enum":["running","complete","aborted"]}},"required":["id","name","taskClass","seed","mirror","status"]}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trials/{id}/leaderboard":{"get":{"summary":"Per-build verified results of one trial","parameters":[{"name":"id","in":"path","required":true,"description":"Trial id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"buildId":{"type":"string"},"label":{"type":"string"},"model":{"type":"string"},"attempts":{"type":"integer"},"claimedSuccess":{"type":"integer"},"verifiedSuccess":{"type":"integer"},"partial":{"type":"integer"},"failure":{"type":"integer"},"unknown":{"type":"integer"},"karats":{"type":"integer"},"ciLow":{"type":"number"},"ciHigh":{"type":"number"},"avgLlmCostUsd":{"type":"number"},"medianLatencyMs":{"type":"number"},"avgGasUsed":{"type":"number"}},"required":["buildId","label","model","attempts","claimedSuccess","verifiedSuccess","partial","failure","unknown","karats","ciLow","ciHigh","avgLlmCostUsd","medianLatencyMs","avgGasUsed"]}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/builds/{id}/verdicts":{"get":{"summary":"Recent trial verdicts of one build, newest first (max 100 per page; REVOKED ones are listed with their status)","parameters":[{"name":"id","in":"path","required":true,"description":"Build id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Verdict"}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/census/funnel":{"get":{"summary":"Census lifecycle funnel of indexed on-chain agents (ERC-8004 + ACP)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"registered":{"type":"integer"},"resolvable":{"type":"integer"},"callable":{"type":"integer"},"active":{"type":"integer"},"verified":{"type":"integer"},"updatedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["registered","resolvable","callable","active","verified","updatedAt"]}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Census not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verdicts/{id}":{"get":{"summary":"One verdict (trial attempt or vrf_… verification) with checks and attestation link","parameters":[{"name":"id","in":"path","required":true,"description":"Attempt id or vrf_… id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Verdict"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/certificates":{"get":{"summary":"Continuous certificates; effectiveStatus is EXPIRED once past TTL","parameters":[{"name":"buildId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Certificate"}}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/verify":{"post":{"summary":"E4 verdict on Base mainnet transactions (web3.transfer, web3.swap). API key or x402 payment.","description":"Every tx must be sent by `agent`. Balances and the QuoterV2 reference quote are read at (first tx block − 1), so the agent cannot move its own yardstick. The verdict hash uses the same canonical form as attested trial verdicts.","security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VerifyResult"}}}}},"headers":{"PAYMENT-RESPONSE":{"description":"x402 only: base64(JSON SettleResponse) with success, payer, transaction, network","schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402 v2, only when x402 is enabled on this deployment and no API key was sent). Decode the base64 `PAYMENT-REQUIRED` header, sign one of `accepts[]`, and retry with `PAYMENT-SIGNATURE`. Also returned when a payment fails verification or settlement.","headers":{"PAYMENT-REQUIRED":{"description":"base64(JSON PaymentRequired): x402Version, resource, accepts[{scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra}]","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"TX_NOT_FOUND or TX_NOT_FROM_AGENT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream RPC failure or wrong chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}