{"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, predict, rating?detail=full) accept an API key or, where enabled, an x402 payment instead. Registry writes (agents, builds, tasks, events, jobs) need an API key: the key is the tenant and owns what it writes. Every write is recorded in an append-only, hash-chained audit log."},"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},"RegisterAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":2000},"identities":{"default":[],"maxItems":16,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"erc8004"},"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"agentId":{"type":"string","pattern":"^\\d{1,78}$"}},"required":["kind","chainId","agentId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"wallet"},"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["kind","address"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"mcp"},"url":{"type":"string","maxLength":2048,"format":"uri"}},"required":["kind","url"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"a2a"},"url":{"type":"string","maxLength":2048,"format":"uri"}},"required":["kind","url"],"additionalProperties":false}]}}},"required":["name"],"additionalProperties":false},"RegisterBuildRequest":{"type":"object","properties":{"agentId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"},"label":{"type":"string","minLength":1,"maxLength":120},"version":{"type":"string","pattern":"^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$"},"genome":{"type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":200},"provider":{"type":"string","minLength":1,"maxLength":100},"promptHash":{"type":"string","minLength":1,"maxLength":200},"tools":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"strategy":{"type":"string","minLength":1,"maxLength":100},"harness":{"type":"string","minLength":1,"maxLength":100}},"required":["model","provider","promptHash","tools","strategy","harness"],"additionalProperties":false},"parentBuildId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"},"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["agentId","label","version","genome"],"additionalProperties":false},"StartTaskRequest":{"type":"object","properties":{"buildId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"},"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"]}]},"valueUsd":{"type":"number","minimum":0,"maximum":1000000000},"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}},"required":["buildId","task"],"additionalProperties":false},"SubmitEventRequest":{"type":"object","properties":{"buildId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"},"taskRunId":{"type":"string","pattern":"^run_[0-9a-f]{24}$"},"nonce":{"type":"integer","minimum":1,"maximum":9007199254740991},"kind":{"type":"string","enum":["step","tool_call","receipt","tx","log","claim","result"]},"issuedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"payload":{"type":"object","propertyNames":{"type":"string","maxLength":256},"additionalProperties":{}},"scheme":{"type":"string","enum":["eip191","eip712"]},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["buildId","taskRunId","nonce","kind","issuedAt","payload","scheme","signature"],"additionalProperties":false},"PredictRequest":{"type":"object","properties":{"buildId":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"},"taskType":{"type":"string","enum":["web3.transfer","web3.swap","web3.swap.budget","web3.multistep","web3.trap","web3.transfer.injected","web3.swap.volatile","software.bugfix"]}},"required":["buildId","taskType"],"additionalProperties":false},"EscrowRequest":{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"escrow":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^[1-9]\\d{0,38}$"},"provider":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"deadline":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"integer","exclusiveMinimum":0,"maximum":1099511627776}]},"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"]}]},"evaluator":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"client":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},"required":["chainId","escrow","token","amount","provider","deadline","task"],"additionalProperties":false},"RegisterJobRequest":{"type":"object","properties":{"chainId":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},"escrow":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"jobId":{"type":"string","pattern":"^[1-9]\\d{0,77}$"},"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"]}]}},"required":["chainId","escrow","jobId","task"],"additionalProperties":false},"SubmitProofRequest":{"type":"object","properties":{"txHashes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["txHashes","signature"],"additionalProperties":false},"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"]},"Rating":{"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"]}}}},"Identity":{"type":"object","properties":{"kind":{"type":"string","enum":["erc8004","wallet","mcp","a2a"]},"value":{"type":"string"},"verified":{"type":"boolean"}},"required":["kind","value","verified"]},"RegisteredAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"owner":{"type":"string"},"internal":{"type":"boolean"},"identities":{"type":"array","items":{"$ref":"#/components/schemas/Identity"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","description","owner","internal","identities","createdAt"]},"RegisteredBuild":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"label":{"type":"string"},"version":{"type":"string"},"genome":{"type":"object","properties":{"model":{"type":"string"},"provider":{"type":"string"},"promptHash":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}},"strategy":{"type":"string"},"harness":{"type":"string"}},"required":["model","provider","promptHash","tools","strategy","harness"]},"genomeHash":{"type":"string","description":"keccak256(canonicalJson(genome))"},"parentBuildId":{"anyOf":[{"type":"string"},{"type":"null"}]},"wallet":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","agentId","label","version","genome","genomeHash","parentBuildId","wallet","createdAt"]},"TaskRun":{"type":"object","properties":{"id":{"type":"string"},"buildId":{"type":"string"},"taskId":{"type":"string"},"taskType":{"type":"string"},"taskClass":{"type":"string","enum":["web3","software"]},"specHash":{"type":"string"},"status":{"type":"string","enum":["running","reported"]},"valueUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"events":{"type":"integer"},"lastNonce":{"anyOf":[{"type":"string","description":"last accepted nonce of the build"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","buildId","taskId","taskType","taskClass","specHash","status","valueUsd","events","lastNonce","createdAt","updatedAt"]},"EventReceipt":{"type":"object","properties":{"id":{"type":"string"},"taskRunId":{"type":"string"},"buildId":{"type":"string"},"nonce":{"type":"string"},"kind":{"type":"string","enum":["step","tool_call","receipt","tx","log","claim","result"]},"payloadHash":{"type":"string"},"signer":{"type":"string"},"scheme":{"type":"string","enum":["eip191","eip712"]},"evidenceClass":{"type":"string","enum":["E0"]},"issuedAt":{"type":"string","format":"date-time"},"receivedAt":{"type":"string","format":"date-time"}},"required":["id","taskRunId","buildId","nonce","kind","payloadHash","signer","scheme","evidenceClass","issuedAt","receivedAt"]},"PredictResult":{"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"},"taskClass":{"type":"string","enum":["web3","software"]},"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":["buildId","taskType","pSuccess","ciLow","ciHigh","sample","expectedCostUsd","expectedLatencyMs","basis","label","taskClass","kRating"]},"PreparedTx":{"type":"object","properties":{"step":{"type":"string","enum":["approve","createJob"]},"chainId":{"type":"integer"},"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string","enum":["0"]},"description":{"type":"string"}},"required":["step","chainId","to","data","value","description"]},"EscrowPrepared":{"type":"object","properties":{"chainId":{"type":"integer"},"escrow":{"type":"string"},"specHash":{"type":"string"},"spec":{"type":"object"},"terms":{"type":"object","properties":{"token":{"type":"string"},"amount":{"type":"string"},"provider":{"type":"string"},"evaluator":{"type":"string"},"client":{"anyOf":[{"type":"string"},{"type":"null"}]},"deadline":{"type":"string","format":"date-time"},"deadlineUnix":{"type":"string"},"feeBps":{"anyOf":[{"type":"integer"},{"type":"null"}]},"providerAmountOnSuccess":{"anyOf":[{"type":"string"},{"type":"null"}]},"gracePeriodSeconds":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["token","amount","provider","evaluator","client","deadline","deadlineUnix","feeBps","providerAmountOnSuccess","gracePeriodSeconds","expiresAt"]},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/PreparedTx"}},"register":{"type":"object"},"statusPath":{"type":"string"},"custody":{"type":"string"}},"required":["chainId","escrow","specHash","spec","terms","transactions","register","statusPath","custody"]},"EscrowStatus":{"type":"object","properties":{"id":{"type":"string"},"chainId":{"type":"integer"},"escrow":{"type":"string"},"jobId":{"type":"string"},"registered":{"type":"boolean"},"job":{"anyOf":[{"type":"object","description":"Same shape as GET /v1/jobs/{id}"},{"type":"null"}]},"onchain":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["Funded","Completed","Rejected","Reclaimed"]},"client":{"type":"string"},"provider":{"type":"string"},"evaluator":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string"},"feeBps":{"type":"integer"},"deadline":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"specHash":{"type":"string"}},"required":["status","client","provider","evaluator","token","amount","feeBps","deadline","expiresAt","specHash"]},{"type":"null"}]}},"required":["id","chainId","escrow","jobId","registered","job","onchain"]},"Incident":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["over_claim","failure","drift","revocation"]},"severity":{"type":"string","enum":["low","medium","high","critical"]},"status":{"type":"string","enum":["open","acknowledged","resolved"]},"buildId":{"type":"string"},"attemptId":{"anyOf":[{"type":"string"},{"type":"null"}]},"trialId":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskId":{"anyOf":[{"type":"string"},{"type":"null"}]},"taskType":{"anyOf":[{"type":"string"},{"type":"null"}]},"fingerprintHash":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"type":"string"},"details":{"type":"object"},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","kind","severity","status","buildId","attemptId","trialId","taskId","taskType","fingerprintHash","summary","details","firstSeenAt","lastSeenAt","occurredAt"]}}},"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"}}}}}},"post":{"summary":"Register an external agent and the identities it claims (ERC-8004, wallet, MCP, A2A). API key; the key's account owns it.","description":"Identities are stored unverified and are never evidence. Agents registered here are external (internal=false).","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/RegisteredAgent"}}}}}},"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"}}}},"415":{"description":"Content-Type must be application/json","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/agents/{id}/rating":{"get":{"summary":"K-rating of every build of an agent; task = a task type or a task class (web3, software)","parameters":[{"name":"id","in":"path","required":true,"description":"Agent id","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}},{"name":"task","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","web3","software"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"agentId":{"type":"string"},"task":{"anyOf":[{"type":"string"},{"type":"null"}]},"builds":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Rating"},{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]}]}},"best":{"anyOf":[{"type":"object","properties":{"buildId":{"type":"string"},"karats":{"type":"integer"}},"required":["buildId","karats"]},{"type":"null"}]}},"required":["agentId","task","builds","best"]}}}}}},"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 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"}}}}}}},"/v1/builds":{"post":{"summary":"Register a build (genome + version) of an agent you own; the API computes the genome hash and records lineage","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterBuildRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/RegisteredBuild"}}}}}},"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"}}}},"403":{"description":"NOT_OWNER: the agent belongs to another API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"BUILD_VERSION_EXISTS","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/tasks":{"post":{"summary":"Start a task run of a KOS task by a build you own. Idempotent with idempotencyKey (200 returns the original run).","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartTaskRequest"}}}},"responses":{"200":{"description":"Existing run for this idempotencyKey","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TaskRun"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/TaskRun"}}}}}},"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"}}}},"403":{"description":"NOT_OWNER","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED","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/tasks/{id}":{"get":{"summary":"One of your task runs (404 for other tenants' runs)","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Task run id (run_…)","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/TaskRun"}}}}}},"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 task run","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/events":{"post":{"summary":"Append a signed event (step, tool_call, receipt, tx, log, claim, result) to one of your task runs","description":"Signed by the build's registered wallet: EIP-191 personal_sign over eventSigningMessage() or EIP-712 typed data eventTypedData() (both in @karatum/sdk). The nonce must strictly increase per build; a replayed or reordered event is rejected (409 NONCE_REPLAYED). issuedAt must be at most 60 min old and 5 min in the future. Events are append-only and E0: what an agent signs about itself never decides a verdict.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitEventRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EventReceipt"}}}}}},"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"}}}},"403":{"description":"WRONG_SIGNER","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown task run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"NONCE_REPLAYED, DUPLICATE_SIGNATURE, RUN_CLOSED or NO_SIGNING_WALLET","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Payload too large","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/predict":{"post":{"summary":"Performance Model: P(success) with 95% interval, expected cost and latency for a build on a task type (API key or x402 payment)","security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PredictResult"}}}}},"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/escrow":{"post":{"summary":"Pay-on-Outcome: prepare a KaratumEscrow job — unsigned approve + createJob calldata and terms. Non-custodial: Karatum never signs.","description":"specHash = keccak256(canonicalJson(normalised task)). After JobCreated is mined, register the spec with POST /v1/jobs so the evaluator can resolve it from evidence. Fee, grace period and allowlists are read from the escrow when this deployment can.","security":[{},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EscrowRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EscrowPrepared"}}}}}},"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"}}}},"409":{"description":"ESCROW_PAUSED","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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"JOBS_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs":{"post":{"summary":"Register the spec of a funded KaratumEscrow job (its keccak256 must equal the on-chain specHash). API key.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterJobRequest"}}}},"responses":{"200":{"description":"Already registered with this spec","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"Job"}}}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"Job"}}}}}},"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":"JOB_NOT_FOUND_ONCHAIN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"SPEC_HASH_MISMATCH or JOB_NOT_FUNDED","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"}}}},"503":{"description":"JOBS_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}":{"get":{"summary":"An escrow job with its proof submissions","parameters":[{"name":"id","in":"path","required":true,"description":"job_<chainId>_<escrow>_<jobId>","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","description":"Job"}}}}}},"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 job","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"}}}},"503":{"description":"JOBS_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/jobs/{id}/submit":{"post":{"summary":"Submit proof transactions for a job, signed (EIP-191) by the job's provider. API key.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"job_<chainId>_<escrow>_<jobId>","schema":{"type":"string","maxLength":256,"pattern":"^[A-Za-z0-9._:@|-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitProofRequest"}}}},"responses":{"202":{"description":"Accepted for evaluation","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","description":"Submission"}}}}}},"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"}}}},"403":{"description":"NOT_JOB_PROVIDER","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"JOB_NOT_OPEN, DEADLINE_PASSED, SPEC_NOT_REGISTERED or TX_ALREADY_CLAIMED","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"}}}},"503":{"description":"JOBS_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/escrow/{jobId}":{"get":{"summary":"Status of an escrow job (job_<chainId>_<escrow>_<jobId>): registry state, or on-chain state when not registered","parameters":[{"name":"jobId","in":"path","required":true,"description":"job_<chainId>_<escrow>_<jobId>","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/EscrowStatus"}}}}}},"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 job","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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"JOBS_DISABLED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/certificates/{id}":{"get":{"summary":"One certificate; effectiveStatus is EXPIRED once past TTL","parameters":[{"name":"id","in":"path","required":true,"description":"Certificate 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/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"}}}},"404":{"description":"Unknown certificate","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/incidents/{id}":{"get":{"summary":"A public incident (failure, over-claim, drift, revocation on public trials). Private tender incidents are never served.","parameters":[{"name":"id","in":"path","required":true,"description":"Incident id (inc_…)","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/Incident"}}}}}},"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 or private incident","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"}]},"wallet":{"anyOf":[{"type":"string"},{"type":"null"}]},"erc8004":{"type":"array","items":{"type":"object","properties":{"chainId":{"type":"integer"},"agentId":{"type":"string"},"registry":{"anyOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}},"required":["chainId","agentId","registry","verified"]}},"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","wallet","erc8004","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"}}}}}}}}}