openapi: 3.1.0 info: title: Canath Payment Agent API description: AI-powered USDC/EURC stablecoin transfers via Circle. Send money peer-to-peer, check balances, fund wallets, and shop from any merchant — all through conversation. version: 3.0.0 servers: - url: https://www.canath.io/api security: - bearerAuth: [] components: schemas: {} securitySchemes: bearerAuth: type: http scheme: bearer description: "Use the pa_live_... API key returned by registerOrLogin. Include as: Authorization: Bearer pa_live_..." paths: /agent/register: post: operationId: registerOrLogin summary: Register a new Canath account or log in to an existing one description: | Creates a new account with a Circle USDC/EURC wallet, or authenticates an existing user. Returns a pa_live_ API key — store it immediately, it is shown only once. After calling this, ALWAYS immediately call getBalance before asking anything else. security: [] requestBody: required: true content: application/json: schema: type: object required: [email, password] properties: email: type: string format: email description: User's email address name: type: string description: Full name (required for new accounts) password: type: string minLength: 8 description: Password (min 8 characters) responses: "200": description: Authenticated — returning user content: application/json: schema: type: object properties: apiKey: type: string description: pa_live_... API key — store this for all subsequent requests agentHandle: type: string description: User's Canath handle e.g. PA-XK7M3Q2R isNewAccount: type: boolean "201": description: Created — new account with Circle wallet content: application/json: schema: type: object properties: apiKey: type: string agentHandle: type: string circleWalletId: type: string depositAddress: type: string description: Polygon address for receiving USDC/EURC from external wallets isNewAccount: type: boolean "400": description: Invalid input or email format "401": description: Wrong password /circle/balance: get: operationId: getBalance summary: Get USDC and EURC wallet balances description: | Returns the live USDC and EURC balances from the user's Circle wallet. Always call this immediately after registerOrLogin and display the result to the user. responses: "200": description: Live balances content: application/json: schema: type: object properties: USDC: type: string description: USDC balance e.g. "123.45" EURC: type: string description: EURC balance e.g. "67.89" /circle/wallet: post: operationId: createWallet summary: Create a Circle wallet (first-time users only) description: Call this once after registering a brand-new account. Returning users already have a wallet — skip this. responses: "200": description: Wallet created or already exists content: application/json: schema: type: object properties: walletId: type: string existing: type: boolean /agents/check: get: operationId: lookupUser summary: Check if a Canath user exists by email or handle description: | Look up a recipient before sending money. Returns 404 if not found. Always call this before sending to confirm the recipient has a Canath account. parameters: - name: email in: query schema: type: string - name: handle in: query schema: type: string description: PA-XXXXXXXX format responses: "200": description: User found content: application/json: schema: type: object properties: found: type: boolean handle: type: string email: type: string "404": description: No Canath account found for that email or handle /agent/transfer: post: operationId: sendPayment summary: Send USDC or EURC to another Canath user description: | Send USDC or EURC peer-to-peer. 1.49% fee applies. ALWAYS confirm recipient, amount, currency, and fee with the user before calling this. The "to" field accepts: email address, Canath handle (PA-XXXXXXXX), or phone (+1...). requestBody: required: true content: application/json: schema: type: object required: [to, amount, currency] properties: to: type: string description: Recipient email, PA-XXXXXXXX handle, or phone number amount: type: number description: Amount to send (before fee) currency: type: string enum: [USDC, EURC] description: USDC (US Dollar Coin) or EURC (Euro Coin) responses: "200": description: Transfer complete content: application/json: schema: type: object properties: transferId: type: string status: type: string amount: type: number fee: type: number recipientAmount: type: number currency: type: string "400": description: Invalid input or insufficient balance "404": description: Recipient not found /agent/transfer/quote: get: operationId: getTransferQuote summary: Get a fee quote before sending description: Preview the fee and net amount for a transfer. Use before calling sendPayment to show the user exactly what will be deducted. parameters: - name: to in: query required: true schema: type: string - name: amount in: query required: true schema: type: number - name: currency in: query schema: type: string enum: [USDC, EURC] default: USDC responses: "200": description: Fee quote content: application/json: schema: type: object properties: amount: type: number fee: type: number feeRate: type: string recipientReceives: type: number currency: type: string /circle/buy-session: post: operationId: createFundingLink summary: Generate a private link for the user to add USDC or EURC to their wallet description: | Creates a secure, time-limited funding link. The user taps the link to buy USDC or EURC via debit card (Circle Mint) or from any exchange. Never ask the user for card details — all payment processing happens on Circle's platform. requestBody: required: true content: application/json: schema: type: object required: [amount, currency] properties: amount: type: number description: Amount to fund currency: type: string enum: [USDC, EURC] responses: "200": description: Funding link created content: application/json: schema: type: object properties: url: type: string description: "Private link e.g. https://www.canath.io/buy?token=..." amount: type: number currency: type: string expiresAt: type: string format: date-time /circle/withdraw: post: operationId: withdrawToWallet summary: Withdraw USDC or EURC to an external Polygon wallet description: | Sends USDC or EURC on-chain to any Polygon (EVM) address. 1.49% Canath fee applies. Always confirm the destination address, amount, fee, and net with the user before executing. If the user has a saved default withdrawal address, the API uses it automatically. requestBody: required: true content: application/json: schema: type: object required: [amount, currency] properties: amount: type: number currency: type: string enum: [USDC, EURC] address: type: string description: "Optional — Polygon 0x address. Omit to use the user's saved default." responses: "200": description: Withdrawal initiated content: application/json: schema: type: object properties: txId: type: string address: type: string gross: type: number fee: type: number net: type: number currency: type: string note: type: string description: Forward this message to the user verbatim /circle/transfers: get: operationId: getTransferHistory summary: Get recent USDC/EURC transfer history responses: "200": description: Transfer list content: application/json: schema: type: object properties: transfers: type: array items: type: object /account/revoke-key: post: operationId: revokeApiKey summary: Revoke the current API key description: Triggered when the user says "turn off", "disable", "pause", or "revoke". Circle wallets and funds remain safe — only the API key is invalidated. responses: "200": description: Key revoked