Agent API Documentation

// Response
{
  "wallet": "...",
  "checking": { "usdc": 150.00, "sol": 2.5 },
  "savings": { "usdc": 500.00, "sol": 0 },
  "yield": { "earned_usdc": 2.08, "earned_sol": 0, "apy": "5%" },
  "collateral": {
    "total_savings_usdc": 500.00,
    "borrowed_usdc": 0,
    "available_to_borrow_usdc": 350.00,
    "ltv_ratio": 0.7
  }
}

Send funds to the treasury wallet on-chain, then call this endpoint with the transaction signature. The deposit is verified on-chain before crediting your balance.

// Request
{
  "amount": 100,
  "token": "USDC",  // or "SOL"
  "tx_signature": "5KtP..."  // Solana transaction signature
}

// Response
{
  "success": true,
  "deposit": {
    "amount": 100,
    "token": "USDC",
    "tx_signature": "5KtP...",
    "verified": true
  },
  "balance": {
    "token": "USDC",
    "previous": 50,
    "current": 150
  },
  "verification": {
    "slot": 123456789,
    "blockTime": 1699123456,
    "sender": "...",
    "recipient": "..."
  }
}

Daily limit: $1,000 USD equivalent per agent. Withdrawals are queued and processed by the treasury.

// Request
{
  "amount": 50,
  "token": "USDC",
  "destination": "..."  // optional, defaults to agent wallet
}

// Response
{
  "success": true,
  "withdrawal": {
    "id": "...",
    "amount": 50,
    "token": "USDC",
    "destination": "...",
    "status": "pending"
  },
  "balance": {
    "token": "USDC",
    "previous": 150,
    "current": 100
  },
  "daily_limit": {
    "limit_usd": 1000,
    "withdrawn_today_usd": 50,
    "remaining_usd": 950
  }
}

Query params: limit (default 50), offset, type (deposit/withdraw/transfer)

// Response
{
  "transactions": [
    {
      "id": "...",
      "type": "deposit",
      "token": "USDC",
      "amount": 100,
      "status": "completed",
      "tx_signature": "5KtP...",
      "created_at": "2024-..."
    }
  ],
  "total": 15,
  "limit": 50,
  "offset": 0
}

Returns credit score, PD band, risk category, credit limit, and on-chain data analysis.

// Response
{
  "wallet": "...",
  "creditScore": {
    "score": 742,
    "pdBand": "3-7%",
    "riskCategory": "Medium",
    "creditLimit": 5000,
    "decision": "APPROVE"
  },
  "onChainData": {
    "solBalance": 10.5,
    "totalTransactions": 150
  }
}

Query params: amount (optional), purpose (optional)

// Response
{
  "eligible": true,
  "decision": "APPROVE",
  "maxAmount": 5000,
  "terms": {
    "apr": 0.12,
    "maxLTV": 0.7,
    "maxDuration": 90
  }
}

// Request
{
  "amount": 1000,
  "purpose": "task",  // task, working_capital, liquidity_provision, etc.
  "duration": 30,     // days
  "collateral": {     // optional
    "type": "SOL",
    "amount": 10
  }
}

// Response
{
  "application": {
    "id": "loan_123...",
    "status": "approved",
    "amount": 1000,
    "apr": 0.12,
    "terms": { ... }
  }
}

// Response
{
  "loans": [...],
  "summary": {
    "totalLoans": 3,
    "totalActive": 1,
    "totalOutstanding": 950
  }
}

// Request
{
  "amount": 100,
  "txSignature": "..." // optional, for on-chain verification
}

// Response
{
  "payment": {
    "id": "payment_123...",
    "amount": 100,
    "remainingBalance": 850,
    "status": "completed"
  }
}

import { Keypair, Connection, Transaction, SystemProgram, LAMPORTS_PER_SOL } from '@solana/web3.js';
import bs58 from 'bs58';
import nacl from 'tweetnacl';

const BASE_URL = 'https://bankofclawd.com/api/v1';
const TREASURY_WALLET = 'TREASURY_ADDRESS_HERE';

class BankOfClawdAgent {
  private wallet: Keypair;
  private connection: Connection;
  private token: string | null = null;

  constructor(privateKey: string, rpcUrl = 'https://api.mainnet-beta.solana.com') {
    this.wallet = Keypair.fromSecretKey(bs58.decode(privateKey));
    this.connection = new Connection(rpcUrl);
  }

  async authenticate(): Promise<void> {
    // 1. Get challenge
    const challengeRes = await fetch(`${BASE_URL}/agent/auth/challenge`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ wallet: this.wallet.publicKey.toBase58() })
    });
    const { challenge } = await challengeRes.json();

    // 2. Sign challenge
    const messageBytes = new TextEncoder().encode(challenge);
    const signature = nacl.sign.detached(messageBytes, this.wallet.secretKey);
    const signatureBase58 = bs58.encode(signature);

    // 3. Verify and get token
    const verifyRes = await fetch(`${BASE_URL}/agent/auth/verify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        wallet: this.wallet.publicKey.toBase58(),
        signature: signatureBase58,
        message: challenge
      })
    });
    const { token } = await verifyRes.json();
    this.token = token;
  }

  // ============ BANKING ============

  async getAccount() {
    const res = await fetch(`${BASE_URL}/agent/account`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }

  async deposit(amount: number, token: 'SOL' | 'USDC') {
    // 1. Send funds on-chain to treasury
    const tx = new Transaction().add(
      SystemProgram.transfer({
        fromPubkey: this.wallet.publicKey,
        toPubkey: new PublicKey(TREASURY_WALLET),
        lamports: amount * LAMPORTS_PER_SOL
      })
    );
    const signature = await this.connection.sendTransaction(tx, [this.wallet]);
    await this.connection.confirmTransaction(signature);

    // 2. Record deposit via API (verified on-chain)
    const res = await fetch(`${BASE_URL}/agent/account/deposit`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify({ amount, token, tx_signature: signature })
    });
    return res.json();
  }

  async withdraw(amount: number, token: 'SOL' | 'USDC', destination?: string) {
    const res = await fetch(`${BASE_URL}/agent/account/withdraw`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify({ amount, token, destination })
    });
    return res.json();
  }

  // ============ CREDIT ============

  async getProfile() {
    const res = await fetch(`${BASE_URL}/agent/profile`, {
      headers: { 'Authorization': `Bearer ${this.token}` }
    });
    return res.json();
  }

  async applyForLoan(amount: number, purpose: string) {
    const res = await fetch(`${BASE_URL}/agent/loans`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify({ amount, purpose, duration: 30 })
    });
    return res.json();
  }
}

// Usage
const agent = new BankOfClawdAgent('YOUR_PRIVATE_KEY');
await agent.authenticate();

// Check balance
const account = await agent.getAccount();
console.log('Checking:', account.checking);
console.log('Savings:', account.savings);

// Deposit 1 SOL
await agent.deposit(1, 'SOL');

// Check credit score
const profile = await agent.getProfile();
console.log('Credit Score:', profile.creditScore.score);