{"openapi":"3.1.0","info":{"title":"OwnPay Canonical API","version":"1.0.0","description":"Universal Payment Rails & Control Plane for Humans and Autonomous AI Agents on Base L2.\n\n**Revenue Model:** 100% Transaction-Based ($0/mo, $0/yr). Fee tiers apply per settled transaction.\n\n**Environments:**\n- Sandbox / Testnet: Base Sepolia (`84532`) using `own_test_...` keys.\n- Live / Production: Base Mainnet (`8453`) using `own_live_...` keys.","contact":{"name":"OwnPay Developer Platform","url":"https://ownpay.dev"}},"servers":[{"url":"https://api.ownpay.dev","description":"Canonical Production API Host (Base Mainnet 8453)"},{"url":"http://localhost:3000","description":"Local Development & Sandbox Engine"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"own_live_* / own_test_*","description":"Authenticate using an OwnPay API key in the format: `Bearer own_live_...` or `Bearer own_test_...`"},"AgentKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"own_agent_*","description":"Authenticate using an autonomous AI Agent API key: `Bearer own_agent_...`"}},"schemas":{"ApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"code":{"type":"string"},"data":{"type":"object"}},"required":["success"]},"PaymentIntent":{"type":"object","properties":{"intent_id":{"type":"string","format":"uuid"},"order_id":{"type":"string"},"payment_address":{"type":"string"},"usdc_amount":{"type":"number"},"fiat_amount":{"type":"number"},"fiat_currency":{"type":"string"},"exchange_rate":{"type":"number"},"qr_data":{"type":"string"},"status":{"type":"string","enum":["PENDING","CONFIRMED","EXPIRED"]},"network":{"type":"string"},"chain_id":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}},"Agent":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["SANDBOX","ACTIVE","PAUSED","FROZEN","REVOKED"]},"environment":{"type":"string","enum":["sandbox","live"]},"walletAddress":{"type":"string"},"walletType":{"type":"string","enum":["smart_account","eoa","delegated"]},"defaultChain":{"type":"string"},"defaultToken":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastActivityAt":{"type":"string","format":"date-time","nullable":true}}},"AgentPolicy":{"type":"object","properties":{"maxPerTransaction":{"type":"number","description":"Max spend allowed per single autonomous payment in USDC"},"dailyLimit":{"type":"number","description":"24-hour aggregate spending limit in USDC"},"monthlyLimit":{"type":"number","description":"30-day aggregate spending limit in USDC"},"allowedTokens":{"type":"array","items":{"type":"string"}},"allowedChains":{"type":"array","items":{"type":"string"}},"allowedRecipients":{"type":"array","items":{"type":"string"}},"humanApprovalAbove":{"type":"number","description":"Payments strictly above this USDC amount trigger human approval"},"isActive":{"type":"boolean"}}},"ApiKeyRecord":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string","enum":["sandbox","live"]},"prefix":{"type":"string","enum":["own_test_","own_live_"]},"keyMasked":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"revokedAt":{"type":"string","format":"date-time","nullable":true},"isActive":{"type":"boolean"}}}}},"paths":{"/api/v1/intents":{"post":{"summary":"Create Payment Intent","description":"Generates an idempotent, non-custodial payment intent with real-time currency conversion on Base.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","default":"USD"},"title":{"type":"string"},"webhook_url":{"type":"string","format":"uri"}},"required":["order_id","amount"]}}}},"responses":{"201":{"description":"Payment intent generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIntent"}}}},"401":{"description":"Unauthorized or invalid API key"}}}},"/api/v1/intents/{id}/status":{"get":{"summary":"Inspect Intent Status","description":"Returns the real-time settlement status of an on-chain intent.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Settlement status returned"},"404":{"description":"Intent not found"}}}},"/v1/payments":{"post":{"summary":"Execute Universal Payment (Human or Agent)","description":"Executes a direct settlement payment. Autonomous agents are evaluated against the centralized Policy Engine.","security":[{"ApiKeyAuth":[]},{"AgentKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number"},"recipient":{"type":"string","description":"Recipient EVM address on Base"},"token":{"type":"string","default":"USDC"},"chain":{"type":"string","default":"base"},"purpose":{"type":"string"}},"required":["amount","recipient"]}}}},"responses":{"200":{"description":"Payment settled immediately on-chain"},"202":{"description":"Approval required: payment queued for human review"},"403":{"description":"Payment rejected by policy limits or agent is frozen"}}}},"/v1/agents":{"post":{"summary":"Register Autonomous Agent","description":"Registers an autonomous agent with a derived Base Smart Account wallet and default policy.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"defaultChain":{"type":"string","default":"base"},"defaultToken":{"type":"string","default":"USDC"}},"required":["name"]}}}},"responses":{"201":{"description":"Agent registered with derived wallet and scoped API key"}}},"get":{"summary":"List Registered Agents","description":"Retrieves all agents owned by the authenticated merchant with balance and spending summaries.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of agents returned"}}}},"/v1/agents/{id}/freeze":{"post":{"summary":"Agent Kill-Switch (Freeze Agent)","description":"Immediately freezes an agent. All subsequent spending requests will be rejected with 403.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent frozen successfully"},"404":{"description":"Agent not found"}}}},"/v1/agents/{id}/unfreeze":{"post":{"summary":"Unfreeze Agent","description":"Restores an agent to active status.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent unfrozen and active"}}}},"/api/v1/keys/create":{"post":{"summary":"Create Scoped API Key","description":"Issues a new API key with granular scopes and environment isolation. Raw secret is displayed ONCE.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["sandbox","live"],"default":"sandbox"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}},"responses":{"201":{"description":"Key created with rawSecret preview"},"403":{"description":"Unverified merchants cannot issue live keys"}}}},"/api/v1/keys":{"get":{"summary":"List Masked API Keys","description":"Retrieves all keys for the authenticated merchant with prefixes and masks (raw secret omitted).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of masked keys"}}}},"/api/v1/keys/{id}/revoke":{"post":{"summary":"Revoke API Key","description":"Permanently revokes an API key. Revocation is instantaneous.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked"}}}},"/api/v1/x402/data-feed":{"get":{"summary":"x402 Machine Paywall Data Feed","description":"Returns HTTP 402 with micropayment requirements unless valid payment proof is supplied.","parameters":[{"name":"X-Payment-Proof","in":"header","required":false,"schema":{"type":"string"},"description":"Payment proof or settled intent UUID"}],"responses":{"200":{"description":"Access granted"},"402":{"description":"Payment required"}}}},"/api/v1/webhooks/dispatch-test":{"post":{"summary":"SSRF-Protected Webhook Tester","description":"Dispatches a test HMAC-signed webhook event to an external endpoint with SSRF defenses.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetUrl":{"type":"string","format":"uri"},"eventType":{"type":"string","enum":["intent.settled","payment.confirmed","agent.paid","session_key.revoked"]},"secret":{"type":"string"}},"required":["targetUrl"]}}}},"responses":{"200":{"description":"Webhook test dispatched with delivery receipt"},"400":{"description":"SSRF violation: localhost, private IP, or metadata endpoint blocked"}}}},"/api/v1/sandbox/faucet":{"post":{"summary":"Testnet Sandbox Faucet","description":"Simulates instantaneous USDC payment confirmation on Base Sepolia for a testnet intent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent_id":{"type":"string"}},"required":["intent_id"]}}}},"responses":{"200":{"description":"Intent confirmed on Base Sepolia"}}}},"/api/v1/pay/submit-tx":{"post":{"summary":"Submit Coinbase Smart Wallet / Passkey Transaction","description":"Submits an on-chain transaction hash for instant cryptographic & 15-point verification and canonical double-entry settlement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent_id":{"type":"string","format":"uuid"},"tx_hash":{"type":"string","description":"Hex-encoded 64-character transaction hash on Base"}},"required":["intent_id","tx_hash"]}}}},"responses":{"200":{"description":"Transaction verified and settled on Base"},"400":{"description":"Verification failed: invalid token, recipient, or reverted transaction"},"404":{"description":"Intent not found"},"409":{"description":"Conflict: Replay attack or already settled"},"410":{"description":"Intent has expired"}}}},"/api/v1/reports/tax-statement":{"get":{"summary":"Generate Accounting & Tax Statement","description":"Generates standard accounting statements in CSV, JSON, or printable PDF/HTML formats with fee breakdown and legal disclaimers.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"range","in":"query","schema":{"type":"string","enum":["30d","quarterly","ytd","all"],"default":"all"}},{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json","pdf"],"default":"json"}}],"responses":{"200":{"description":"Accounting statement generated in requested format"},"401":{"description":"Unauthorized"}}}},"/api/v1/pricing":{"get":{"summary":"Commercial Pricing & Fee Schedule","description":"Returns the transparent per-transaction fee schedule ($0/month, 0.25% Starter, 0.10% Verified, 0.05% Enterprise).","responses":{"200":{"description":"Pricing policy metadata"}}}}},"x-ownpay-pricing":{"model":"TRANSACTION_BASED","pricingModel":"TRANSACTION_BASED","commercialTerms":"Pay as you process — no monthly subscription.","monthlySubscriptionFee":0,"annualSubscriptionFee":0,"setupFee":0,"defaultFeeRate":"0.10%","activePolicy":{"policyId":"policy_base_tx_v1","name":"OwnPay Base Standard Protocol Fee","feeType":"TRANSACTION_PERCENTAGE","rate":0.001,"rateDisplay":"0.10%","minimumFeeUsd":0.0001,"settlementCurrency":"USDC","effectiveFrom":"2026-01-01T00:00:00Z"},"tiers":{"starter":{"feeBps":25,"percentage":"0.25%","feeRate":0.0025,"dailyLimitUsd":500,"description":"Entry-level live merchant tier for daily payments up to $500/day (~60,000 BDT). Purpose-built for small businesses, solo developers, and freelancers. Real USDC settled on Base Mainnet after streamlined individual KYC verification.","features":["Base Mainnet Live Settlement (Real USDC)","Up to $500/day (~60,000 BDT)","0.25% Protocol Transaction Fee","Streamlined Solo Dev & Freelancer KYC (NID/Passport)","Basic POS Dynamic QR","Base Sepolia Sandbox Mode Included"]},"verified":{"feeBps":10,"percentage":"0.10%","feeRate":0.001,"dailyLimitUsd":25000,"description":"Full commercial merchant tier for stores processing up to $25,000/day on Base Mainnet. Purpose-built for registered businesses, e-commerce, and retail chains. Requires comprehensive business KYC (Trade License, Corporate Tax ID/VAT, Operating Address, and Cryptographic Wallet Signature) to prevent any legal/regulatory issues.","features":["Base Mainnet Live Settlement (Real USDC)","Up to $25,000/day (~30 Lakh BDT)","0.10% Protocol Transaction Fee","Full Corporate KYC & Trade License Verification","Hosted Payment Links & Checkout","Multi-Key Rotation & Webhook Engine","Agent Commerce Access"]},"enterprise":{"feeBps":5,"percentage":"0.05%","feeRate":0.0005,"dailyLimitUsd":null,"description":"For institutional volume, AI agent fleets, fintech aggregators, and high-frequency merchants requiring customized risk, transaction, and settlement policies on Base Mainnet. Requires comprehensive institutional AML/KYC, UBO declaration, and legal compliance clearance to ensure zero cross-border regulatory issues.","features":["Base Mainnet Live Settlement (Real USDC)","Custom Volume Limits","0.05% / Negotiated Micro-Fee","Comprehensive Institutional AML/KYC & Legal Clearance","Custom Paymaster Rails","Dedicated AI Agent Fleet Policies","Advanced Risk Controls & 24/7 SLA"]},"UNVERIFIED":{"tier":"UNVERIFIED","tierLabel":"Sandbox Testnet (Unverified)","environment":"sandbox","dailyLimitUsd":500,"dailyLimitBdt":60000,"daily_limit_usd":500,"daily_limit_bdt":60000,"mainnetEnabled":false,"subscriptionFee":0,"pricingModel":"TRANSACTION_BASED","feeRate":0.0025,"feeBps":25,"percentage":"0.25%","feeRateDisplay":"0.25% per transaction","description":"Initial state for newly registered accounts. Restricted to Base Sepolia testnet sandbox until KYC verification is submitted.","features":["Base Sepolia Testnet (84532)","Test Faucet & Simulated Settlement","Single API Key Scope","Base Mainnet Settlement Locked"]},"STARTER":{"tier":"STARTER","tierLabel":"Tier 1: Starter","environment":"live","dailyLimitUsd":500,"dailyLimitBdt":60000,"daily_limit_usd":500,"daily_limit_bdt":60000,"mainnetEnabled":true,"subscriptionFee":0,"pricingModel":"TRANSACTION_BASED","feeRate":0.0025,"feeBps":25,"percentage":"0.25%","feeRateDisplay":"0.25% per transaction","description":"Entry-level live merchant tier for daily payments up to $500/day (~60,000 BDT). Purpose-built for small businesses, solo developers, and freelancers. Real USDC settled on Base Mainnet after streamlined individual KYC verification.","features":["Base Mainnet Live Settlement (Real USDC)","Up to $500/day (~60,000 BDT)","0.25% Protocol Transaction Fee","Streamlined Solo Dev & Freelancer KYC (NID/Passport)","Basic POS Dynamic QR","Base Sepolia Sandbox Mode Included"]},"VERIFIED":{"tier":"VERIFIED","tierLabel":"Tier 2: Verified Merchant","environment":"live","dailyLimitUsd":25000,"dailyLimitBdt":3000000,"daily_limit_usd":25000,"daily_limit_bdt":3000000,"mainnetEnabled":true,"subscriptionFee":0,"pricingModel":"TRANSACTION_BASED","feeRate":0.001,"feeBps":10,"percentage":"0.10%","feeRateDisplay":"0.10% per transaction","description":"Full commercial merchant tier for stores processing up to $25,000/day on Base Mainnet. Purpose-built for registered businesses, e-commerce, and retail chains. Requires comprehensive business KYC (Trade License, Corporate Tax ID/VAT, Operating Address, and Cryptographic Wallet Signature) to prevent any legal/regulatory issues.","features":["Base Mainnet Live Settlement (Real USDC)","Up to $25,000/day (~30 Lakh BDT)","0.10% Protocol Transaction Fee","Full Corporate KYC & Trade License Verification","Hosted Payment Links & Checkout","Multi-Key Rotation & Webhook Engine","Agent Commerce Access"]},"ENTERPRISE":{"tier":"ENTERPRISE","tierLabel":"Tier 3: Enterprise","environment":"live","dailyLimitUsd":null,"dailyLimitBdt":null,"daily_limit_usd":null,"daily_limit_bdt":null,"mainnetEnabled":true,"subscriptionFee":0,"pricingModel":"TRANSACTION_BASED","feeRate":0.0005,"feeBps":5,"percentage":"0.05%","feeRateDisplay":"0.05% custom volume pricing","description":"For institutional volume, AI agent fleets, fintech aggregators, and high-frequency merchants requiring customized risk, transaction, and settlement policies on Base Mainnet. Requires comprehensive institutional AML/KYC, UBO declaration, and legal compliance clearance to ensure zero cross-border regulatory issues.","features":["Base Mainnet Live Settlement (Real USDC)","Custom Volume Limits","0.05% / Negotiated Micro-Fee","Comprehensive Institutional AML/KYC & Legal Clearance","Custom Paymaster Rails","Dedicated AI Agent Fleet Policies","Advanced Risk Controls & 24/7 SLA"]}}}}