{"openapi":"3.1.0","info":{"title":"ThoughtProof Reasoning Verification API","description":"Adversarial reasoning verification for AI agents: independent models evaluate a decision, a separate red-team model challenges their verdicts, and a synthesizer weighs both into a final ALLOW, BLOCK, or UNCERTAIN — with an EdDSA-signed attestation.","version":"1.4.0","guidance":"Use POST /v1/check to verify agent decisions before settlement. Provide claim + stakeLevel + domain. x402 payment required on Base (USDC). JWKS at /.well-known/jwks.json.","contact":{"url":"https://thoughtproof.ai","email":"support@thoughtproof.ai"}},"servers":[{"url":"https://api.thoughtproof.ai","description":"Production"}],"security":[{"operatorApiKey":[]}],"paths":{"/v1/check":{"get":{"operationId":"checkDiscovery","summary":"x402/MPP service discovery","description":"Returns x402-compatible 402 response for agent discovery. POST to /v1/check to run adversarial reasoning verification.","security":[],"x-payment-info":{"pricingMode":"range","price":"0.008000","priceMax":"1.000000","priceMaxNote":"x402 negotiation upper-bound. Active pricing tiers are fast=$0.008, standard=$0.02, deep=$0.08; priceMax is not currently routed for any speed/stakeLevel combination but reserved for future tier expansion.","protocols":["x402","mpp"]},"responses":{"402":{"description":"Payment Required — x402 payment on Base (USDC)"}}},"post":{"operationId":"verifyReasoning","summary":"Verify AI agent reasoning quality","description":"Adversarial multi-model verification: independent evaluators examine the reasoning, a separate red-team model challenges their verdicts, and a synthesizer produces the final verdict. Returns ALLOW, BLOCK, or UNCERTAIN with confidence score and JWKS-signed attestation.","x-payment-info":{"pricingMode":"range","price":"0.008000","priceMax":"1.000000","priceMaxNote":"x402 negotiation upper-bound. Active pricing tiers are fast=$0.008, standard=$0.02, deep=$0.08; priceMax is not currently routed for any speed/stakeLevel combination but reserved for future tier expansion.","protocols":["x402","mpp"]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim"],"properties":{"claim":{"type":"string","description":"The decision or reasoning to verify"},"stakeLevel":{"type":"string","enum":["low","medium","high","critical"],"default":"medium"},"domain":{"type":"string","enum":["financial","medical","legal","code","general"],"default":"general"},"speed":{"type":"string","enum":["fast","standard","deep"],"default":"standard","description":"Verification depth. Pricing: fast=$0.008, standard=$0.02, deep=$0.08 (Base USDC via x402)"},"agentId":{"type":"string","description":"Optional caller/agent identifier for per-agent verification history (also accepted via X-Agent-Id header; body wins). Powers GET /v1/stats/{agentId} and /v1/trustscore/{agentId}."}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["ALLOW","BLOCK","UNCERTAIN"]},"confidence":{"type":"number","example":0.82},"objections":{"type":"array","items":{"type":"string"}},"durationMs":{"type":"integer"}}}}}},"402":{"description":"x402 payment required"}}}},"/v1/operators":{"post":{"operationId":"registerOperator","summary":"Register as an operator","description":"Creates a new operator account and returns an API key (tp_op_...). Use this in the X-API-Key header.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"MyAIApp"},"email":{"type":"string","format":"email","example":"dev@example.com"}}}}}},"responses":{"201":{"description":"Operator registered","content":{"application/json":{"schema":{"type":"object","properties":{"operatorId":{"type":"string"},"apiKey":{"type":"string"},"name":{"type":"string"}}}}}}}}},"/v1/agents":{"post":{"operationId":"registerAgent","summary":"Register an AI agent","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"payment-agent-v2"},"description":{"type":"string"}}}}}},"responses":{"201":{"description":"Agent registered","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"name":{"type":"string"},"apiKey":{"type":"string"},"registeredAt":{"type":"string","format":"date-time"}}}}}}}},"get":{"operationId":"listAgents","summary":"List all registered agents","responses":{"200":{"description":"List of agents"}}}},"/v1/stats/{agentId}":{"get":{"operationId":"getOutputVerificationStats","summary":"HCS-25 output-verification summary for an agent","description":"Returns the HCS-25 AI Trust Score `outputVerificationSummary` (allow/block/uncertain rates, avg calibrated confidence, per-stake distribution, contributing providers) over a rolling window. Conformant with the HCS-25 output-verification signal. Public endpoint, no auth required.","security":[],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"window","in":"query","required":false,"description":"Rolling window in days (e.g. 7d or 7). Default 7, clamped 1–365.","schema":{"type":"string","default":"7d","example":"7d"}}],"responses":{"200":{"description":"HCS-25 output-verification summary","content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"object","properties":{"agentId":{"type":"string"},"metadata":{"type":"object","properties":{"outputVerificationSummary":{"type":"object","properties":{"allowRate":{"type":"number","minimum":0,"maximum":1},"blockRate":{"type":"number","minimum":0,"maximum":1},"uncertainRate":{"type":"number","minimum":0,"maximum":1},"avgConfidence":{"type":"number","minimum":0,"maximum":1},"totalChecks":{"type":"integer"},"stakeDistribution":{"type":"object","description":"Per-stake-level {checks, allowRate, avgConfidence} for low/medium/high/critical"},"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string","description":"Registered ERC-8004 agent id this provider attests under (env-configurable)"},"signerAddress":{"type":"string"},"methodologyUrl":{"type":"string"},"checksContributed":{"type":"integer"}}}},"windowDays":{"type":"integer"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}}}}}}},"/v1/trustscore/{agentId}":{"get":{"operationId":"getTrustScore","summary":"Get an agent's public trust score","description":"Returns composite trust score (0–100), tier, and breakdown computed from verification history. Public endpoint, no auth required.","security":[],"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Trust score profile","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string"},"trustscore":{"type":"integer","minimum":0,"maximum":100,"example":82},"tier":{"type":"string","enum":["new","building","trusted","verified"]},"breakdown":{"type":"object","properties":{"reliability":{"type":"integer","minimum":0,"maximum":100,"description":"verified/total ratio × 100"},"volume":{"type":"integer","minimum":0,"maximum":100,"description":"min(total × 10, 100)"},"recency":{"type":"integer","minimum":0,"maximum":100,"description":"time since last verification"}}},"receipt_summary":{"type":"object","properties":{"total":{"type":"integer"},"verified":{"type":"integer"},"unverified":{"type":"integer"}}},"message":{"type":"string","example":"Verified — 17/20 verifications passed"}}}}}}}}},"/v1/badge/{filename}":{"get":{"operationId":"getTrustBadge","summary":"Get an SVG trust badge for an agent","description":"Returns an embeddable SVG shield (160×20px) showing the agent's trust score and tier. Cache-Control: max-age=300. Filename format: <agentId>.svg.","security":[],"parameters":[{"name":"filename","in":"path","required":true,"description":"agentId followed by .svg extension","schema":{"type":"string","example":"37477.svg"}}],"responses":{"200":{"description":"SVG badge","content":{"image/svg+xml":{"schema":{"type":"string"}}},"headers":{"Cache-Control":{"schema":{"type":"string","example":"max-age=300, s-maxage=300"}}}}}}},"/v1/verify":{"post":{"operationId":"issueReceipt","summary":"Issue a signed verification receipt","description":"Verify a claim and receive an EdDSA-signed receipt (JWT + blockHash). Requires a real registered agentId from POST /v1/agents. Supports operator-key and x402 payment flows.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agentId","claim","verdict"],"properties":{"agentId":{"type":"string","example":"agent_abc123xyz"},"claim":{"type":"string","example":"Approve €500 payment to vendor-42 based on invoice analysis"},"verdict":{"type":"string","enum":["ALLOW","BLOCK","UNCERTAIN"]},"domain":{"type":"string","default":"general"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"201":{"description":"Receipt issued","content":{"application/json":{"schema":{"type":"object","properties":{"receiptId":{"type":"string","example":"rcpt_xK9mN2pQ4rT8sV"},"verdict":{"type":"string"},"score":{"type":"number","example":0.8234},"jwt":{"type":"string","description":"Signed receipt JWT (EdDSA)"},"blockHash":{"type":"string"},"verifyUrl":{"type":"string"},"proof":{"type":"object","description":"Self-describing proof: carries kid, jwks_uri, verify_proof_url and claim_hash so any receiver can verify offline without trusting ThoughtProof or the presenter.","properties":{"format":{"type":"string","example":"tp-eddsa-jwt-1"},"jwt":{"type":"string"},"alg":{"type":"string","example":"EdDSA"},"kid":{"type":"string","example":"tp-attestor-v1"},"issuer":{"type":"string","example":"https://api.thoughtproof.ai"},"jwks_uri":{"type":"string","example":"https://api.thoughtproof.ai/.well-known/jwks.json"},"verify_proof_url":{"type":"string","example":"https://api.thoughtproof.ai/v1/verify-proof"},"claim_hash":{"type":"string","example":"sha256:1ae1...bffb5"}}}}}}}}}}},"/v1/verify-proof":{"post":{"operationId":"verifyProof","summary":"Independently verify a ThoughtProof attestation (free, no auth)","description":"Verify a ThoughtProof EdDSA attestation without trusting the presenter and without auth or payment. This is a convenience wrapper around the same offline verification any holder can run against /.well-known/jwks.json: it checks the EdDSA signature, the kid against the published attestor key, and expiry. The receiver may equally recompute claim_hash = sha256:<hex of raw claim> and verify the JWT locally with the published JWK — no trust in ThoughtProof required.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jwt":{"type":"string","description":"Compact EdDSA JWT from a verify receipt (or pass proof.jwt)."},"proof":{"type":"object","properties":{"jwt":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean","description":"true only if signature valid AND not expired AND kid trusted"},"signatureValid":{"type":"boolean"},"expired":{"type":"boolean"},"kid":{"type":"string","example":"tp-attestor-v1"},"issuer":{"type":"string"},"claim_hash":{"type":"string","example":"sha256:1ae1...bffb5"},"verdict":{"type":"string"},"confidence":{"type":"number"},"issuedAt":{"type":"integer"},"expiresAt":{"type":"integer"},"jwks_uri":{"type":"string"}}}}}},"400":{"description":"Missing or malformed jwt"}}}},"/v1/receipts/{receiptId}":{"get":{"operationId":"getReceipt","summary":"Retrieve a receipt","description":"Fetch a previously issued receipt. No auth required — publicly verifiable.","security":[],"parameters":[{"name":"receiptId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Receipt found"}}}},"/v1/issuer/wallet/{address}":{"get":{"operationId":"getWalletAttestation","summary":"Get a wallet-bound ThoughtProof attestation","description":"Returns a signed wallet_reasoning_integrity/v1 envelope for a wallet address. Public endpoint for multi-issuer orchestrators and composed trust envelopes. score_normalized is the canonical 0..1 score, score_display is the same score mapped to 0..100, and confidence_bps expresses the same confidence in basis points.","security":[],"parameters":[{"name":"address","in":"path","required":true,"description":"EVM wallet address to resolve against registered ThoughtProof agents","schema":{"type":"string","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f7E2c1"}}],"responses":{"200":{"description":"Signed wallet attestation","content":{"application/json":{"schema":{"type":"object","properties":{"issuer":{"type":"string","example":"thoughtproof"},"schema":{"type":"string","example":"wallet_reasoning_integrity/v1"},"wallet":{"type":"string","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f7E2c1"},"found":{"type":"boolean","example":true},"verdict":{"type":"string","enum":["VERIFIED","NOT_FOUND","REVOKED","UNKNOWN"],"example":"VERIFIED"},"score_normalized":{"type":"number","example":0.82},"score_display":{"type":"number","example":82},"score_scale":{"type":"string","example":"0-1"},"confidence_bps":{"type":"integer","example":8200},"reason":{"type":"string","example":"Wallet is linked to a registered agent with positive ThoughtProof receipts."},"evidence":{"type":"object","properties":{"attestationCount":{"type":"integer","example":4},"latestAttestation":{"type":"string","example":"rcpt_xK9mN2pQ4rT8sV"},"source":{"type":"string","example":"thoughtproof"}}},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"signature":{"type":"object","properties":{"alg":{"type":"string","example":"EdDSA"},"kid":{"type":"string","example":"tp-attestor-v1"},"value":{"type":"string","example":"base64url-signature"}}}}}}}},"400":{"description":"Invalid wallet address"}}}},"/.well-known/jwks.json":{"get":{"operationId":"getJwks","summary":"Get public signing keys (Ed25519)","security":[],"responses":{"200":{"description":"JWKS"}}}}},"components":{"securitySchemes":{"operatorApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Operator API key (format: tp_op_...)"}}}}