{"name":"Bank of Clawd Agent API","version":"2.0.0","baseUrl":"/api/v1","description":"Complete financial infrastructure for AI agents: banking, savings with Kamino yield, collateral credit, x402 payments, and credit lines.","treasury_address":"G3siTv4xEEo9i3UJgnPaVq3TbyGeyNLATk74VvKXaadV","authentication":{"type":"Wallet Signature + JWT","flow":["1. Request a challenge: POST /api/v1/agent/auth/challenge","2. Sign the challenge with your wallet","3. Verify and get token: POST /api/v1/agent/auth/verify","4. Use token in Authorization header: Bearer <token>"],"tokenExpiry":"24 hours"},"endpoints":{"authentication":[{"method":"POST","path":"/agent/auth/challenge","description":"Request a challenge message to sign","body":{"wallet":"string (Solana wallet address)"},"response":{"challenge":"string (message to sign)","expiresIn":"number (seconds)"}},{"method":"POST","path":"/agent/auth/verify","description":"Verify signature and get access token","body":{"wallet":"string","signature":"string (base58 encoded)","message":"string (the challenge that was signed)"},"response":{"token":"string (JWT)","expiresIn":"number (seconds)","wallet":"string"}}],"profile":[{"method":"GET","path":"/agent/profile","description":"Get agent credit profile and score","auth":"Required","response":{"wallet":"string","creditScore":{"score":"number (0-1000)","pdBand":"string","riskCategory":"string","htm":"number (0.7-1.2)","creditLimit":"number (USD)","suggestedAPR":"number","decision":"APPROVE | APPROVE_WITH_CONDITIONS | DENY","subscores":"object"},"onChainData":{"solBalance":"number","totalTransactions":"number","accountAgeDays":"number | null"},"identity":{"wallet":"boolean","x":"boolean","github":"boolean"}}}],"eligibility":[{"method":"GET","path":"/agent/eligibility","description":"Check loan eligibility","auth":"Required","queryParams":{"amount":"number (optional, requested loan amount)","purpose":"string (optional, loan purpose)"},"response":{"eligible":"boolean","decision":"string","maxAmount":"number","terms":{"apr":"number","maxLTV":"number","maxDuration":"number (days)"},"requirements":"string[]"}}],"banking":[{"method":"GET","path":"/agent/account","description":"Get account overview with checking, savings, yield, and collateral info","auth":"Required","response":{"checking":{"usdc":"number","sol":"number"},"savings":{"usdc":"number","sol":"number"},"yield_earned":{"usdc":"number","sol":"number"},"collateral":{"limit":"number","borrowed":"number","available":"number"},"apy":{"usdc":"number (decimal)","sol":"number (decimal)"}}},{"method":"POST","path":"/agent/account/deposit","description":"Record deposit after sending funds to treasury on-chain","auth":"Required","body":{"amount":"number","token":"USDC | SOL","tx_signature":"string (on-chain tx signature)"}},{"method":"POST","path":"/agent/account/withdraw","description":"Withdraw from checking to your wallet. Daily limit: $1000 USD","auth":"Required","body":{"amount":"number","token":"USDC | SOL","destination":"string (optional, defaults to agent wallet)"}},{"method":"GET","path":"/agent/account/transactions","description":"Get transaction history","auth":"Required","queryParams":{"limit":"number (default: 50)","offset":"number (default: 0)","type":"deposit | withdraw | savings_deposit | savings_withdraw | x402_payment | x402_receive"}}],"savings":[{"method":"POST","path":"/agent/account/savings/deposit","description":"Move funds from checking to savings to earn Kamino yield","auth":"Required","body":{"amount":"number","token":"USDC | SOL"},"note":"USDC earns ~1.7% APY, SOL earns ~5.2% APY (variable rates from Kamino)"},{"method":"POST","path":"/agent/account/savings/withdraw","description":"Move funds from savings back to checking (includes earned yield)","auth":"Required","body":{"amount":"number","token":"USDC | SOL"}},{"method":"GET","path":"/agent/account/savings/yield","description":"Get current APY rates from Kamino Finance","auth":"Not required","response":{"rates":[{"token":"USDC","apy":"string","apyDecimal":"number"},{"token":"SOL","apy":"string","apyDecimal":"number"}],"protocol":"Kamino Finance"}}],"collateral":[{"method":"POST","path":"/agent/account/collateral/borrow","description":"Instantly borrow USDC against your savings (70% LTV, 8% APR)","auth":"Required","body":{"amount":"number (USDC to borrow)"},"terms":{"ltv":"70%","apr":"8%","approval":"instant"}},{"method":"POST","path":"/agent/account/collateral/repay","description":"Repay collateral loan from checking balance","auth":"Required","body":{"amount":"number (USDC to repay)"}}],"x402":[{"method":"POST","path":"/agent/account/x402/pay","description":"Make an x402 payment to an external service","auth":"Required","body":{"recipient":"string (Solana wallet address)","amount":"number","token":"USDC | SOL","service_url":"string (optional, URL being paid for)","memo":"string (optional)"},"response":{"success":"boolean","payment_id":"string (UUID)","tx_signature":"string","receipt":"X402PaymentReceipt (for retry headers)"},"daily_limit":"$1000 USD equivalent"},{"method":"POST","path":"/agent/account/x402/receive","description":"Verify and credit an incoming x402 payment","auth":"Required","body":{"tx_signature":"string (on-chain transaction)","expected_amount":"number (optional)","expected_token":"USDC | SOL (optional)"},"response":{"success":"boolean","payment_id":"string","verified":"boolean","amount":"number","token":"string","sender":"string"}},{"method":"GET","path":"/agent/account/x402/request","description":"Generate x402 payment request for 402 responses","auth":"Required","queryParams":{"amount":"number (required)","token":"USDC | SOL (default: USDC)","description":"string (optional)","expires_in":"number (seconds, default: 3600)"},"response":{"payment_request":"X402PaymentRequest","headers":"object (HTTP headers for 402 response)"}}],"loans":[{"method":"GET","path":"/agent/loans","description":"List all loans for the agent","auth":"Required","response":{"loans":"array","summary":{"totalLoans":"number","totalActive":"number","totalOutstanding":"number","nextPayment":"object | null"}}},{"method":"POST","path":"/agent/loans","description":"Apply for a new uncollateralized credit line (human review)","auth":"Required","body":{"amount":"number (required, USD)","purpose":"string (required: task, working_capital, liquidity_provision, market_neutral, directional_trading, speculative)","duration":"number (optional, days, default: 30)","collateral":{"type":"string (optional: SOL, USDC, etc.)","amount":"number (optional)"}},"response":{"application":{"id":"string","status":"approved | pending_review | denied","amount":"number","apr":"number","terms":"object"}}},{"method":"GET","path":"/agent/loans/:id","description":"Get specific loan details","auth":"Required","response":{"loan":"object"}},{"method":"POST","path":"/agent/loans/:id/repay","description":"Make a loan repayment","auth":"Required","body":{"amount":"number (required)","txSignature":"string (optional, Solana tx signature)"},"response":{"payment":{"id":"string","amount":"number","remainingBalance":"number","status":"string"}}}]},"errorCodes":{"400":"Bad Request - Invalid input","401":"Unauthorized - Missing or invalid token","403":"Forbidden - Insufficient permissions","404":"Not Found - Resource not found","500":"Internal Server Error"},"examples":{"authentication":"\n// Step 1: Get challenge\nconst challengeRes = await fetch('/api/v1/agent/auth/challenge', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ wallet: 'YOUR_WALLET_ADDRESS' })\n});\nconst { challenge } = await challengeRes.json();\n\n// Step 2: Sign with wallet (using @solana/web3.js)\nconst message = new TextEncoder().encode(challenge);\nconst signature = await wallet.signMessage(message);\nconst signatureBase58 = bs58.encode(signature);\n\n// Step 3: Verify and get token\nconst verifyRes = await fetch('/api/v1/agent/auth/verify', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({\n    wallet: 'YOUR_WALLET_ADDRESS',\n    signature: signatureBase58,\n    message: challenge\n  })\n});\nconst { token } = await verifyRes.json();\n      ","loanApplication":"\n// Apply for a loan\nconst res = await fetch('/api/v1/agent/loans', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'Authorization': `Bearer ${token}`\n  },\n  body: JSON.stringify({\n    amount: 1000,\n    purpose: 'task',\n    duration: 30\n  })\n});\nconst { application } = await res.json();\nconsole.log('Loan status:', application.status);\n      "},"sdkComingSoon":{"npm":"@bank-of-clawd/agent-sdk","features":["Automatic authentication handling","Type-safe API methods","Built-in retry logic","Wallet adapter integration"]}}