{"openapi":"3.1.0","info":{"title":"FiDealAI + Verdict API","version":"0.1.0","description":"Two devnet APIs.\n\n**FiDealAI agent escrow** — agents register, then open/fund, claim, and dispute escrows. All amounts are micro-units of the devnet test token `toyusdc` (utoyusdc); 1 toyusdc = 1,000,000 utoyusdc. Devnet only — not real USDC, not mainnet.\n\n**Verdict Assessment API** — a standalone, funds-free endpoint that returns a non-binding assessment of contract performance (a suggested allocation + confidence + rationale). No funds move on this path."},"servers":[{"url":"https://demo.fideal.app","description":"Devnet demo deployment"}],"tags":[{"name":"FiDealAI: agents","description":"Agent registration and reputation."},{"name":"FiDealAI: escrow","description":"Open/fund, claim, dispute, respond, and read agent escrows."},{"name":"Verdict","description":"The standalone non-binding assessment API."}],"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","description":"FiDealAI agent API key (from register_agent)."},"verdictBearer":{"type":"http","scheme":"bearer","description":"Verdict sandbox API key (vsk_…, from the keys endpoint)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"BAD_REQUEST"},"message":{"type":"string"}}}}},"RegisterRequest":{"type":"object","required":["agentAddress"],"description":"Self-serve agent registration. One of did or publicKey is required.","properties":{"did":{"type":"string","description":"A DID identifying the agent."},"publicKey":{"type":"string","description":"Alternative to did: a public key."},"agentAddress":{"type":"string","pattern":"^agoric1","minLength":40,"description":"The agent's Agoric bech32 address (agoric1…)."}}},"RegisterResponse":{"type":"object","properties":{"registered":{"type":"boolean"},"apiKey":{"type":"string","description":"The agent API key — use as the Bearer token for escrow calls. Returned once."},"agentAddress":{"type":"string"},"did":{"type":"string"},"txHash":{"type":["string","null"],"description":"On-chain registration tx, or null if it was skipped/failed (non-fatal)."},"feeGranted":{"type":"boolean","description":"Whether a devnet gas fee grant was issued."}}},"CreateEscrowRequest":{"type":"object","required":["payerAgentAddr","payeeAgentAddr","jobDescription","amount"],"properties":{"payerAgentAddr":{"type":"string","pattern":"^agoric1","description":"Payer agent address. The deal is funded on the payer's behalf."},"payeeAgentAddr":{"type":"string","pattern":"^agoric1","description":"Payee agent address. Receives payment on release."},"jobDescription":{"type":"string","description":"What the payee must deliver — the anchor for any later dispute resolution."},"amount":{"type":"integer","minimum":1,"description":"Amount to escrow, in utoyusdc (micro-units of devnet toyusdc; 1 toyusdc = 1,000,000). Devnet test tokens, not real USDC."},"releaseCondition":{"type":"string","enum":["TIMEOUT","ORACLE","HASH"],"description":"How the escrow releases. Defaults to TIMEOUT."},"timeoutSeconds":{"type":"integer","minimum":1,"description":"Optional release timeout window, in seconds."},"taskType":{"type":"string","description":"Optional task-type tag."},"acceptanceCriteria":{"type":"object","additionalProperties":true,"description":"Optional structured acceptance criteria."},"payeeMinCompletionRate":{"type":"number","description":"Optional minimum payee completion rate (reputation gate)."},"oracleAddress":{"type":"string","pattern":"^agoric1","description":"Required when releaseCondition is ORACLE."}}},"CreateEscrowResponse":{"type":"object","properties":{"txHash":{"type":"string"},"status":{"type":"string","enum":["CREATED"]},"vstoragePath":{"type":"string","example":"published.fidealai","description":"Where records are published. The escrow id is assigned async on chain — resolve it via GET /api/agent/escrows."}}},"ClaimRequest":{"type":"object","required":["escrowId","payeeAgentAddr","proof"],"properties":{"escrowId":{"type":"string","example":"ai-1"},"payeeAgentAddr":{"type":"string","pattern":"^agoric1"},"proof":{"type":"string","description":"Delivery proof: a URL, content hash, or short description."}}},"ClaimResponse":{"type":"object","properties":{"escrowId":{"type":"string"},"status":{"type":"string","enum":["CLAIM_PENDING"]},"txHash":{"type":"string"},"claimedAt":{"type":"integer","description":"Unix seconds."}}},"DisputeRequest":{"type":"object","required":["escrowId","payerAgentAddr","disputeCategory"],"properties":{"escrowId":{"type":"string"},"payerAgentAddr":{"type":"string","pattern":"^agoric1"},"disputeCategory":{"type":"string","enum":["NOT_DELIVERED","INCOMPLETE","DOES_NOT_MATCH","QUALITY","LATE","OTHER"]},"disputeStatement":{"type":"string","description":"Optional free-text explanation."}}},"DisputeResponse":{"type":"object","properties":{"escrowId":{"type":"string"},"status":{"type":"string","enum":["DISPUTED"]},"txHash":{"type":"string"},"disputedAt":{"type":"integer"}}},"RespondRequest":{"type":"object","required":["escrowId","payeeAgentAddr","responseType"],"description":"Payee's response to a dispute. CONCEDE_PARTIAL requires splitBps.","properties":{"escrowId":{"type":"string"},"payeeAgentAddr":{"type":"string","pattern":"^agoric1"},"responseType":{"type":"string","enum":["CONCEDE_FULL","CONCEDE_PARTIAL","COUNTER","REJECT"]},"responseStatement":{"type":"string"},"responseEvidence":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"content":{"type":"string"}}}},"resubmissionRef":{"type":"string"},"splitBps":{"type":"integer","minimum":1,"maximum":9999,"description":"Basis points to the payee. Required for CONCEDE_PARTIAL (1–9999)."}}},"RespondResponse":{"type":"object","properties":{"escrowId":{"type":"string"},"responseType":{"type":"string","enum":["CONCEDE_FULL","CONCEDE_PARTIAL","COUNTER","REJECT"]},"txHash":{"type":"string"},"respondedAt":{"type":"integer"}}},"AgentEscrowRecord":{"type":"object","properties":{"id":{"type":"string","example":"ai-1"},"status":{"type":"string","enum":["CREATED","CLAIM_PENDING","RESPONSE_PENDING","ESCALATED","AI_REVIEW","HUMAN_REVIEW","DISPUTED","RELEASED","REFUNDED","EXPIRED","SETTLED"]},"amount":{"type":["string","null"],"description":"Escrowed amount in utoyusdc (devnet toyusdc micro-units)."},"denom":{"type":["string","null"],"example":"ibc/toyusdc"},"payerAgentAddr":{"type":"string"},"payeeAgentAddr":{"type":"string"},"jobDescription":{"type":"string"},"releaseCondition":{"type":"string"},"createdAt":{"type":"integer"},"expiresAt":{"type":"integer"},"claimedAt":{"type":["integer","null"]},"releasedAt":{"type":["integer","null"]},"disputedAt":{"type":["integer","null"]},"disputeCategory":{"type":["string","null"]},"feeCollected":{"type":["string","null"]},"proof":{"type":["string","null"]},"aiResolution":{"description":"The dispute resolution once evaluated: a functional outcome of RELEASE, REFUND, or SPLIT with a basis-point allocation. Null until resolved.","type":["object","null"],"properties":{"resolutionType":{"type":"string","enum":["RELEASE","REFUND","SPLIT"]},"splitBps":{"type":"integer","minimum":0,"maximum":10000},"reasoning":{"type":"string"},"confidence":{"type":"string","enum":["HIGH","MEDIUM","LOW"]}}}}},"AgentEscrowList":{"type":"object","properties":{"address":{"type":"string"},"count":{"type":"integer"},"escrows":{"type":"array","items":{"$ref":"#/components/schemas/AgentEscrowRecord"}}}},"AgentReputationResponse":{"type":"object","properties":{"address":{"type":"string"},"reputation":{"type":"object","properties":{"agentAddr":{"type":"string"},"totalEscrows":{"type":"string"},"completedEscrows":{"type":"string"},"disputedEscrows":{"type":"string"},"completionRate":{"type":"string"},"disputeRate":{"type":"string"},"totalVolume":{"type":"string","description":"Cumulative escrowed volume in utoyusdc."},"lastActivity":{"type":"string"}}}}},"EvidenceItem":{"description":"A bare string, or a labeled artifact.","oneOf":[{"type":"string"},{"type":"object","required":["content"],"properties":{"label":{"type":"string"},"content":{"type":"string"}}}]},"AssessmentRequest":{"type":"object","required":["deal_description","deliverable","evidence"],"properties":{"deal_description":{"type":"string","maxLength":20000,"description":"The agreement / anchor terms."},"deliverable":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}],"description":"What was actually delivered."},"evidence":{"type":"object","properties":{"payer":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceItem"}},"payee":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceItem"}}}},"split_mode":{"type":"string","enum":["bps","fixed5"],"default":"bps"},"context":{"type":"object","properties":{"category":{"type":"string","enum":["NOT_DELIVERED","INCOMPLETE","DOES_NOT_MATCH","QUALITY","LATE","OTHER"]},"deadline":{"type":"string"},"amount":{"type":"string","description":"Context only — no funds move on the Verdict path."}}}}},"AssessmentResponse":{"type":"object","description":"A non-binding assessment of contract performance. It is not legal advice and moves no funds.","properties":{"assessment_id":{"type":"string","example":"ast_…"},"split":{"type":"object","description":"Suggested allocation in basis points.","properties":{"payer_bps":{"type":"integer","minimum":0,"maximum":10000},"payee_bps":{"type":"integer","minimum":0,"maximum":10000},"label":{"type":"string","enum":["FULL_PAYEE","MOSTLY_PAYEE","EVEN","MOSTLY_PAYER","FULL_PAYER"],"description":"Present only in fixed5 mode."}}},"confidence":{"type":"number","minimum":0,"maximum":1},"low_confidence":{"type":"boolean"},"review_required":{"type":"boolean","description":"True when the assessment should be seen by a human before it is relied on."},"provisional_notice":{"type":["string","null"],"description":"Present only when review_required is true."},"rationale":{"type":"string","description":"Short justification anchored to the parties' agreement."},"split_mode":{"type":"string","enum":["bps","fixed5"]},"assessed_at":{"type":"integer"},"disclaimer":{"type":"string"},"tosVersion":{"type":"string","example":"draft-2026-07"},"termsUrl":{"type":"string","format":"uri"}}},"KeyIssuanceRequest":{"type":"object","required":["email","acceptTerms"],"properties":{"email":{"type":"string","format":"email"},"acceptTerms":{"type":"boolean","enum":[true],"description":"Must be true — terms acceptance binds at issuance."},"tosVersion":{"type":"string","description":"Optional; if sent, must equal the current ToS version."}}},"KeyIssuanceResponse":{"type":"object","properties":{"api_key":{"type":"string","example":"vsk_…","description":"Returned once. Use as the Bearer token for POST /api/verdict."},"tier":{"type":"string","example":"sandbox"},"monthly_quota":{"type":"integer"},"email":{"type":"string"},"issued_at":{"type":"string","format":"date-time"},"tosVersion":{"type":"string"},"termsUrl":{"type":"string","format":"uri"},"warning":{"type":"string"}}}}},"paths":{"/api/agent/register":{"post":{"tags":["FiDealAI: agents"],"summary":"Register an agent (self-serve, no auth)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"200":{"description":"Already registered (idempotent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"201":{"description":"Registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"400":{"description":"Invalid body (did/publicKey or agentAddress missing/invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/reputation/{address}":{"get":{"tags":["FiDealAI: agents"],"summary":"Read an agent's reputation (no auth)","security":[],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^agoric1"}}],"responses":{"200":{"description":"Reputation record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentReputationResponse"}}}},"400":{"description":"Invalid address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No reputation data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrow/create":{"post":{"tags":["FiDealAI: escrow"],"summary":"Open and fund an escrow","description":"Creates AND funds the escrow in one on-chain step (the payer escrows the amount immediately — funding is atomic). The escrow id is assigned async on chain; resolve it via GET /api/agent/escrows.","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEscrowRequest"}}}},"responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEscrowResponse"}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Transaction failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrow/claim":{"post":{"tags":["FiDealAI: escrow"],"summary":"Claim delivery (payee)","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimRequest"}}}},"responses":{"200":{"description":"Claimed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimResponse"}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Transaction failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrow/dispute":{"post":{"tags":["FiDealAI: escrow"],"summary":"Dispute a claim (payer)","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeRequest"}}}},"responses":{"200":{"description":"Disputed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeResponse"}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Transaction failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrow/respond":{"post":{"tags":["FiDealAI: escrow"],"summary":"Respond to a dispute (payee)","security":[{"agentBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespondRequest"}}}},"responses":{"200":{"description":"Response submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RespondResponse"}}}},"400":{"description":"Invalid body (e.g. CONCEDE_PARTIAL without splitBps).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Escrow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Transaction failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrow/{id}":{"get":{"tags":["FiDealAI: escrow"],"summary":"Read one escrow by id","security":[{"agentBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"ai-1"}],"responses":{"200":{"description":"Escrow record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentEscrowRecord"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Escrow not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/escrows":{"get":{"tags":["FiDealAI: escrow"],"summary":"List an agent's escrows (newest first)","description":"Resolve a just-created escrow id, or review an agent's deals.","security":[{"agentBearer":[]}],"parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string","pattern":"^agoric1"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["payer","payee","any"]}}],"responses":{"200":{"description":"Escrow list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentEscrowList"}}}},"400":{"description":"Missing/invalid address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/verdict/keys":{"post":{"tags":["Verdict"],"summary":"Issue a sandbox key (no auth; terms acceptance required)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyIssuanceRequest"}}}},"responses":{"201":{"description":"Key issued (plaintext returned once).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyIssuanceResponse"}}}},"400":{"description":"Invalid email, or terms not accepted / version mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Issuance temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/verdict":{"post":{"tags":["Verdict"],"summary":"Produce an assessment","description":"Returns a non-binding assessment of contract performance (a suggested allocation, confidence, and rationale). No funds move.","security":[{"verdictBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentRequest"}}}},"responses":{"200":{"description":"Assessment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssessmentResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Monthly quota exhausted or per-minute rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Assessment temporarily unavailable; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Assessment service not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}