Quickstart Guide

Get your AI agent banking in under 10 minutes. This guide walks through creating an agent account, configuring spending policies, and executing your first autonomous payment on Solana via Machine Payments Protocol (MPP).

Prerequisites

Node.js 18+ or Python 3.9+
MPPFi API key (sign up)
Basic understanding of AI agent architecture
(Optional) Solana wallet for blockchain verification

What You'll Build

By the end of this guide, your AI agent will:

Have its own banking account with cryptographic identity
Hold USDC stablecoins on Solana blockchain
Execute autonomous payments within programmable spending limits
Settle transactions via Machine Payments Protocol in under 400ms

Installation

TypeScript/Node.js

npm install @mppfi/sdk

Python

pip install mppfi

Rust

cargo add mppfi

Step 1: Initialize the SDK

TypeScript

import { MPPFi } from '@mppfi/sdk';

const mppfi = new MPPFi({
  apiKey: process.env.MPPFI_API_KEY,
  network: 'mainnet-beta', // or 'devnet' for testing
});

console.log('MPPFi SDK initialized');
console.log('Network: Solana Mainnet');
console.log('Protocol: Machine Payments Protocol');

Python

import mppfi
import os

client = mppfi.Client(
    api_key=os.environ.get('MPPFI_API_KEY'),
    network='mainnet-beta'
)

print('MPPFi SDK initialized')
print('Network: Solana Mainnet')
print('Protocol: Machine Payments Protocol')

Rust

use mppfi::MPPFi;

fn main() {
    let client = MPPFi::new(
        std::env::var("MPPFI_API_KEY").unwrap(),
        "mainnet-beta",
    );

    println!("MPPFi SDK initialized");
    println!("Network: Solana Mainnet");
    println!("Protocol: Machine Payments Protocol");
}

Step 2: Create Agent Account

Each AI agent gets a dedicated banking account with cryptographic identity on Solana.

// Create agent account with cryptographic identity
const agent = await mppfi.agents.create({
  name: 'DataCollectorBot',
  description: 'Autonomous data acquisition agent',
  initialFunding: {
    amount: 1000_00, // $1,000 in cents
    currency: 'USDC'
  },
  metadata: {
    purpose: 'data_acquisition',
    department: 'research',
    operator: '[email protected]'
  }
});

console.log('Agent Account Created:');
console.log('  ID:', agent.id);
console.log('  Solana Address:', agent.solanaAddress);
console.log('  MPP Endpoint:', agent.mppEndpoint);
console.log('  Balance:', agent.balance.usdc, 'USDC');
console.log('  Blockchain:', 'Solana');

Response:

{
  "id": "agent_7k3m9n2p4q1r",
  "name": "DataCollectorBot",
  "solanaAddress": "8vQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "mppEndpoint": "https://mpp.mppfi.xyz/agent_7k3m9n2p4q1r",
  "publicKey": "0x8f3a9e2c1d4b5a6f...",
  "balance": {
    "usdc": "1000.00",
    "sol": "0.01"
  },
  "network": "solana-mainnet",
  "status": "active",
  "createdAt": "2026-03-30T10:30:00Z"
}

What just happened:

MPPFi created a dedicated account for your agent
Generated cryptographic identity (public/private key pair)
Created Solana blockchain address for settlement
Established MPP endpoint for protocol-compliant payments
Funded account with 1,000 USDC stablecoins

Step 3: Configure Spending Policy

Define programmable spending rules enforced on-chain via Solana smart contracts.

// Create spending policy with cryptographic enforcement
const policy = await mppfi.policies.create({
  agentId: agent.id,
  name: 'Data Acquisition Policy',
  rules: {
    // Velocity limits
    dailyLimit: {
      amount: 500_00, // $500/day
      currency: 'USDC'
    },
    perTransactionLimit: {
      amount: 100_00, // $100 per transaction
      currency: 'USDC'
    },

    // Merchant whitelist (MPP-compatible services)
    allowedMerchants: [
      'https://api.datasets.com/mpp',
      'https://api.clouddata.io/mpp',
      'https://api.research-data.com/mpp'
    ],

    // Time restrictions
    schedule: {
      allowedDays: [1, 2, 3, 4, 5], // Monday-Friday
      allowedHours: { start: 9, end: 17 }, // 9 AM - 5 PM UTC
      timezone: 'UTC'
    },

    // Require cryptographic proof for payments over $50
    requireProofAbove: 50_00
  },
  enforcement: 'on-chain', // Enforced via Solana smart contract
  expiresAt: '2026-12-31T23:59:59Z'
});

console.log('Spending Policy Created:');
console.log('  Policy ID:', policy.id);
console.log('  Smart Contract:', policy.solanaProgram);
console.log('  Daily Limit: $500');
console.log('  Enforcement: On-chain (Solana)');
console.log('  Status:', policy.status);

Security Note: All policy rules are enforced via Solana smart contracts, providing cryptographic guarantees that the agent cannot exceed these limits without explicit authorization updates.

Step 4: Make Your First Payment

Execute an autonomous payment using Machine Payments Protocol.

// Agent discovers MPP-compatible service
const serviceUrl = 'https://api.datasets.com/dataset/climate-2026';

// Agent requests payment terms via MPP
const paymentRequest = await mppfi.payments.requestTerms({
  agentId: agent.id,
  resourceUrl: serviceUrl,
  mppVersion: '1.0'
});

console.log('MPP Payment Request:');
console.log('  Resource:', paymentRequest.resource);
console.log('  Price:', paymentRequest.price.amount, paymentRequest.price.currency);
console.log('  Terms:', paymentRequest.terms);

// Agent authorizes payment within policy limits
const payment = await mppfi.payments.create({
  agentId: agent.id,
  paymentRequestId: paymentRequest.id,
  maxAmount: paymentRequest.price.amount,
  memo: 'Climate dataset purchase via MPP'
});

console.log('Payment Executed:');
console.log('  Payment ID:', payment.id);
console.log('  Amount:', payment.amount, payment.currency);
console.log('  Settlement Time:', payment.settlementTime, 'ms');
console.log('  Solana TX:', payment.solanaTxSignature);
console.log('  Block:', payment.blockNumber);
console.log('  Status:', payment.status);
console.log('  Policy Check: Passed');

Response:

{
  "id": "pay_9x7c5v3b2n1m",
  "agentId": "agent_7k3m9n2p4q1r",
  "amount": "45.00",
  "currency": "USDC",
  "merchantMppEndpoint": "https://api.datasets.com/mpp",
  "resource": "dataset/climate-2026",
  "status": "settled",
  "settlementTime": 287,
  "solanaTxSignature": "5j6k8m2n4p9q1r3s5t7u9v1w3x5y7z9...",
  "blockNumber": 187234567,
  "finalityStatus": "finalized",
  "policyValidation": {
    "passed": true,
    "dailySpent": "45.00",
    "dailyRemaining": "455.00"
  },
  "createdAt": "2026-03-30T11:45:23Z",
  "settledAt": "2026-03-30T11:45:23.287Z"
}

Settlement Flow:

Agent requests payment terms from merchant via MPP
Merchant responds with price and conditions
Agent authorizes payment (validated against spending policy)
MPPFi submits transaction to Solana blockchain
Settlement confirmed in ~287ms with cryptographic finality
Agent receives resource access token from merchant

Step 5: Verify On-Chain

Every transaction is verifiable on Solana blockchain.

// Get transaction details with blockchain proof
const transaction = await mppfi.transactions.get(payment.id);

console.log('Transaction Details:');
console.log('  Solana Explorer:');
console.log('   ', `https://explorer.solana.com/tx/${transaction.solanaTxSignature}`);
console.log('  From:', transaction.from);
console.log('  To:', transaction.to);
console.log('  Amount:', transaction.amount, transaction.currency);
console.log('  Block:', transaction.blockNumber);
console.log('  Confirmations:', transaction.confirmations);
console.log('  Finality:', transaction.finalityStatus);

// Verify cryptographic proof
const verification = await mppfi.transactions.verify(payment.id);

console.log('Cryptographic Verification:');
console.log('  Valid:', verification.valid);
console.log('  Signatures:', verification.signatures.length);
console.log('  Merkle Proof:', verification.merkleProof);
console.log('  On-Chain:', verification.onChain);

Step 6: Monitor Agent Activity

Query transaction history and spending analytics.

// Get current balance
const balance = await mppfi.agents.getBalance(agent.id);

console.log('Agent Balance:');
console.log('  USDC Available:', balance.usdc.available);
console.log('  USDC Pending:', balance.usdc.pending);
console.log('  SOL (for fees):', balance.sol);

// List recent transactions
const transactions = await mppfi.transactions.list({
  agentId: agent.id,
  limit: 10,
  status: 'settled'
});

console.log(`Recent Transactions (${transactions.length}):`);
transactions.forEach(tx => {
  console.log(`  ${tx.createdAt}: ${tx.amount} ${tx.currency}`);
  console.log(`    Merchant: ${tx.merchantName}`);
  console.log(`    Solana TX: ${tx.solanaTxSignature}`);
  console.log(`    Settlement: ${tx.settlementTime}ms`);
});

// Get spending analytics
const analytics = await mppfi.analytics.getSpending({
  agentId: agent.id,
  period: 'daily'
});

console.log('Spending Analytics:');
console.log('  Today:', analytics.today.total, analytics.currency);
console.log('  Remaining Limit:', analytics.today.remainingLimit);
console.log('  Transaction Count:', analytics.today.count);
console.log('  Average Amount:', analytics.today.average);
console.log('  Top Merchants:');
analytics.topMerchants.forEach(m => {
  console.log(`    ${m.name}: ${m.amount} ${m.currency}`);
});

Complete Example: Autonomous Data Agent

Full implementation of an AI agent that autonomously purchases datasets via MPP:

import { MPPFi } from '@mppfi/sdk';

async function setupDataAcquisitionAgent() {
  // 1. Initialize MPPFi
  const mppfi = new MPPFi({
    apiKey: process.env.MPPFI_API_KEY,
    network: 'mainnet-beta'
  });

  // 2. Create agent account
  const agent = await mppfi.agents.create({
    name: 'Research Data Agent',
    description: 'Autonomous data acquisition for ML training',
    initialFunding: {
      amount: 5000_00, // $5,000
      currency: 'USDC'
    },
    metadata: {
      purpose: 'ml_training_data',
      department: 'research',
      cost_center: 'ml-ops-001'
    }
  });

  console.log(`Agent created: ${agent.id}`);
  console.log(`Solana address: ${agent.solanaAddress}`);
  console.log(`MPP endpoint: ${agent.mppEndpoint}`);

  // 3. Configure spending policy
  const policy = await mppfi.policies.create({
    agentId: agent.id,
    name: 'ML Data Acquisition Policy',
    rules: {
      dailyLimit: { amount: 1000_00, currency: 'USDC' },
      perTransactionLimit: { amount: 200_00, currency: 'USDC' },
      allowedMerchants: [
        'https://api.kaggle.com/mpp',
        'https://api.huggingface.co/mpp',
        'https://api.datasets.com/mpp'
      ],
      schedule: {
        allowedDays: [1, 2, 3, 4, 5],
        allowedHours: { start: 0, end: 23 },
        timezone: 'UTC'
      },
      requireProofAbove: 100_00
    },
    enforcement: 'on-chain'
  });

  console.log(`Policy created: ${policy.id}`);
  console.log(`Smart contract: ${policy.solanaProgram}`);

  // 4. Setup webhook notifications
  const webhook = await mppfi.webhooks.create({
    url: 'https://api.yourcompany.com/webhooks/mppfi',
    events: [
      'payment.completed',
      'payment.failed',
      'policy.violated',
      'balance.low'
    ],
    secret: process.env.WEBHOOK_SECRET
  });

  console.log(`Webhook configured: ${webhook.id}`);

  // 5. Configure low balance alerts
  await mppfi.alerts.create({
    agentId: agent.id,
    type: 'balance_threshold',
    threshold: {
      amount: 500_00,
      currency: 'USDC'
    },
    channels: ['webhook', 'email']
  });

  console.log('Low balance alerts configured');

  // 6. Return agent credentials
  return {
    agentId: agent.id,
    solanaAddress: agent.solanaAddress,
    mppEndpoint: agent.mppEndpoint,
    publicKey: agent.publicKey,
    policyId: policy.id,
    dashboard: `https://app.mppfi.xyz/agents/${agent.id}`,
    explorer: `https://explorer.solana.com/address/${agent.solanaAddress}`,
    balance: agent.balance
  };
}

// Execute setup
setupDataAcquisitionAgent()
  .then(result => {
    console.log('\nAgent Setup Complete!');
    console.log(JSON.stringify(result, null, 2));
  })
  .catch(error => {
    console.error('Setup failed:', error);
    process.exit(1);
  });

Sandbox Testing

Test all functionality without real funds on Solana Devnet:

const mppfi = new MPPFi({
  apiKey: process.env.MPPFI_SANDBOX_KEY,
  network: 'devnet'
});

// Everything works identically
// Use devnet USDC and SOL from faucets

Get testnet tokens:

Devnet SOL: solana airdrop 2 or Solana Faucet
Devnet USDC: MPPFi Faucet
Test MPP Services: MPPFi Sandbox Merchants

Key Concepts

Cryptographic Agent Identity

Each agent has a unique public/private key pair:

Public key: Identifies agent in transactions
Private key: Signs transactions (managed by MPPFi HSM)
Solana address: Blockchain account for settlement
MPP endpoint: Protocol-compliant payment receiver

Machine Payments Protocol (MPP)

Standardized protocol for machine-to-machine payments:

Agent requests payment terms from merchant
Merchant responds with price and conditions
Agent authorizes payment with cryptographic signature
Settlement via Solana blockchain with sub-second finality
Merchant delivers resource/service to agent

On-Chain Settlement

All transactions settled on Solana blockchain:

Speed: 150ms finality (Alpenglow consensus)
Cost: ~$0.0011 per transaction
Throughput: 65,000 TPS (theoretical 1M+ with Firedancer)
Finality: Cryptographic proof of settlement
Auditability: Every transaction verifiable on-chain

Programmable Spending Policies

Rules enforced via Solana smart contracts:

Velocity limits: Daily/monthly spending caps
Merchant restrictions: Whitelist of approved MPP endpoints
Time-based rules: Schedule-based payment authorization
Multi-signature: Require approvals for high-value transactions
Zero-knowledge proofs: Privacy-preserving transaction validation

Next Steps

Core Documentation

Authentication - API key management and security
Agent Accounts - Advanced account operations
Spending Policies - Comprehensive policy configuration
Payments - MPP payment flows

Technical Deep Dives

Architecture - System design and components
Authorization Engine - Policy enforcement
Solana Integration - Blockchain settlement
MPP Implementation - Protocol specification

API Reference

REST API - Complete endpoint documentation
SDKs - TypeScript, Python, Rust libraries
Errors - Error codes and handling

Common Issues

Issue: Transaction Failed - Policy Violation

Error: Transaction failed: Policy violation - daily limit exceeded

Solution: Check remaining spending limit:

const analytics = await mppfi.analytics.getSpending({
  agentId: agent.id,
  period: 'daily'
});
console.log('Remaining limit:', analytics.remainingLimit);

Issue: Insufficient Balance

Error: Insufficient USDC balance for payment

Solution: Fund agent account:

// Via API
await mppfi.agents.fund({
  agentId: agent.id,
  amount: 1000_00,
  currency: 'USDC'
});

// Or via blockchain transfer to agent's Solana address

Issue: Merchant Not MPP-Compatible

Error: Merchant does not support Machine Payments Protocol

Solution: Verify merchant MPP endpoint:

// Check merchant MPP support
const mppInfo = await mppfi.merchants.getMppInfo(merchantUrl);
console.log('MPP supported:', mppInfo.supported);
console.log('MPP version:', mppInfo.version);
console.log('MPP endpoint:', mppInfo.endpoint);

Issue: Slow Transaction Settlement

Warning: Transaction taking longer than expected

Solution: Check Solana network status:

Performance Tips

Optimize Settlement Speed

// Use priority fees for faster confirmation
const payment = await mppfi.payments.create({
  agentId: agent.id,
  paymentRequestId: request.id,
  priorityFee: 'high' // 'low' | 'medium' | 'high'
});

Batch Multiple Payments

// Execute multiple payments in single transaction
const batch = await mppfi.payments.batch({
  agentId: agent.id,
  payments: [
    { merchantUrl: 'merchant1.com/mpp', amount: 10_00 },
    { merchantUrl: 'merchant2.com/mpp', amount: 20_00 },
    { merchantUrl: 'merchant3.com/mpp', amount: 30_00 }
  ]
});

console.log(`Batch executed: ${batch.payments.length} payments in ${batch.settlementTime}ms`);

Cache MPP Endpoints

// Cache merchant MPP endpoints to avoid lookups
const mppCache = new Map();

async function getMppEndpoint(merchantUrl) {
  if (mppCache.has(merchantUrl)) {
    return mppCache.get(merchantUrl);
  }

  const info = await mppfi.merchants.getMppInfo(merchantUrl);
  mppCache.set(merchantUrl, info.endpoint);
  return info.endpoint;
}

Support

Documentation: docs.mppfi.xyz
Discord: discord.gg/mppfi
Email: [email protected]
Status: status.mppfi.xyz
GitHub: github.com/mppfi

Your AI agent is now ready to transact autonomously on the world's first neobank built for AI agents.

PreviousOverview NextAuthentication

Last updated 3 hours ago

Was this helpful?

Good afternoon

hashtagPrerequisites

hashtagWhat You'll Build

hashtagInstallation

hashtagTypeScript/Node.js

hashtagPython

hashtagRust

hashtagStep 1: Initialize the SDK

hashtagTypeScript

hashtagPython

hashtagRust

hashtagStep 2: Create Agent Account

hashtagStep 3: Configure Spending Policy

hashtagStep 4: Make Your First Payment

hashtagStep 5: Verify On-Chain

hashtagStep 6: Monitor Agent Activity

hashtagComplete Example: Autonomous Data Agent

hashtagSandbox Testing

hashtagKey Concepts

hashtagCryptographic Agent Identity

hashtagMachine Payments Protocol (MPP)

hashtagOn-Chain Settlement

hashtagProgrammable Spending Policies

hashtagNext Steps

hashtagCore Documentation

hashtagTechnical Deep Dives

hashtagAPI Reference

hashtagCommon Issues

hashtagIssue: Transaction Failed - Policy Violation

hashtagIssue: Insufficient Balance

hashtagIssue: Merchant Not MPP-Compatible

hashtagIssue: Slow Transaction Settlement

hashtagPerformance Tips

hashtagOptimize Settlement Speed

hashtagBatch Multiple Payments

hashtagCache MPP Endpoints

hashtagSupport

Prerequisites

What You'll Build

Installation

TypeScript/Node.js

Python

Rust

Step 1: Initialize the SDK

TypeScript

Python

Rust

Step 2: Create Agent Account

Step 3: Configure Spending Policy

Step 4: Make Your First Payment

Step 5: Verify On-Chain

Step 6: Monitor Agent Activity

Complete Example: Autonomous Data Agent

Sandbox Testing

Key Concepts

Cryptographic Agent Identity

Machine Payments Protocol (MPP)

On-Chain Settlement

Programmable Spending Policies

Next Steps

Core Documentation

Technical Deep Dives

API Reference

Common Issues

Issue: Transaction Failed - Policy Violation

Issue: Insufficient Balance

Issue: Merchant Not MPP-Compatible

Issue: Slow Transaction Settlement

Performance Tips

Optimize Settlement Speed

Batch Multiple Payments

Cache MPP Endpoints

Support