Agent Accounts

Agent accounts are dedicated banking accounts for AI agents with cryptographic identity, programmable spending policies, and blockchain settlement on Solana.

---

Overview

Every AI agent gets its own banking account with:

• Cryptographic Identity: Unique public/private keypair managed in HSM

• Solana Address: Blockchain account for settlement and verification

• MPP Endpoint: Machine Payments Protocol-compliant payment receiver

• Multi-Currency Support: USDC, SOL, and other SPL tokens

• Programmable Policies: On-chain spending rules via Solana smart contracts

• Real-Time Operations: Sub-second balance queries and transaction processing

---

Creating an Account

Basic Account Creation

const agent = await mppfi.agents.create({
  name: 'Cloud Infrastructure Agent',
  description: 'Autonomous cloud resource management',
  initialFunding: {
    amount: 5000_00, // $5,000 in cents
    currency: 'USDC'
  },
  metadata: {
    purpose: 'cloud_infrastructure',
    department: 'engineering',
    cost_center: 'eng-cloud-001',
    operator: '[email protected]'
  }
});

console.log('Agent Account Created:');
console.log('  ID:', agent.id);
console.log('  Name:', agent.name);
console.log('  Solana Address:', agent.solanaAddress);
console.log('  Public Key:', agent.publicKey);
console.log('  MPP Endpoint:', agent.mppEndpoint);
console.log('  Balance:', agent.balance.usdc, 'USDC');
console.log('  Network:', agent.network);
console.log('  Status:', agent.status);

Response:

{
  "id": "agent_7k3m9n2p4q1r",
  "name": "Cloud Infrastructure Agent",
  "description": "Autonomous cloud resource management",
  "solanaAddress": "8vQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "publicKey": "0x8f3a9e2c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a8e9f0c1d2e3f4a5b6c7d8e9f0",
  "mppEndpoint": "https://mpp.mppfi.xyz/agent_7k3m9n2p4q1r",
  "balance": {
    "usdc": "5000.00",
    "sol": "0.01"
  },
  "network": "solana-mainnet",
  "status": "active",
  "metadata": {
    "purpose": "cloud_infrastructure",
    "department": "engineering",
    "cost_center": "eng-cloud-001",
    "operator": "[email protected]"
  },
  "createdAt": "2026-03-30T10:30:00Z"
}

Multi-Currency Account

const agent = await mppfi.agents.create({
  name: 'Trading Agent',
  initialFunding: {
    usdc: 10000_00,  // $10,000 USDC
    sol: 50_00       // 50 SOL
  },
  currencies: ['USDC', 'SOL', 'USDT'],
  metadata: {
    purpose: 'automated_trading',
    strategy: 'arbitrage'
  }
});

console.log('Multi-Currency Balances:');
console.log('  USDC:', agent.balance.usdc);
console.log('  SOL:', agent.balance.sol);
console.log('  USDT:', agent.balance.usdt);

---

Querying Account Balance

Current Balance

const balance = await mppfi.agents.getBalance('agent_7k3m9n2p4q1r');

console.log('Agent Balance:');
console.log('  Available USDC:', balance.usdc.available);
console.log('  Pending USDC:', balance.usdc.pending);
console.log('  Total USDC:', balance.usdc.total);
console.log('  SOL (fees):', balance.sol);
console.log('  Last Updated:', balance.lastUpdated);
console.log('  Block Height:', balance.blockHeight);

Response:

{
  "agentId": "agent_7k3m9n2p4q1r",
  "usdc": {
    "available": "4750.00",
    "pending": "250.00",
    "total": "5000.00"
  },
  "sol": "0.009",
  "lastUpdated": "2026-03-30T10:35:12Z",
  "blockHeight": 187234567,
  "solanaAddress": "8vQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin"
}

Multi-Currency Balances

const balances = await mppfi.agents.getAllBalances('agent_7k3m9n2p4q1r');

balances.forEach(bal => {
  console.log(`${bal.currency}:`);
  console.log(`  Available: ${bal.available}`);
  console.log(`  Pending: ${bal.pending}`);
  console.log(`  Mint Address: ${bal.mintAddress}`);
});

---

Account Operations

Funding an Account

Via API (Off-Chain to On-Chain)

// Fund agent from your organization's account
const funding = await mppfi.agents.fund({
  agentId: 'agent_7k3m9n2p4q1r',
  amount: 1000_00,
  currency: 'USDC',
  source: 'organization', // or 'external'
  memo: 'Monthly budget allocation'
});

console.log('Funding Transaction:');
console.log('  TX Signature:', funding.solanaTxSignature);
console.log('  Amount:', funding.amount, funding.currency);
console.log('  Settlement Time:', funding.settlementTime, 'ms');
console.log('  New Balance:', funding.newBalance);

Via Blockchain Transfer

// Get agent's Solana address for direct transfer
const agent = await mppfi.agents.get('agent_7k3m9n2p4q1r');

console.log('Send USDC to this address:');
console.log('  Address:', agent.solanaAddress);
console.log('  Network: Solana Mainnet');
console.log('  Token: USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)');

// Funds will be available after blockchain confirmation (~400ms)

Withdrawing Funds

// Withdraw USDC to external Solana address
const withdrawal = await mppfi.agents.withdraw({
  agentId: 'agent_7k3m9n2p4q1r',
  amount: 500_00,
  currency: 'USDC',
  destination: {
    type: 'solana',
    address: '9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin'
  },
  memo: 'Withdrawal to treasury'
});

console.log('Withdrawal Transaction:');
console.log('  TX Signature:', withdrawal.solanaTxSignature);
console.log('  Amount:', withdrawal.amount, withdrawal.currency);
console.log('  Destination:', withdrawal.destination);
console.log('  Status:', withdrawal.status);
console.log('  Explorer:', `https://explorer.solana.com/tx/${withdrawal.solanaTxSignature}`);

---

Account Management

Updating Account Details

const updated = await mppfi.agents.update('agent_7k3m9n2p4q1r', {
  name: 'Cloud Infrastructure Agent - Updated',
  description: 'Enhanced autonomous cloud management',
  metadata: {
    purpose: 'cloud_infrastructure',
    department: 'platform',
    cost_center: 'platform-ops-001',
    version: 'v2.0'
  }
});

console.log('Agent Updated:');
console.log('  Name:', updated.name);
console.log('  Metadata:', updated.metadata);

Freezing an Account

// Temporarily freeze all agent operations
const frozen = await mppfi.agents.freeze('agent_7k3m9n2p4q1r', {
  reason: 'Security review in progress',
  duration: '24h',
  notifyOperator: true
});

console.log('Agent Frozen:');
console.log('  Status:', frozen.status);
console.log('  Reason:', frozen.freezeReason);
console.log('  Unfreezes At:', frozen.unfreezeAt);

// Unfreeze manually
await mppfi.agents.unfreeze('agent_7k3m9n2p4q1r');

Closing an Account

// Withdraw remaining balance first
const balance = await mppfi.agents.getBalance('agent_7k3m9n2p4q1r');

if (parseFloat(balance.usdc.available) > 0) {
  await mppfi.agents.withdraw({
    agentId: 'agent_7k3m9n2p4q1r',
    amount: parseFloat(balance.usdc.available) * 100,
    currency: 'USDC',
    destination: {
      type: 'organization' // Return to org account
    }
  });
}

// Close account
const closed = await mppfi.agents.close('agent_7k3m9n2p4q1r', {
  reason: 'Agent decommissioned',
  archiveData: true
});

console.log('Agent Closed:');
console.log('  Status:', closed.status);
console.log('  Closed At:', closed.closedAt);
console.log('  Archive URL:', closed.archiveUrl);

---

Transaction History

List Transactions

const transactions = await mppfi.transactions.list({
  agentId: 'agent_7k3m9n2p4q1r',
  limit: 50,
  offset: 0,
  status: 'settled',
  orderBy: 'createdAt:desc'
});

console.log(`Transactions (${transactions.length}):`);
transactions.forEach(tx => {
  console.log(`  ${tx.type}: ${tx.amount} ${tx.currency}`);
  console.log(`    Status: ${tx.status}`);
  console.log(`    Solana TX: ${tx.solanaTxSignature}`);
  console.log(`    Block: ${tx.blockNumber}`);
  console.log(`    Settlement: ${tx.settlementTime}ms`);
});

Filter by Date Range

const marchTransactions = await mppfi.transactions.list({
  agentId: 'agent_7k3m9n2p4q1r',
  startDate: '2026-03-01T00:00:00Z',
  endDate: '2026-03-31T23:59:59Z',
  type: 'payment'
});

console.log(`March Payments: ${marchTransactions.length}`);
console.log(`Total: $${marchTransactions.reduce((sum, tx) => sum + parseFloat(tx.amount), 0).toFixed(2)}`);

Export Transaction History

// Export as CSV with blockchain verification
const csv = await mppfi.transactions.export({
  agentId: 'agent_7k3m9n2p4q1r',
  format: 'csv',
  startDate: '2026-01-01',
  endDate: '2026-03-31',
  includeBlockchainProofs: true
});

// CSV includes:
// - Transaction ID
// - Timestamp
// - Type (payment/transfer/funding/withdrawal)
// - Amount/Currency
// - Status
// - Solana TX Signature
// - Block Number
// - Merchant/Recipient
// - Policy Validation

fs.writeFileSync('transactions_q1_2026.csv', csv);
console.log('Transactions exported with blockchain proofs');

---

Account Analytics

Spending Summary

const summary = await mppfi.analytics.getSpendingSummary({
  agentId: 'agent_7k3m9n2p4q1r',
  period: 'monthly',
  year: 2026,
  month: 3
});

console.log('March 2026 Spending:');
console.log('  Total Spent:', summary.totalSpent, summary.currency);
console.log('  Transaction Count:', summary.transactionCount);
console.log('  Average Transaction:', summary.averageTransaction);
console.log('  Top Merchants:');
summary.topMerchants.forEach(m => {
  console.log(`    ${m.name}: ${m.amount} ${m.currency} (${m.count} txns)`);
});
console.log('  Category Breakdown:');
Object.entries(summary.categories).forEach(([cat, amt]) => {
  console.log(`    ${cat}: ${amt}`);
});

Velocity Metrics

const velocity = await mppfi.analytics.getVelocityMetrics('agent_7k3m9n2p4q1r');

console.log('Spending Velocity:');
console.log('  Hourly:');
console.log('    Spent:', velocity.hourly.spent);
console.log('    Limit:', velocity.hourly.limit);
console.log('    Remaining:', velocity.hourly.remaining);
console.log('  Daily:');
console.log('    Spent:', velocity.daily.spent);
console.log('    Limit:', velocity.daily.limit);
console.log('    Remaining:', velocity.daily.remaining);
console.log('    Utilization:', velocity.daily.utilization, '%');
console.log('  Monthly:');
console.log('    Spent:', velocity.monthly.spent);
console.log('    Limit:', velocity.monthly.limit);
console.log('    Remaining:', velocity.monthly.remaining);

---

Hierarchical Agent Accounts

Parent-Child Structure

// Create parent agent
const parent = await mppfi.agents.create({
  name: 'Orchestration Agent',
  type: 'parent',
  initialFunding: { amount: 50000_00, currency: 'USDC' },
  metadata: { role: 'coordinator' }
});

// Create child agents under parent
const child1 = await mppfi.agents.createChild({
  parentId: parent.id,
  name: 'Data Collector Agent',
  spendingLimit: { amount: 1000_00, currency: 'USDC', period: 'daily' },
  derivationPath: "m/44'/501'/0'/0'", // HD wallet path
  metadata: { role: 'data_acquisition' }
});

const child2 = await mppfi.agents.createChild({
  parentId: parent.id,
  name: 'Processing Agent',
  spendingLimit: { amount: 2000_00, currency: 'USDC', period: 'daily' },
  derivationPath: "m/44'/501'/0'/1'",
  metadata: { role: 'data_processing' }
});

console.log('Agent Hierarchy:');
console.log('  Parent:', parent.id);
console.log('    Child 1:', child1.id, '- Daily limit: $1,000');
console.log('    Child 2:', child2.id, '- Daily limit: $2,000');

Transfer Between Agents

// Parent funds child agents
const transfer = await mppfi.transfers.create({
  from: parent.id,
  to: child1.id,
  amount: 500_00,
  currency: 'USDC',
  memo: 'Weekly budget allocation'
});

console.log('Transfer Complete:');
console.log('  From:', transfer.from);
console.log('  To:', transfer.to);
console.log('  Amount:', transfer.amount, transfer.currency);
console.log('  Solana TX:', transfer.solanaTxSignature);
console.log('  Settlement:', transfer.settlementTime, 'ms');

---

Best Practices

1. Account Naming

Use clear, descriptive names that indicate the agent's purpose:

// Good
'Production Agent - Cloud Infrastructure'
'DataBot - Research Paper Acquisition'
'PaymentAgent - Invoice Processing'

// Avoid
'Agent 1'
'Test'
'Bot'

2. Metadata Organization

Store relevant context in metadata for tracking:

metadata: {
  purpose: 'cloud_infrastructure',
  environment: 'production',
  department: 'engineering',
  cost_center: 'eng-cloud-001',
  project: 'autonomous-ops',
  operator: '[email protected]',
  version: '2.1.0',
  deployment: 'us-east-1'
}

3. Balance Monitoring

Set up alerts for low balances:

await mppfi.alerts.create({
  agentId: 'agent_7k3m9n2p4q1r',
  type: 'balance_threshold',
  threshold: {
    amount: 1000_00,
    currency: 'USDC'
  },
  channels: ['webhook', 'email'],
  recipients: ['[email protected]']
});

4. Configure Policies First

Always configure spending policies before funding:

// 1. Create account
const agent = await mppfi.agents.create({...});

// 2. Configure policies
await mppfi.policies.create({
  agentId: agent.id,
  rules: {...}
});

// 3. Then fund
await mppfi.agents.fund({
  agentId: agent.id,
  amount: 5000_00,
  currency: 'USDC'
});

---

Security Considerations

Key Management

• Private keys stored in Hardware Security Modules (HSM)

• Keys never exposed via API

• Agent signs transactions using MPPFi's secure signing service

• Backup keys stored in geo-distributed HSMs

Access Control

// Restrict agent access by IP
await mppfi.agents.setAccessControl('agent_7k3m9n2p4q1r', {
  allowedIPs: ['203.0.113.10', '198.51.100.0/24'],
  requireMFA: true,
  sessionTimeout: 3600 // 1 hour
});

Audit Logging

All agent operations are immutably logged:

const auditLog = await mppfi.agents.getAuditLog('agent_7k3m9n2p4q1r', {
  startDate: '2026-03-01',
  eventTypes: [
    'agent.created',
    'agent.funded',
    'policy.updated',
    'payment.executed',
    'agent.frozen'
  ]
});

auditLog.forEach(event => {
  console.log(`${event.timestamp}: ${event.type}`);
  console.log(`  Actor: ${event.actor}`);
  console.log(`  Details: ${JSON.stringify(event.details)}`);
  console.log(`  Blockchain Proof: ${event.blockchainProof}`);
});

---

Next Steps

• Payments - Execute transactions via MPP

• Spending Policies - Configure authorization rules

• Webhooks - Real-time event notifications

• REST API Reference - Complete API documentation

---

Dedicated banking accounts for every AI agent with blockchain-level transparency.