{"openapi":"3.1.0","info":{"title":"SafeRoute x402 API","version":"0.15.0","description":"Autonomous Base swap safety checks and noncustodial quotes with buyer-controlled signing and execution verification."},"servers":[{"url":"https://api.usesaferoute.com"}],"paths":{"/v1/high-notional-policy":{"get":{"summary":"Read the feature-gated high-notional policy tiers","description":"Publishes the $500 public tier and evidence requirements for $10k Pro, $100k Advanced, and $1M+ Enterprise policy evaluation.","responses":{"200":{"description":"High-notional policy and feature status"}}}},"/v1/high-notional-policy/evaluate":{"post":{"summary":"Evaluate a high-notional Base transaction policy","description":"Returns ALLOW, REVIEW, or BLOCK plus bounded slicing guidance. It never signs, broadcasts, or returns executable calldata.","responses":{"200":{"description":"Policy decision and evidence"},"400":{"description":"Invalid evaluation input"}}}},"/v1/agent-payment-route":{"post":{"summary":"Prepare a buffered exact-buy Base USDC funding route","description":"$0.05 USDC via x402. Funds a payer-owned target covering the payment and optional buffer; the buyer confirms it and performs one standard x402 retry.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"quoteMode":{"type":"string","const":"exactBuy"},"sellToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"buyToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maximumSellAmount":{"type":"string","pattern":"^\\d+$"},"taker":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"executionMode":{"type":"string","const":"standard"},"paymentRequirements":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","const":"eip155:8453"},"asset":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxTimeoutSeconds":{"type":"integer","minimum":1,"maximum":3600},"extra":{"type":["object","null"]}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]},"paymentResource":{"type":"object","properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"description":{"type":"string","maxLength":500},"mimeType":{"type":"string","maxLength":128}},"required":["url"]},"paymentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"targetUsdcBalance":{"type":"string","pattern":"^\\d+$","description":"Optional post-funding Base USDC balance target. Must cover the current payment and stay within the active launch cap."},"deadline":{"type":"string","format":"date-time","description":"Optional route deadline; defaults to the requirement timeout and cannot exceed it."},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["quoteMode","sellToken","buyToken","maximumSellAmount","taker","recipient","executionMode","paymentRequirements","paymentResource","paymentId"]},"example":{"quoteMode":"exactBuy","sellToken":"0x4200000000000000000000000000000000000006","buyToken":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","maximumSellAmount":"1000000000000000","taker":"0x1111111111111111111111111111111111111111","recipient":"0x1111111111111111111111111111111111111111","executionMode":"standard","paymentRequirements":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000000","payTo":"0x2222222222222222222222222222222222222222","maxTimeoutSeconds":300,"extra":{}},"paymentResource":{"url":"https://merchant.example/report"},"paymentId":"srpay_example_1234567890","targetUsdcBalance":"5000000"}}}},"responses":{"200":{"description":"Exact-buy payment route prepared"},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"409":{"description":"Payment identifier conflict or replay"},"422":{"description":"Safety policy rejected the route"},"502":{"description":"Quote provider failure"}}}},"/v1/agent-payment-route/bootstrap/challenge":{"post":{"summary":"Create a signed-wallet bootstrap challenge","description":"Free, rate-limited EIP-191 challenge for a payer with insufficient USDC. The request commits to one x402 requirement and one bounded funding route.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"fundingToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maximumSellAmount":{"type":"string","pattern":"^\\d+$"},"targetUsdcBalance":{"type":"string","pattern":"^\\d+$","description":"Optional buffered Base USDC balance target."},"paymentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"paymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer","const":2},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"description":{"type":"string","maxLength":500},"mimeType":{"type":"string","maxLength":128}},"required":["url"]},"accepts":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","const":"eip155:8453"},"asset":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxTimeoutSeconds":{"type":"integer","minimum":1,"maximum":3600},"extra":{"type":["object","null"]}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]}}},"required":["x402Version","resource","accepts"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["payer","fundingToken","maximumSellAmount","paymentId","paymentRequired"]}}}},"responses":{"200":{"description":"Wallet signature challenge issued"},"400":{"description":"Invalid request"},"403":{"description":"Payer is outside the canary allowlist"},"422":{"description":"Unsupported payment requirement"},"429":{"description":"Rate limit exceeded"}}}},"/v1/agent-payment-route/bootstrap":{"post":{"summary":"Redeem a signed-wallet bootstrap challenge","description":"Verifies the payer's EIP-191 signature and prepares one buffered funding route. No upfront x402 fee; only the disclosed 20-bps executed AutoFund swap fee applies.","responses":{"200":{"description":"Shortfall funding route prepared"},"401":{"description":"Wallet signature invalid"},"409":{"description":"Challenge expired or consumed"},"422":{"description":"Safety policy rejected the route"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Safety circuit open"}}}},"/v1/agent-payment-route/verify":{"post":{"summary":"Verify a mined SafeRoute Pay execution","responses":{"200":{"description":"Payment execution verified"},"422":{"description":"Execution differs from signed intent"}}}},"/v1/quote":{"post":{"summary":"Buy a safety-checked Base swap quote","description":"$0.01 USDC via x402. Returns an unsigned transaction or buyer-signable gasless payload; SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"],"description":"Approved Base sell-token symbol"},"to":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"],"description":"Approved Base buy-token symbol"},"amount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Human-readable sell amount, capped at $500 USDC equivalent"},"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Buyer-controlled taker wallet"},"executionMode":{"type":"string","enum":["standard","gasless"],"default":"standard"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["from","to","amount","wallet"]},"example":{"from":"USDC","to":"WETH","amount":"25","wallet":"0x1111111111111111111111111111111111111111","executionMode":"standard","sourceAgentId":"buyer-agent-id","referralCode":"PARTNER_CODE","intentId":"intent_unique_1234567890"}}}},"responses":{"200":{"description":"Safe quote created","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"quoteId":{"type":"string","format":"uuid"},"chainId":{"type":"integer","const":8453},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"sellToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"buyToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"sellAmount":{"type":"string","pattern":"^\\d+$"},"buyAmount":{"type":"string","pattern":"^\\d+$"},"minBuyAmount":{"type":"string","pattern":"^\\d+$"},"feeBps":{"type":"integer","const":10},"feeAmount":{"type":"string","pattern":"^\\d+$"},"feeToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"executionMode":{"type":"string","enum":["standard","gasless"]},"usdNotional":{"type":"string","pattern":"^\\d+$"},"approvalRequired":{"type":"boolean"},"taker":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"approvalSpender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"payloadHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"transactionDataHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"transaction":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"data":{"type":"string","pattern":"^0x[a-fA-F0-9]*$"},"value":{"type":"string","pattern":"^\\d+$"},"gas":{"type":"string","pattern":"^\\d+$"},"gasPrice":{"type":"string","pattern":"^\\d+$"}},"required":["to","data","value"]},"gasless":{"type":"object","properties":{"trade":{"type":"object"},"target":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"relaySubmitEndpoint":{"type":"string","format":"uri"},"relayRequiresBuyerZeroXApiKey":{"type":"boolean","const":true},"buyerMustSignAndSubmit":{"type":"boolean","const":true}},"required":["trade","target","relaySubmitEndpoint","relayRequiresBuyerZeroXApiKey","buyerMustSignAndSubmit"]},"simulation":{"type":"object","additionalProperties":false,"properties":{"status":{"type":"string","enum":["passed","skipped","failed"]},"reason":{"type":"string"}},"required":["status"]},"receipt":{"type":"object","additionalProperties":false,"properties":{"quoteId":{"type":"string","format":"uuid"},"chainId":{"type":"integer","const":8453},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"sellToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"buyToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"sellAmount":{"type":"string","pattern":"^\\d+$"},"buyAmount":{"type":"string","pattern":"^\\d+$"},"taker":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"executionMode":{"type":"string","enum":["standard","gasless"]},"usdcNotional":{"type":"string","pattern":"^\\d+$"},"feeBps":{"type":"integer","const":10},"feeRecipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"feeAmount":{"type":"string","pattern":"^\\d+$"},"feeToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"payloadHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"transactionTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"transactionValue":{"type":"string","pattern":"^\\d+$"},"gaslessTarget":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"attribution":{"type":"object","additionalProperties":false,"properties":{"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}}}},"required":["quoteId","chainId","createdAt","expiresAt","sellToken","buyToken","sellAmount","buyAmount","taker","executionMode","usdcNotional","feeBps","feeRecipient","payloadHash"]},"receiptSignature":{"type":"string","pattern":"^[a-fA-F0-9]{64}$"},"inputFormat":{"type":"string","enum":["simple","advanced"]}},"required":["quoteId","chainId","createdAt","expiresAt","sellToken","buyToken","sellAmount","buyAmount","feeBps","executionMode","usdNotional","approvalRequired","taker","payloadHash","simulation","receipt","receiptSignature","inputFormat"],"anyOf":[{"required":["transaction"]},{"required":["gasless"]}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"402":{"description":"x402 payment required or settlement failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"409":{"description":"Payment identifier was reused for different input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"422":{"description":"SafeRoute policy rejected the quote","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"502":{"description":"Upstream quote provider failed; payment is canceled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}}}}},"/v1/swap-safety-check":{"post":{"summary":"Buy a wallet-free Base swap safety preflight","description":"$0.001 USDC via x402. Validates the token pair and $500 cap, checks indicative liquidity, estimates the fee and output, and identifies the next action without requesting a wallet or returning executable calldata.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"],"description":"Approved Base sell-token symbol"},"to":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"],"description":"Approved Base buy-token symbol; must differ from from"},"amount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$","description":"Human-readable sell amount, capped at $500 USDC equivalent"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["from","to","amount"]},"example":{"from":"USDC","to":"WETH","amount":"25","sourceAgentId":"buyer-agent-id","intentId":"intent_unique_1234567890"}}}},"responses":{"200":{"description":"Eligible swap preflight created","content":{"application/json":{"schema":{"type":"object","properties":{"checkId":{"type":"string","format":"uuid"},"status":{"type":"string","const":"eligible"},"chainId":{"type":"integer","const":8453},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"pair":{"type":"object","properties":{"from":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"to":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"sellToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"buyToken":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"required":["from","to","sellToken","buyToken"]},"amount":{"type":"object","properties":{"human":{"type":"string"},"raw":{"type":"string","pattern":"^\\d+$"},"usdcEquivalentRaw":{"type":"string","pattern":"^\\d+$"}},"required":["human","raw","usdcEquivalentRaw"]},"estimatedOutput":{"type":"object","properties":{"raw":{"type":"string","pattern":"^\\d+$"},"minimumRaw":{"type":"string","pattern":"^\\d+$"}},"required":["raw"]},"tokenVerification":{"type":"object","properties":{"sellTokenApproved":{"type":"boolean","const":true},"buyTokenApproved":{"type":"boolean","const":true},"sellTokenDecimals":{"type":"integer","minimum":0},"buyTokenDecimals":{"type":"integer","minimum":0}},"required":["sellTokenApproved","buyTokenApproved","sellTokenDecimals","buyTokenDecimals"]},"liquidity":{"type":"object","properties":{"available":{"type":"boolean","const":true},"sources":{"type":"array","items":{"type":"string"}}},"required":["available","sources"]},"priceImpact":{"type":"object","properties":{"status":{"type":"string","const":"checked_on_full_quote"},"warning":{"type":"string"}},"required":["status","warning"]},"allowance":{"type":"object","properties":{"status":{"type":"string","const":"wallet_required_for_check"}},"required":["status"]},"expectedSafeRouteFee":{"type":"object","properties":{"bps":{"type":"integer","const":10},"amountRaw":{"type":"string","pattern":"^\\d+$"},"token":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"indicative":{"type":"boolean","const":true}},"required":["bps","amountRaw","token","indicative"]},"warnings":{"type":"array","items":{"type":"string"}},"nextAction":{"type":"object","properties":{"method":{"type":"string","const":"POST"},"endpoint":{"type":"string","format":"uri"},"price":{"type":"string","const":"$0.01"},"requiredAdditionalField":{"type":"string","const":"wallet"}},"required":["method","endpoint","price","requiredAdditionalField"]},"attribution":{"type":"object","additionalProperties":false,"properties":{"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}}}},"required":["checkId","status","chainId","createdAt","expiresAt","pair","amount","estimatedOutput","tokenVerification","liquidity","priceImpact","allowance","expectedSafeRouteFee","warnings","nextAction"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"402":{"description":"x402 payment required or settlement failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"409":{"description":"Payment identifier was reused for different input","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"422":{"description":"SafeRoute policy rejected the preflight","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}},"502":{"description":"Upstream price provider failed; payment is canceled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"type":"object"}}},"required":["error","code"]}}}}}}},"/v1/proof":{"post":{"summary":"Return a signed machine-readable ALLOW, BLOCK, or REVIEW receipt before a Base trade, token interaction, or transaction signing.","description":"$0.05 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","const":"trade"},"from":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"to":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"amount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"executionMode":{"type":"string","const":"standard"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["action","from","to","amount","wallet"]},{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","const":"transaction"},"transaction":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"data":{"type":"string","pattern":"^0x[a-fA-F0-9]+$"},"value":{"type":"string","pattern":"^\\d+$"}},"required":["from","to","data"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["action","transaction"]},{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","const":"token"},"token":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["action","token"]}]},"example":{"action":"trade","from":"USDC","to":"WETH","amount":"25","wallet":"0x1111111111111111111111111111111111111111","executionMode":"standard","sourceAgentId":"buyer-agent-id","referralCode":"PARTNER_CODE","intentId":"intent_unique_1234567890"}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/wallet-risk-check":{"post":{"summary":"Check a Base wallet's account type, activity nonce, and native balance, returning an honest ALLOW or REVIEW structural-risk verdict.","description":"$0.01 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["wallet"]},"example":{"wallet":"0x1111111111111111111111111111111111111111"}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/token-risk-check":{"post":{"summary":"Verify an approved Base token against SafeRoute's locked registry, bytecode, address, and live route liquidity.","description":"$0.03 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["token"]},"example":{"token":"AERO"}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/transaction-preflight":{"post":{"summary":"Decode and simulate an approved Base ERC-20 transfer or approval, or SafeRoute's exact official ERC-8004 registration, before buyer-controlled signing.","description":"$0.05 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"transaction":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"to":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"data":{"type":"string","pattern":"^0x[a-fA-F0-9]*$"},"value":{"type":"string","pattern":"^\\d+$","default":"0"}},"required":["from","to","data"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["transaction"]},"example":{"transaction":{"from":"0x1111111111111111111111111111111111111111","to":"0x833589fCD6eDb6E08f4C7C32D4f71b54bdA02913","data":"0xa9059cbb00000000000000000000000022222222222222222222222222222222222222220000000000000000000000000000000000000000000000000000000000000001","value":"0"}}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/token-transfer":{"post":{"summary":"Validate and simulate a bounded approved-token transfer, then return unsigned calldata for the buyer to sign.","description":"$0.10 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"amount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"sender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["token","amount","sender","recipient"]},"example":{"token":"USDC","amount":"12.50","sender":"0x1111111111111111111111111111111111111111","recipient":"0x2222222222222222222222222222222222222222"}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/trade-guard":{"post":{"summary":"One pre-sign verdict combining approved-token checks, route economics, policy limits, a firm quote, and Base simulation.","description":"$0.49 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"from":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"to":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"amount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"executionMode":{"type":"string","const":"standard","default":"standard"},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["from","to","amount","wallet"]},"example":{"from":"USDC","to":"WETH","amount":"25","wallet":"0x1111111111111111111111111111111111111111","executionMode":"standard"}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/post-tx-verify":{"post":{"summary":"Compare a mined Base transaction with declared intent and report output, slippage, recipient, approval changes, and anomalies.","description":"$0.05 USDC via x402. SafeRoute never signs or broadcasts.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"transactionHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"},"intent":{"type":"object","additionalProperties":false,"properties":{"sender":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"recipient":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"sellToken":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"buyToken":{"type":"string","enum":["USDC","WETH","EURC","CBETH","CBBTC","VIRTUAL","AERO"]},"sellAmount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"minimumBuyAmount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"expectedBuyAmount":{"type":"string","pattern":"^\\d+(?:\\.\\d+)?$"},"expectedTarget":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"expectedCalldataHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"required":["sender","recipient","sellToken","buyToken","sellAmount","minimumBuyAmount"]},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["transactionHash","intent"]},"example":{"transactionHash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","intent":{"sender":"0x1111111111111111111111111111111111111111","recipient":"0x1111111111111111111111111111111111111111","sellToken":"USDC","buyToken":"WETH","sellAmount":"25","minimumBuyAmount":"0.005"}}}}},"responses":{"200":{"description":"SafeRoute analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string"}},"required":["status","service"]}}}},"400":{"description":"Invalid request"},"402":{"description":"x402 payment required"},"422":{"description":"SafeRoute policy rejected the request"},"502":{"description":"Upstream provider failure"}}}},"/v1/protect-payment":{"post":{"summary":"Protect an x402 payment through one automatic API","description":"Free and rate-limited. Returns a signed pre-payment decision, binds a duplicate-safe payment ID, explains policy risk, and optionally verifies mined Base-USDC settlement. The buyer retains signing and payment control.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"idempotencyKey":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9._:-]+$"},"payment":{"type":"object","additionalProperties":false,"properties":{"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"paymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"description":{"type":"string","maxLength":500},"mimeType":{"type":"string","maxLength":128}},"required":["url"]},"accepts":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","const":"eip155:8453"},"asset":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxTimeoutSeconds":{"type":"integer","minimum":1,"maximum":3600},"extra":{"type":["object","null"]}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]}}},"required":["x402Version","resource","accepts"]},"policy":{"type":"object","additionalProperties":false,"properties":{"maxAmountAtomic":{"type":"string","pattern":"^\\d+$"},"reviewAboveAmountAtomic":{"type":"string","pattern":"^\\d+$"},"allowedPayees":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"blockedPayees":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"allowedHosts":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":253}}}},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["payer","paymentRequired"]},"settlement":{"type":"object","additionalProperties":false,"properties":{"paymentResponseHeader":{"type":"string","minLength":1,"maxLength":8192},"transactionHash":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$"}},"anyOf":[{"required":["paymentResponseHeader"]},{"required":["transactionHash"]}]}},"required":["idempotencyKey","payment"]},"example":{"idempotencyKey":"merchant-order-123","payment":{"payer":"0x1111111111111111111111111111111111111111","paymentRequired":{"x402Version":2,"resource":{"url":"https://merchant.example/report"},"accepts":[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4C7C32D4f71b54bdA02913","amount":"1000000","payTo":"0x2222222222222222222222222222222222222222","maxTimeoutSeconds":300,"extra":{}}]},"policy":{"maxAmountAtomic":"10000000","allowedHosts":["merchant.example"]}}}}}},"responses":{"200":{"description":"Unified payment protection result"},"400":{"description":"Invalid request or evidence"},"409":{"description":"Idempotency conflict"},"422":{"description":"Invalid settlement authorization"},"429":{"description":"Rate limit exceeded"}}}},"/v1/payment-control/guard":{"post":{"summary":"Guard an x402 payment before the buyer pays","description":"Free and rate-limited. Binds one buyer-generated payment ID to an exact Base USDC requirement and policy, then returns a signed ALLOW, BLOCK, or REVIEW receipt.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"paymentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"},"payer":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"paymentRequired":{"type":"object","properties":{"x402Version":{"type":"integer"},"resource":{"type":"object","properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"description":{"type":"string","maxLength":500},"mimeType":{"type":"string","maxLength":128}},"required":["url"]},"accepts":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","const":"exact"},"network":{"type":"string","const":"eip155:8453"},"asset":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"amount":{"type":"string","pattern":"^\\d+$"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"maxTimeoutSeconds":{"type":"integer","minimum":1,"maximum":3600},"extra":{"type":["object","null"]}},"required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"]}}},"required":["x402Version","resource","accepts"]},"policy":{"type":"object","additionalProperties":false,"properties":{"maxAmountAtomic":{"type":"string","pattern":"^\\d+$"},"reviewAboveAmountAtomic":{"type":"string","pattern":"^\\d+$"},"allowedPayees":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"blockedPayees":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}},"allowedHosts":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":253}}}},"sourceAgentId":{"type":"string","minLength":1,"maxLength":128},"referralCode":{"type":"string","minLength":3,"maxLength":64,"pattern":"^[a-zA-Z0-9_-]+$"},"intentId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["paymentId","payer","paymentRequired"]},"example":{"paymentId":"srguard_example_1234567890","payer":"0x1111111111111111111111111111111111111111","paymentRequired":{"x402Version":2,"resource":{"url":"https://merchant.example/report"},"accepts":[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4C7C32D4f71b54bdA02913","amount":"1000000","payTo":"0x2222222222222222222222222222222222222222","maxTimeoutSeconds":300,"extra":{}}]},"policy":{"maxAmountAtomic":"10000000","allowedHosts":["merchant.example"]}}}}},"responses":{"200":{"description":"Signed payment guard receipt"},"400":{"description":"Invalid request"},"409":{"description":"Payment ID conflict"},"429":{"description":"Rate limit exceeded"}}}},"/v1/payment-control/reconcile":{"post":{"summary":"Verify and reconcile a guarded x402 settlement","description":"Free and rate-limited. Verifies the signed guard receipt, PAYMENT-RESPONSE, and exact mined Base USDC Transfer before marking settlement complete or retry-safe.","responses":{"200":{"description":"Signed reconciliation receipt"},"400":{"description":"Invalid settlement evidence"},"404":{"description":"Guard record not found"},"409":{"description":"Settlement conflict"},"422":{"description":"Invalid or non-ALLOW guard"},"429":{"description":"Rate limit exceeded"}}}},"/v1/payment-control/status":{"get":{"summary":"Read aggregate payment-control telemetry","responses":{"200":{"description":"Durable aggregate guard and settlement counts"}}}},"/v1/executions/verify":{"post":{"summary":"Verify a standard-mode SafeRoute execution","description":"Free verification of receipt signature, sender, calldata, target, value, expiry, success, and disclosed fee transfer.","responses":{"200":{"description":"Execution verified"},"400":{"description":"Invalid proof"},"404":{"description":"Transaction not found"},"422":{"description":"Execution does not match the signed quote"},"429":{"description":"Rate limit exceeded"}}}}}}