REST API

API Reference

ClawBank provides two authentication methods: Session Auth for user-facing operations and API Key Auth for autonomous agent transactions.

Authentication

API Key (agents)

Used by AI agents for autonomous transactions.

Authorization: Bearer cb_your_api_key

Session (users)

Supabase session cookie — set automatically after login.

Cookie: sb-xxx-auth-token=...

Endpoints

GET/api/agent/balanceAPI Key

Get real-time SOL balance for the authenticated agent's wallet.

Response

{
  "data": {
    "wallet_address": "9xDm...",
    "balance_sol": 1.2345,
    "balance_lamports": 1234500000
  }
}

POST/api/agent/transactAPI Key

Send SOL from the agent's wallet. Platform fee (0.5%) deducted automatically. Transaction is simulated before signing.

Request body

{
  "to": "RECIPIENT_SOLANA_ADDRESS",
  "amount_sol": 0.1,
  "memo": "optional memo string"
}

Response

{
  "data": {
    "signature": "5eykt...",
    "amount_sol": 0.0995,
    "fee_sol": 0.0005,
    "to": "RECIPIENT_ADDRESS",
    "explorer_url": "https://explorer.solana.com/tx/..."
  }
}

POST/api/agent/withdrawSession

User-initiated withdrawal from an agent wallet. Requires session auth + agent ownership.

Request body

{
  "agent_id": "uuid",
  "to": "RECIPIENT_SOLANA_ADDRESS",
  "amount_sol": 0.5
}

Response

{
  "data": {
    "signature": "5eykt...",
    "amount_sol": 0.4975,
    "fee_sol": 0.0025,
    "to": "RECIPIENT_ADDRESS",
    "explorer_url": "https://explorer.solana.com/tx/..."
  }
}

GET/api/agentsSession

List all agents owned by the authenticated user.

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Trading Bot",
      "wallet_address": "9xDm...",
      "status": "active",
      "daily_limit": 10,
      "max_tx_limit": 1
    }
  ]
}

POST/api/agentsSession

Create a new agent. Generates a Solana keypair automatically. Returns the API key ONCE — store it securely.

Request body

{
  "name": "My AI Agent",
  "description": "Optional description"
}

Response

{
  "data": {
    "id": "uuid",
    "name": "My AI Agent",
    "wallet_address": "9xDm...",
    "api_key": "cb_abc123...",
    "status": "active"
  }
}

PATCH/api/agents/:idSession

Update agent settings including spending limits.

Request body

{
  "daily_limit": 5,
  "max_tx_limit": 0.5,
  "status": "inactive"
}

Response

{ "data": { "id": "...", "daily_limit": 5 } }

GET/api/agents/:id/balanceSession

Get real-time balance for a specific agent by ID.

Response

{
  "data": {
    "address": "9xDm...",
    "balance_sol": 1.23,
    "balance_lamports": 1230000000
  }
}

GET/api/agents/:id/transactionsSession

Paginated transaction history for an agent. Query params: limit (max 100), offset.

Response

{
  "data": [
    {
      "id": "uuid",
      "type": "agent_tx",
      "amount": 0.1,
      "fee_taken": 0.0005,
      "signature": "5eykt...",
      "status": "confirmed",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

GET/api/healthNone

Platform health check + Solana RPC status.

Response

{
  "status": "ok",
  "timestamp": "2026-01-01T00:00:00Z",
  "solana": { "online": true, "slot": 300000000, "latency_ms": 42 },
  "network": "devnet"
}

Error Codes

400Bad RequestInvalid JSON or failed validation

401UnauthorizedMissing or invalid API key / session

403ForbiddenSpending limit exceeded or agent inactive

404Not FoundAgent not found or not owned by user

500Server ErrorTransaction failed or internal error

502Bad GatewaySolana RPC unavailable