{"openapi":"3.0.3","info":{"title":"ClawBank API","version":"1.0.0","description":"Programmable AI agent wallets on Solana. Provision isolated wallets, send SOL, and track transactions — all via HTTP.","contact":{"url":"https://clawbank.to"},"license":{"name":"MIT"}},"servers":[{"url":"https://clawbank.to","description":"Production"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Agent API key obtained at agent creation. Format: `cb_...`"},"SessionAuth":{"type":"apiKey","in":"cookie","name":"sb-access-token","description":"Supabase session cookie. Obtain by signing in at /login."}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":64},"description":{"type":"string","maxLength":500,"nullable":true},"wallet_address":{"type":"string","description":"Solana public key (base58)"},"daily_limit":{"type":"number","nullable":true,"description":"Max SOL the agent may spend per calendar day"},"max_tx_limit":{"type":"number","nullable":true,"description":"Max SOL per individual transaction"},"status":{"type":"string","enum":["active","inactive"]},"created_at":{"type":"string","format":"date-time"}}},"Transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["agent_tx","withdraw"]},"amount":{"type":"number","description":"Gross SOL amount"},"fee_taken":{"type":"number","description":"Platform fee in SOL"},"from_address":{"type":"string"},"to_address":{"type":"string"},"signature":{"type":"string","nullable":true,"description":"Solana transaction signature"},"status":{"type":"string","enum":["pending","confirmed","failed"]},"memo":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Balance":{"type":"object","properties":{"wallet_address":{"type":"string"},"balance_sol":{"type":"number"},"balance_lamports":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}},"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Service health","description":"Returns the health status of the ClawBank API and its connection to the Solana RPC.","tags":["Health"],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"},"solana":{"type":"object","properties":{"status":{"type":"string"},"latency_ms":{"type":"integer"}}},"network":{"type":"string","example":"devnet"}}}}}}}}},"/api/agent/balance":{"get":{"operationId":"getAgentBalance","summary":"Get agent wallet balance","description":"Returns the current SOL balance of the authenticated agent's wallet. Authenticated with agent API key.","tags":["Agent (API key)"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Balance fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Balance"}}},"example":{"data":{"wallet_address":"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU","balance_sol":0.42,"balance_lamports":420000000}}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Failed to reach Solana RPC","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/transact":{"post":{"operationId":"sendSol","summary":"Send SOL","description":"Send SOL from the agent wallet to any Solana address. A 0.5% platform fee is deducted from `amount_sol`. The transaction is simulated before broadcast to catch insufficient-balance errors early.","tags":["Agent (API key)"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","amount_sol"],"properties":{"to":{"type":"string","minLength":32,"maxLength":44,"description":"Destination Solana address (base58)","example":"7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"},"amount_sol":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":1000,"description":"Gross SOL to send (fee deducted from this)","example":0.1},"memo":{"type":"string","maxLength":200,"description":"Optional on-chain memo","example":"invoice 42"}}}}}},"responses":{"200":{"description":"Transaction confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"signature":{"type":"string","description":"Solana transaction signature"},"amount_sol":{"type":"number","description":"Net SOL received by destination"},"fee_sol":{"type":"number","description":"Platform fee charged"},"to":{"type":"string"},"explorer_url":{"type":"string","format":"uri","description":"Solana Explorer link"}}}}}}}},"400":{"description":"Validation error or simulation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Agent inactive or spend limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Transaction broadcast failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agents":{"get":{"operationId":"listAgents","summary":"List agents","description":"Returns all agents owned by the authenticated user, newest first.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"responses":{"200":{"description":"Agent list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAgent","summary":"Create agent","description":"Creates a new agent with a fresh Solana wallet. Returns the agent record plus the API key — shown only once, store it securely.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"api_key":{"type":"string","description":"Raw API key — shown once only"}}}]}}}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"}}}},"/api/agents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent UUID"}],"get":{"operationId":"getAgent","summary":"Get agent","description":"Returns a single agent owned by the authenticated user.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"responses":{"200":{"description":"Agent found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"404":{"description":"Agent not found or not owned by user"}}},"patch":{"operationId":"updateAgent","summary":"Update agent","description":"Update agent name, description, spend limits, or active status.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":500},"daily_limit":{"type":"number","nullable":true,"description":"Set null to remove limit"},"max_tx_limit":{"type":"number","nullable":true,"description":"Set null to remove limit"},"status":{"type":"string","enum":["active","inactive"]}}}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Agent"}}}}}},"404":{"description":"Agent not found"}}},"delete":{"operationId":"deactivateAgent","summary":"Deactivate agent","description":"Sets agent status to `inactive`. The wallet and transaction history are preserved.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"responses":{"200":{"description":"Agent deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}},"404":{"description":"Agent not found"}}}},"/api/agents/{id}/balance":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAgentBalanceById","summary":"Get agent balance (by ID)","description":"Returns the on-chain SOL balance for a specific agent. Useful from the dashboard.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Balance"}}}}}},"404":{"description":"Agent not found"},"502":{"description":"Solana RPC unreachable"}}}},"/api/agents/{id}/transactions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAgentTransactions","summary":"Get transaction history","description":"Returns paginated transaction history for an agent, newest first.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Transaction list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}}}},"404":{"description":"Agent not found"}}}},"/api/agent/withdraw":{"post":{"operationId":"withdrawSol","summary":"Withdraw SOL","description":"Withdraw SOL from an agent wallet to any Solana address. Requires session auth (owner only). A 0.5% platform fee is deducted.","tags":["Agents (session)"],"security":[{"SessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id","to","amount_sol"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"UUID of the agent to withdraw from"},"to":{"type":"string","minLength":32,"maxLength":44,"description":"Destination Solana address"},"amount_sol":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":10000}}}}}},"responses":{"200":{"description":"Withdrawal confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"signature":{"type":"string"},"amount_sol":{"type":"number"},"fee_sol":{"type":"number"},"to":{"type":"string"},"explorer_url":{"type":"string","format":"uri"}}}}}}}},"400":{"description":"Validation or simulation error"},"401":{"description":"Not authenticated"},"404":{"description":"Agent not found or inactive"},"500":{"description":"Transaction failed"}}}}},"tags":[{"name":"Health","description":"Service status"},{"name":"Agent (API key)","description":"Endpoints authenticated with a per-agent API key (`Authorization: Bearer cb_...`). Use these from AI agents and automation."},{"name":"Agents (session)","description":"Endpoints authenticated with a user session cookie. Use these from the ClawBank dashboard or your own backend."}]}