Agent Authentication

Authentication protocols for autonomous AI agent operations on ClawBank's financial infrastructure.

Overview

ClawBank implements cryptographic authentication for AI agents operating as independent economic entities. The authorization architecture supports autonomous financial operations while maintaining institutional-grade security through hardware security modules (HSMs), zero-knowledge proofs, and on-chain transaction validation.

Authentication Architecture

Key Hierarchy

Organization
├── Service Keys (sk_live_*)
│   ├── Full platform access
│   ├── Vault management
│   └── Agent key provisioning
│
├── Agent Keys (ak_live_*)
│   ├── Scoped treasury operations
│   ├── Transaction execution
│   └── Balance queries
│
└── Observer Keys (ok_live_*)
    ├── Read-only access
    └── Analytics queries

Key Types & Permissions

Type	Prefix	Use Case	Permissions	Rate Limit
Service Key	sk_live_	Backend infrastructure	Full API access, agent provisioning	600/min
Agent Key	ak_live_	AI agent operations	Scoped treasury access	1200 MCP calls/min
Observer Key	ok_live_	Monitoring systems	Read-only queries	300/min

Network Environments

• Mainnet: *_live_* - Solana mainnet, real assets

• Devnet: *_test_* - Solana devnet, test tokens

Agent Key Provisioning

Creating Agent Keys

import { ClawBank } from '@clawbank/sdk';

const client = new ClawBank({
  apiKey: process.env.CLAWBANK_SERVICE_KEY, // sk_live_*
  environment: 'production'
});

const agentKey = await client.agents.keys.create({
  name: 'Treasury Operations Agent',
  vaultId: 'vault_abc123',
  permissions: [
    'vaults:read',
    'transactions:create',
    'transactions:read',
    'balance:query'
  ],
  limits: {
    maxTransactionAmount: 1000_000_000, // 1000 USDC (6 decimals)
    dailyTransactionLimit: 10000_000_000, // 10,000 USDC
    maxTransactionsPerHour: 20
  },
  policies: {
    requiresApproval: {
      above: 5000_000_000 // 5000 USDC
    },
    allowedMerchants: [
      'aws.amazon.com',
      'openai.com',
      'anthropic.com'
    ]
  }
});

console.log(`Agent key: ${agentKey.key}`);
console.log(`Key ID: ${agentKey.id}`);

Permission Scopes

// Minimal permissions (read-only agent)
const observerAgent = await client.agents.keys.create({
  name: 'Analytics Agent',
  permissions: [
    'vaults:read',
    'transactions:read',
    'balance:query'
  ]
});

// Full treasury operations
const treasuryAgent = await client.agents.keys.create({
  name: 'Treasury Management Agent',
  permissions: [
    'vaults:read',
    'vaults:update',
    'transactions:create',
    'transactions:read',
    'transfers:create',
    'policies:read'
  ],
  limits: {
    maxTransactionAmount: 10000_000_000,
    dailyTransactionLimit: 100000_000_000
  }
});

Model Context Protocol (MCP) Authentication

MCP Server Configuration

Configure AI agents to connect via Model Context Protocol:

{
  "mcpServers": {
    "clawbank": {
      "command": "npx",
      "args": ["-y", "@clawbank/mcp-server"],
      "env": {
        "CLAWBANK_AGENT_KEY": "ak_live_abc123...",
        "CLAWBANK_VAULT_ID": "vault_xyz789",
        "CLAWBANK_NETWORK": "solana-mainnet"
      }
    }
  }
}

Programmatic MCP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@clawbank/mcp-server'],
  env: {
    CLAWBANK_AGENT_KEY: process.env.CLAWBANK_AGENT_KEY,
    CLAWBANK_VAULT_ID: 'vault_xyz789',
    CLAWBANK_NETWORK: 'solana-mainnet'
  }
});

const mcpClient = new Client({
  name: 'treasury-agent',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

await mcpClient.connect(transport);

// Agent now has authenticated access to treasury operations
const tools = await mcpClient.listTools();
console.log('Available operations:', tools);

On-Chain Transaction Signing

All blockchain transactions require cryptographic signatures. ClawBank supports managed wallets and bring-your-own-key (BYOK) models.

Option 1: Managed Wallet (Recommended)

import { ClawBankAgent } from '@clawbank/agent-sdk';

const agent = new ClawBankAgent({
  agentKey: process.env.CLAWBANK_AGENT_KEY,
  wallet: 'managed' // HSM-backed signing
});

// Transactions signed automatically within security boundaries
const tx = await agent.transactions.execute({
  type: 'transfer',
  amount: 100_000_000, // 100 USDC
  recipient: 'recipient_address',
  memo: 'Infrastructure payment'
});

console.log(`Signature: ${tx.signature}`);
console.log(`Explorer: https://solscan.io/tx/${tx.signature}`);

Option 2: Bring Your Own Key (BYOK)

import { Keypair } from '@solana/web3.js';
import { ClawBankAgent } from '@clawbank/agent-sdk';

// Load agent's Solana keypair
const keypair = Keypair.fromSecretKey(
  Buffer.from(process.env.AGENT_PRIVATE_KEY, 'base64')
);

const agent = new ClawBankAgent({
  agentKey: process.env.CLAWBANK_AGENT_KEY,
  wallet: keypair
});

// Agent signs transactions with provided keypair
const tx = await agent.transactions.execute({
  type: 'transfer',
  amount: 100_000_000,
  recipient: 'recipient_address'
});

Key Rotation

Implement regular key rotation for operational security:

// Generate new agent key
const newKey = await client.agents.keys.create({
  name: 'Treasury Agent - Q1 2026',
  vaultId: 'vault_abc123',
  permissions: existingPermissions,
  limits: existingLimits
});

// Update agent configuration
process.env.CLAWBANK_AGENT_KEY = newKey.key;

// Revoke old key after grace period
await client.agents.keys.revoke('ak_live_old_key_123');

Automated Rotation

async function rotateAgentKey(agentId: string, gracePeriodHours: number = 24) {
  // Create new key
  const newKey = await client.agents.keys.create({
    name: `Agent Key ${new Date().toISOString()}`,
    vaultId: agent.vaultId,
    permissions: agent.permissions,
    limits: agent.limits
  });

  // Schedule old key revocation
  setTimeout(async () => {
    await client.agents.keys.revoke(agent.currentKeyId);
  }, gracePeriodHours * 60 * 60 * 1000);

  return newKey;
}

Multi-Agent Authorization

Configure approval workflows requiring consensus from multiple AI agents:

await client.vaults.setAuthorizationPolicy('vault_abc123', {
  type: 'multi_agent_consensus',
  requiresApproval: {
    above: 5000_000_000, // 5000 USDC
    minAgents: 2,
    approvers: [
      'agent_treasury',
      'agent_risk',
      'agent_compliance'
    ],
    votingStrategy: 'majority', // or 'unanimous'
    timeoutMinutes: 30
  }
});

Agent Consensus Flow

// Agent 1: Initiates transaction
const proposal = await treasuryAgent.transactions.propose({
  amount: 10000_000_000, // 10,000 USDC
  recipient: 'vendor_address',
  memo: 'Infrastructure contract payment'
});

// Agent 2: Risk assessment approval
await riskAgent.transactions.approve(proposal.id, {
  reason: 'Risk assessment passed',
  signature: await riskAgent.sign(proposal.hash)
});

// Agent 3: Compliance approval
await complianceAgent.transactions.approve(proposal.id, {
  reason: 'Compliance checks passed',
  signature: await complianceAgent.sign(proposal.hash)
});

// Transaction executes after threshold reached

Security Best Practices

1. Key Storage

// ❌ Bad: Hardcoded keys
const client = new ClawBank({
  apiKey: 'sk_live_abc123...'
});

// ✅ Good: Environment variables
const client = new ClawBank({
  apiKey: process.env.CLAWBANK_SERVICE_KEY
});

// ✅ Better: Secrets manager
import { SecretsManager } from 'aws-sdk';
const secrets = new SecretsManager();
const { SecretString } = await secrets.getSecretValue({
  SecretId: 'clawbank/agent-keys'
}).promise();
const apiKey = JSON.parse(SecretString).CLAWBANK_AGENT_KEY;

2. Least Privilege Permissions

// ✅ Scope permissions to minimum required
const paymentAgent = await client.agents.keys.create({
  name: 'Payment Processing Agent',
  permissions: [
    'transactions:create', // Only what's needed
    'transactions:read'
  ],
  limits: {
    maxTransactionAmount: 1000_000_000,
    dailyTransactionLimit: 10000_000_000
  }
});

3. Transaction Verification

// Always verify before execution
const tx = await agent.transactions.prepare({
  type: 'transfer',
  amount: 100_000_000,
  recipient: recipientAddress
});

const verification = await agent.transactions.verify(tx);

if (!verification.safe) {
  throw new Error(`Transaction failed verification: ${verification.reason}`);
}

if (!verification.withinLimits) {
  throw new Error('Transaction exceeds agent limits');
}

// Execute only after verification
const signature = await agent.transactions.execute(tx);

4. Audit Logging

// Enable comprehensive audit trails
const agent = new ClawBankAgent({
  agentKey: process.env.CLAWBANK_AGENT_KEY,
  auditLog: {
    enabled: true,
    destination: 'cloudwatch', // or 'datadog', 'custom'
    level: 'verbose'
  }
});

// All operations logged with metadata
await agent.transactions.execute({
  amount: 100_000_000,
  recipient: 'address',
  metadata: {
    initiator: 'treasury-agent',
    purpose: 'vendor_payment',
    invoice: 'INV-2026-001'
  }
});

Rate Limiting

Tier	API Requests/min	On-Chain Ops/min	MCP Calls/min
Developer	60	10	120
Pro	600	60	1200
Enterprise	Custom	Custom	Unlimited

Handling Rate Limits

import { RateLimitError } from '@clawbank/sdk';

async function executeWithRetry(operation: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error instanceof RateLimitError) {
        const backoff = error.retryAfter || Math.pow(2, i) * 1000;
        await sleep(backoff);
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Encryption & Privacy

All sensitive data encrypted at rest and in transit:

• Agent Keys: AES-256-GCM encryption, stored in HSMs

• Private Keys: HSM-backed or client-side encrypted

• Transaction Metadata: Zero-knowledge proof encryption

• MCP Communications: TLS 1.3 with certificate pinning

• On-Chain Data: Optional ZK-proof privacy layer

Zero-Knowledge Transaction Privacy

await client.vaults.setAuthorizationPolicy('vault_abc123', {
  zkProofRequired: true,
  zkProofType: 'groth16',
  publicInputs: ['merchant_category', 'amount_range'],
  privateInputs: ['exact_amount', 'merchant_name', 'invoice_details']
});

// Transaction details remain private, only proof of validity is public
const tx = await agent.transactions.execute({
  amount: 100_000_000,
  recipient: 'merchant_address',
  zkProof: true
});

Compliance & Auditing

Security Audits

• Smart Contracts: Trail of Bits, OtterSec

• Infrastructure: SOC 2 Type II

• MCP Server: NCC Group

• On-Chain Programs: Verified reproducible builds

Regulatory Compliance

• FinCEN: Virtual currency reporting

• Bank Secrecy Act (BSA): AML/KYC for agent transactions

• GDPR: EU data protection for agent data

• CCPA: California privacy compliance

Reporting Security Issues

Report vulnerabilities responsibly:

• Email: [email protected]

• PGP: Download key

• Bug Bounty: Immunefi program

  • Critical smart contract issues: Up to $250,000

  • Infrastructure vulnerabilities: Up to $100,000

Next Steps

• Quickstart Guide - Deploy your first agent

• Authorization Engine - Programmable policies

• Treasury Vaults - On-chain smart contracts

• API Reference - Complete endpoint documentation