{"openapi":"3.1.0","info":{"title":"KushBitx AgentProof API","version":"1.5.0-rc.1","description":"Crypto security, payment verification and protected spend-policy checks for people, applications and AI agents. Evidence Chain is a release candidate; direct checks require restricted pilot activation.","termsOfService":"https://staging.kushbitx.com/terms","contact":{"name":"KushBitx","email":"admin@kushbitx.com"},"x-privacyPolicy":"https://staging.kushbitx.com/privacy"},"servers":[{"url":"https://staging.kushbitx.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"SpendGuard admin or agent key, depending on the endpoint."}},"schemas":{"EvidenceIntent":{"type":"object","additionalProperties":false,"required":["policyId","agentId","requestId","chain","asset","recipient","amount"],"properties":{"policyId":{"type":"string","pattern":"^sgp_[a-f0-9]{32}$"},"agentId":{"type":"string","minLength":1,"maxLength":80},"requestId":{"type":"string","minLength":1,"maxLength":120},"chain":{"const":"base"},"asset":{"const":"USDC"},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$"},"expectedFrom":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}},"EvidenceDecision":{"type":"object","required":["evidenceChainId","intentDigest","decision","reasons","policyRevision","executionAuthorized","replayed"],"properties":{"evidenceChainId":{"type":"string"},"intentDigest":{"type":"string"},"decision":{"enum":["APPROVE","BLOCK","HUMAN_APPROVAL"]},"reasons":{"type":"array","items":{"type":"string"}},"policyRevision":{"type":"integer"},"executionAuthorized":{"const":false},"replayed":{"type":"boolean"}}},"EvidenceChain":{"type":"object","required":["evidenceChainId","policyId","intent","intentDigest","events"],"properties":{"evidenceChainId":{"type":"string"},"policyId":{"type":"string"},"requestId":{"type":"string"},"intent":{"type":"object"},"intentDigest":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","required":["evidenceId","sequence","eventType","body"],"properties":{"evidenceId":{"type":"string"},"sequence":{"type":"integer"},"eventType":{"enum":["PRECHECK_COMPLETED","TRANSACTION_PREFLIGHT_COMPLETED","SETTLEMENT_RECONCILED"]},"body":{"type":"object"}}}}}},"EvidenceSummary":{"type":"object","required":["evidenceChainId","intentDigest","reconciliation","limitations"],"properties":{"evidenceChainId":{"type":"string"},"intentDigest":{"type":"string"},"preAuthorization":{"type":["object","null"]},"transactionPreflight":{"type":["object","null"]},"settlement":{"type":["object","null"]},"reconciliation":{"enum":["NOT_SUBMITTED","MATCH","MISMATCH","PENDING","FAILED","UNKNOWN"]},"limitations":{"type":"array","items":{"type":"string"}}}},"EvidenceSettlement":{"type":"object","required":["evidenceChainId","settlementEvidenceId","txHash","result","reason","mismatches","replayed"],"properties":{"evidenceChainId":{"type":"string"},"settlementEvidenceId":{"type":"string"},"txHash":{"type":"string"},"result":{"enum":["MATCH","MISMATCH","PENDING","FAILED","UNKNOWN"]},"reason":{"type":"string"},"mismatches":{"type":"array","items":{"type":"object"}},"replayed":{"type":"boolean"}}}}},"paths":{"/api/token-preview":{"post":{"operationId":"token_preview","summary":"Free Base token market preview","description":"Market identity and trading-pair data. No wallet, payment or API key required. Does not include security checks or a risk verdict. During a provider outage, source.stale may identify a prior snapshot. Metrics are available for at most 15 minutes; after that they are withheld and source.limited is true while token identity may remain available for up to 24 hours. Paid token reports never use this fallback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["base"],"description":"Blockchain network."},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Base token contract address."}},"required":["chain","address"],"additionalProperties":false},"example":{"chain":"base","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}},"responses":{"200":{"description":"Market preview with token, market, source freshness and paidReportAdds fields"},"400":{"description":"Invalid Base token address"},"404":{"description":"No Base trading pair found"},"429":{"description":"Per-source free preview limit reached; Retry-After indicates when to retry"},"502":{"description":"Market data provider unavailable"}}}},"/api/token-coverage":{"post":{"operationId":"token_coverage","summary":"Free data coverage check before payment","description":"Availability only, not a risk verdict. No wallet or payment required. Cached for up to 60 seconds; paid results may differ. A delivered incomplete report still costs 0.25 USDC.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["base"],"description":"Blockchain network."},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Base token contract address."}},"required":["chain","address"],"additionalProperties":false},"example":{"chain":"base","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}},"responses":{"200":{"description":"Per-category coverage, complete, checkedAt and fee disclosure"},"400":{"description":"Invalid input"},"404":{"description":"No trading pair"},"429":{"description":"Per-source free coverage limit reached; Retry-After indicates when to retry"},"502":{"description":"Provider unavailable"}}}},"/api/spendguard/evaluate":{"post":{"operationId":"spendguard_evaluate","summary":"Free SpendGuard policy preview","description":"Stateless advisory check for a proposed Base USDC payment. It does not hold keys, execute or authorize payment. Caller-supplied policy and risk signals must be enforced by a separate trusted signer or approval service. The response lists optional paid AgentProof evidence checks; none is invoked or charged automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["agentId","requestId","chain","asset","recipient","amount","policy"],"properties":{"agentId":{"type":"string"},"requestId":{"type":"string"},"chain":{"type":"string","enum":["base"]},"asset":{"type":"string","enum":["USDC"]},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string"},"policy":{"type":"object","additionalProperties":false,"required":["maxPerTransaction","remainingDailyBudget","requireHumanAbove","maxRepeats","allowedRecipients","blockUnknownRecipients"],"properties":{"maxPerTransaction":{"type":"string"},"remainingDailyBudget":{"type":"string"},"requireHumanAbove":{"type":"string"},"maxRepeats":{"type":"integer","minimum":1},"allowedRecipients":{"type":"array","items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"blockUnknownRecipients":{"type":"boolean"}}},"context":{"type":"object","additionalProperties":false,"properties":{"repeatCount":{"type":"integer","minimum":0},"agentProofDecision":{"type":"string","enum":["ALLOW","WARN","BLOCK","INCOMPLETE","UNKNOWN"]}}}}}}}},"responses":{"200":{"description":"APPROVE, BLOCK or HUMAN_APPROVAL advisory decision, plus optional paid evidence checks"},"400":{"description":"Invalid policy or proposed spend"},"429":{"description":"Per-source free evaluation limit reached; Retry-After indicates when to retry"}}}},"/api/spendguard/policies":{"post":{"operationId":"spendguard_create_policy","summary":"Create a protected 30-day pilot policy","description":"Stores spending rules outside the AI agent and returns separate one-time admin and agent credentials. Keys cannot be recovered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","agentId","policy"],"properties":{"name":{"type":"string"},"agentId":{"type":"string"},"policy":{"type":"object","required":["maxPerTransaction","dailyBudget","requireHumanAbove","maxRepeats","allowedRecipients","blockUnknownRecipients"]}}}}}},"responses":{"201":{"description":"Policy plus one-time admin and agent keys"},"400":{"description":"Invalid policy"},"429":{"description":"Free pilot creation limit reached"}}}},"/api/spendguard/policies/{policyId}":{"get":{"operationId":"spendguard_get_policy","summary":"Read a protected policy","security":[{"bearerAuth":[]}],"parameters":[{"name":"policyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Policy without secret hashes"},"401":{"description":"Admin key required"},"404":{"description":"Policy or key not found"}}},"put":{"operationId":"spendguard_update_policy","summary":"Replace a protected policy","security":[{"bearerAuth":[]}],"parameters":[{"name":"policyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated policy with incremented revision"},"401":{"description":"Admin key required"},"404":{"description":"Policy or key not found"}}}},"/api/spendguard/decisions":{"post":{"operationId":"spendguard_protected_decision","summary":"Evaluate against a protected server-side policy","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["policyId","requestId","agentId","chain","asset","recipient","amount"],"properties":{"policyId":{"type":"string"},"requestId":{"type":"string"},"agentId":{"type":"string"},"chain":{"type":"string","enum":["base"]},"asset":{"type":"string","enum":["USDC"]},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string"}}}}}},"responses":{"200":{"description":"Stored APPROVE, BLOCK or HUMAN_APPROVAL decision and receipt"},"401":{"description":"Agent key required"},"409":{"description":"Request ID conflict"}}}},"/api/spendguard/decisions/{decisionId}":{"get":{"operationId":"spendguard_get_decision","summary":"Retrieve a protected decision","security":[{"bearerAuth":[]}],"parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stored decision and receipt"},"404":{"description":"Decision or key not found"}}}},"/api/spendguard/decisions/{decisionId}/approve":{"post":{"operationId":"spendguard_approve_decision","summary":"Approve a HUMAN_APPROVAL decision","security":[{"bearerAuth":[]}],"parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Administrator-approved decision"},"409":{"description":"Policy revision, budget or status conflict"},"410":{"description":"Approval request expired"}}}},"/api/token-risk":{"post":{"operationId":"token_risk","summary":"Token Risk","description":"Screen a Base token for sellability, taxes, privileged controls, holder concentration and market risk. Payment: 0.25 USDC per delivered report via x402, including INCOMPLETE or negative results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["base"],"description":"Blockchain network."},"address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Base token contract address."}},"required":["chain","address"],"additionalProperties":false},"example":{"chain":"base","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}}}},"responses":{"200":{"description":"Paid result","content":{"application/json":{"example":{"verdict":{"decision":"INCOMPLETE","level":"unknown","score":null,"confidence":"limited"},"risk":{"coverage":{"ownership":"unavailable"},"breakdown":{"ownership":null}}}}}},"202":{"description":"Pending report or uncertain settlement. Restore the report; do not create another payment."},"400":{"description":"Invalid request"},"402":{"description":"PAYMENT-REQUIRED header contains the x402 payment challenge"},"409":{"description":"Authorization or report input conflict"},"502":{"description":"Upstream provider or settlement unavailable"},"503":{"description":"Durable report storage unavailable; no new payment requested"}}}},"/api/transaction-preflight":{"post":{"operationId":"transaction_preflight","summary":"Transaction Preflight","description":"Simulate an unsigned Base transaction and detect failed execution, dangerous approvals and destination risk signals. Payment: 0.05 USDC per delivered report via x402, including INCOMPLETE or negative results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["base"]},"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Optional sender used for simulation."},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Transaction destination."},"valueWei":{"type":"string","pattern":"^[0-9]+$","description":"Native ETH value in wei."},"data":{"type":"string","pattern":"^0x([a-fA-F0-9]{2})*$","description":"Unsigned calldata."}},"required":["chain","to"],"additionalProperties":false},"example":{"chain":"base","from":"0x0d68028d06af13379C872FEE032568B4Be712f22","to":"0x0d68028d06af13379C872FEE032568B4Be712f22","valueWei":"0","data":"0x"}}}},"responses":{"200":{"description":"Paid result","content":{"application/json":{"example":{"verdict":{"decision":"ALLOW","score":0,"confidence":"high"},"destination":{},"simulation":{},"findings":[]}}}},"202":{"description":"Pending report or uncertain settlement. Restore the report; do not create another payment."},"400":{"description":"Invalid request"},"402":{"description":"PAYMENT-REQUIRED header contains the x402 payment challenge"},"409":{"description":"Authorization or report input conflict"},"502":{"description":"Upstream provider or settlement unavailable"},"503":{"description":"Durable report storage unavailable; no new payment requested"}}}},"/api/verify-payment":{"post":{"operationId":"verify_payment","summary":"Payment Proof","description":"Verify an onchain Base USDC payment, its recipient, amount, status and confirmations. Payment: 0.01 USDC per delivered report via x402, including INCOMPLETE or negative results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string","enum":["base"]},"txHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"expectedTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"expectedFrom":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"expectedAmount":{"type":"string","pattern":"^[0-9]+(\\.[0-9]{1,6})?$","description":"Expected USDC amount."}},"required":["chain","txHash","expectedTo","expectedAmount"],"additionalProperties":false},"example":{"chain":"base","txHash":"0x0000000000000000000000000000000000000000000000000000000000000000","expectedTo":"0x0d68028d06af13379C872FEE032568B4Be712f22","expectedAmount":"1.00"}}}},"responses":{"200":{"description":"Paid result","content":{"application/json":{"example":{"verdict":{"decision":"VERIFIED","verified":true},"confirmations":1,"transfers":[]}}}},"202":{"description":"Pending report or uncertain settlement. Restore the report; do not create another payment."},"400":{"description":"Invalid request"},"402":{"description":"PAYMENT-REQUIRED header contains the x402 payment challenge"},"409":{"description":"Authorization or report input conflict"},"502":{"description":"Upstream provider or settlement unavailable"},"503":{"description":"Durable report storage unavailable; no new payment requested"}}}},"/api/agentproof-quick-check":{"get":{"operationId":"agentproof_quick_check","summary":"AgentProof Quick Check","description":"A deterministic Base chain identity and official USDC contract-presence check. No request body. Not a token-risk report, transaction simulation, or payment proof. Payment: 0.001 USDC per delivered report via x402, including INCOMPLETE or negative results.","responses":{"200":{"description":"Paid result","content":{"application/json":{"example":{"service":"agentproof-quick-check","network":"eip155:8453","status":"PASS","checks":{"chainId":{"expected":8453,"observed":8453,"match":true},"usdcContract":{"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","codePresent":true}}}}}},"202":{"description":"Pending report or uncertain settlement. Restore the report; do not create another payment."},"400":{"description":"Invalid request"},"402":{"description":"PAYMENT-REQUIRED header contains the x402 payment challenge"},"409":{"description":"Authorization or report input conflict"},"502":{"description":"Upstream provider or settlement unavailable"},"503":{"description":"Durable report storage unavailable; no new payment requested"}}}},"/api/orders":{"post":{"summary":"Prepare recovery before signing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","input"],"properties":{"path":{"type":"string","enum":["/api/token-risk","/api/transaction-preflight","/api/verify-payment","/api/agentproof-quick-check"]},"input":{"type":"object"}}}}}},"responses":{"201":{"description":"Private id, key and expiresAt. Store before payment. Pass Report-Id and Recovery-Key with the paid request."}}}},"/api/orders/recover":{"post":{"summary":"Restore a saved report without payment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","key"],"properties":{"id":{"type":"string"},"key":{"type":"string"},"txHash":{"type":"string","description":"Optional settlement transaction hash for interrupted payments"}}}}}},"responses":{"200":{"description":"Original report and receipt"},"202":{"description":"Pending or not yet paid. Do not pay again."},"404":{"description":"Unknown report or incorrect key"},"410":{"description":"Recovery period expired"}}}},"/api/pilot-leads":{"post":{"summary":"Request a SpendGuard company pilot","description":"Stores a production-integration lead for a one-time 49 USDC bounded integration/validation pilot. Submission does not create an order or authorize payment. Contact and workflow data are retained for 90 days.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","company","monthlyDecisions","needs"],"properties":{"email":{"type":"string","format":"email"},"company":{"type":"string","maxLength":120},"monthlyDecisions":{"type":"string","enum":["under-1k","1k-10k","10k-100k","over-100k","not-sure"]},"needs":{"type":"string","minLength":10,"maxLength":1200}},"additionalProperties":false}}}},"responses":{"201":{"description":"Pilot request received"},"400":{"description":"Invalid request"},"429":{"description":"Rate limit reached"}}}},"/api/evidence-chains":{"post":{"operationId":"evidence_chain_create","summary":"Create a protected Evidence Chain (release candidate)","description":"Requires the protected policy agent key. Intent is immutable; retry identical input with the same policyId/requestId. A material input change returns 409. This stores a policy decision, never authorizes or executes a payment. No paid evidence check runs automatically.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceIntent"}}}},"responses":{"200":{"description":"Exact retry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceDecision"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceDecision"}}}},"400":{"description":"Invalid input"},"401":{"description":"Agent bearer key required"},"403":{"description":"Agent or policy is inactive"},"404":{"description":"Feature disabled, chain unavailable or incorrect policy key"},"409":{"description":"Intent conflict"},"410":{"description":"Protected-policy access has expired"},"429":{"description":"Request limit reached"},"503":{"description":"Storage/provider unavailable or direct pilot checks not enabled"}}}},"/api/evidence-chains/{evidenceChainId}":{"get":{"operationId":"evidence_chain_read","summary":"Read immutable intent and appended evidence","security":[{"bearerAuth":[]}],"parameters":[{"name":"evidenceChainId","in":"path","required":true,"schema":{"type":"string","pattern":"^ec_[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Policy-authorized chain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceChain"}}}},"400":{"description":"Invalid input"},"401":{"description":"Agent bearer key required"},"403":{"description":"Agent or policy is inactive"},"404":{"description":"Feature disabled, chain unavailable or incorrect policy key"},"410":{"description":"Protected-policy access has expired"},"429":{"description":"Request limit reached"},"503":{"description":"Storage/provider unavailable or direct pilot checks not enabled"}}}},"/api/evidence-chains/{evidenceChainId}/summary":{"get":{"operationId":"evidence_chain_summary","summary":"Read decisions, reconciliation and limitations","security":[{"bearerAuth":[]}],"parameters":[{"name":"evidenceChainId","in":"path","required":true,"schema":{"type":"string","pattern":"^ec_[a-f0-9]{32}$"}}],"responses":{"200":{"description":"Summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceSummary"}}}},"400":{"description":"Invalid input"},"401":{"description":"Agent bearer key required"},"403":{"description":"Agent or policy is inactive"},"404":{"description":"Feature disabled, chain unavailable or incorrect policy key"},"410":{"description":"Protected-policy access has expired"},"429":{"description":"Request limit reached"},"503":{"description":"Storage/provider unavailable or direct pilot checks not enabled"}}}},"/api/evidence-chains/{evidenceChainId}/preflight":{"post":{"operationId":"evidence_chain_preflight","summary":"Attach an unsigned transaction check (restricted pilot)","description":"Disabled for general access. Requires an explicitly enabled pilot policy, in addition to its agent key. Existing paid Transaction Preflight remains 0.05 USDC. The unsigned input has its own digest; callers must verify it represents their intended transaction. No signature or execution occurs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"evidenceChainId","in":"path","required":true,"schema":{"type":"string","pattern":"^ec_[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["chain","to"],"properties":{"chain":{"const":"base"},"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"valueWei":{"type":"string","pattern":"^[0-9]+$"},"data":{"type":"string","pattern":"^0x([a-fA-F0-9]{2})*$"}}}}}},"responses":{"200":{"description":"Preflight evidence and verdict"},"400":{"description":"Invalid input"},"401":{"description":"Agent bearer key required"},"403":{"description":"Agent or policy is inactive"},"404":{"description":"Feature disabled, chain unavailable or incorrect policy key"},"409":{"description":"Different preflight already attached"},"410":{"description":"Protected-policy access has expired"},"429":{"description":"Request limit reached"},"503":{"description":"Storage/provider unavailable or direct pilot checks not enabled"}}}},"/api/evidence-chains/{evidenceChainId}/settlement":{"post":{"operationId":"evidence_chain_settlement","summary":"Reconcile an existing Base transaction (restricted pilot)","description":"Disabled for general access. Requires an explicitly enabled pilot policy. Reads an existing transaction only. Expected recipient, amount and optional sender come from immutable intent. Existing paid Payment Proof remains 0.01 USDC. UNKNOWN is not verification. MATCH describes an observed transfer, not permission to pay.","security":[{"bearerAuth":[]}],"parameters":[{"name":"evidenceChainId","in":"path","required":true,"schema":{"type":"string","pattern":"^ec_[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["txHash"],"properties":{"txHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}}}}}},"responses":{"200":{"description":"Reconciliation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceSettlement"}}}},"400":{"description":"Invalid input"},"401":{"description":"Agent bearer key required"},"403":{"description":"Agent or policy is inactive"},"404":{"description":"Feature disabled, chain unavailable or incorrect policy key"},"409":{"description":"Conflicting concurrent evidence; read the existing chain"},"410":{"description":"Protected-policy access has expired"},"429":{"description":"Request limit reached"},"503":{"description":"Storage/provider unavailable or direct pilot checks not enabled"}}}}}}