MPP Payments

MPPFi enables AI agents to execute financial transactions autonomously using the Machine Payments Protocol (MPP) on Solana blockchain. All payments are cryptographically signed, policy-enforced, and settled on-chain with sub-second finality.

Payment Flow Architecture

Standard Payment Lifecycle

1. Payment Initiation (Agent)
   └─> Policy Validation (MPPFi)
       └─> Transaction Construction (Solana)
           └─> Cryptographic Signing (Agent HSM)
               └─> On-Chain Settlement (Solana Network)
                   └─> Confirmation & Receipt (MPP Protocol)
                       └─> Webhook Notification (Real-time)

Machine Payments Protocol (MPP)

MPP is the standardized protocol for agent-to-merchant payments:

• Discovery: Merchants expose MPP endpoints for agent discovery

• Negotiation: Agents evaluate pricing, terms, and payment methods

• Authorization: Cryptographic signatures prove agent identity

• Settlement: On-chain transfers with atomic guarantees

• Verification: Blockchain proofs provide immutable receipts

Payment Types

1. Direct Transfers

Send funds directly to another Solana address.

const payment = await mppfi.payments.create({
  agentId: 'agt_7xK9mN2pQ1',
  type: 'transfer',
  amount: 50.00,
  currency: 'USDC',
  destination: {
    address: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
    network: 'solana-mainnet'
  },
  description: 'API service payment',
  metadata: {
    invoice_id: 'inv_abc123',
    service: 'text-to-speech-api'
  }
});

// Response includes blockchain proof
console.log(payment.blockchain.signature); // Transaction hash
console.log(payment.blockchain.block); // Block number
console.log(payment.blockchain.timestamp); // Settlement time

Response:

{
  "id": "pmt_9xL4mP7qR2",
  "object": "payment",
  "status": "completed",
  "type": "transfer",
  "amount": 50.00,
  "currency": "USDC",
  "agent_id": "agt_7xK9mN2pQ1",
  "destination": {
    "address": "GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P",
    "network": "solana-mainnet"
  },
  "blockchain": {
    "network": "solana-mainnet",
    "signature": "5JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA",
    "block": 245678901,
    "timestamp": "2025-01-15T14:32:45Z",
    "confirmations": 32,
    "explorer_url": "https://solscan.io/tx/5JzGW8jvKmF3X9vqYdN2pR7nL4cB8hZ1kQxE6tS3wP2mV9uA"
  },
  "fees": {
    "network_fee": 0.000005,
    "network_fee_currency": "SOL",
    "platform_fee": 0.10,
    "platform_fee_currency": "USDC"
  },
  "created_at": "2025-01-15T14:32:43Z",
  "completed_at": "2025-01-15T14:32:45Z"
}

2. MPP Service Payments

Pay for services using Machine Payments Protocol.

from mppfi import Client

client = Client(api_key='sk_live_...')

# Discover merchant MPP endpoint
merchant = client.merchants.discover(
    domain='api.transcription.ai'
)

# Create MPP payment
payment = client.payments.create_mpp(
    agent_id='agt_7xK9mN2pQ1',
    merchant_endpoint=merchant.mpp_endpoint,
    service='audio_transcription',
    amount=5.00,
    currency='USDC',
    parameters={
        'duration_minutes': 30,
        'language': 'en-US',
        'quality': 'premium'
    }
)

# Payment includes service access token
print(f"Service token: {payment.service_token}")
print(f"Valid until: {payment.token_expiry}")
print(f"Transaction: {payment.blockchain.signature}")

MPP Payment Flow:

1. Discovery: Agent queries merchant's MPP manifest

2. Quotation: Merchant provides real-time pricing

3. Authorization: Agent signs payment with private key

4. Settlement: Funds transferred on Solana blockchain

5. Access: Merchant grants service token upon confirmation

3. Recurring Payments

Schedule automated payments with on-chain enforcement.

use mppfi::{Client, RecurringPayment, Frequency};

let client = Client::new("sk_live_...");

let subscription = client.payments().create_recurring(RecurringPayment {
    agent_id: "agt_7xK9mN2pQ1".to_string(),
    destination_address: "GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P".to_string(),
    amount: 99.00,
    currency: "USDC".to_string(),
    frequency: Frequency::Monthly,
    start_date: "2025-02-01".to_string(),
    end_date: Some("2025-12-31".to_string()),
    description: "Cloud infrastructure subscription".to_string(),
    policy_enforced: true,
}).await?;

println!("Subscription ID: {}", subscription.id);
println!("Next payment: {}", subscription.next_payment_date);
println!("Smart contract: {}", subscription.blockchain.contract_address);

Recurring Payment Features:

• Smart Contract Enforcement: Payments executed by Solana program

• Predictable Scheduling: Precise timing with blockchain timestamps

• Policy Compliance: Each payment validates against spending limits

• Atomic Cancellation: Cancel anytime with on-chain guarantee

• Payment History: Complete audit trail on blockchain

4. Batch Payments

Execute multiple payments atomically in a single transaction.

const batch = await mppfi.payments.createBatch({
  agentId: 'agt_7xK9mN2pQ1',
  payments: [
    {
      destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
      amount: 25.00,
      currency: 'USDC',
      reference: 'supplier_a_invoice_001'
    },
    {
      destination: '8qN5L3kZ9xM2vY7cB4jT6wE1rP9sU5hG3fD8aQ2nK7m',
      amount: 40.00,
      currency: 'USDC',
      reference: 'supplier_b_invoice_002'
    },
    {
      destination: 'F3xR9vQ2mL7nP5jK8cW4yT6zS1bN9hG2dA5eU8fV3k',
      amount: 15.00,
      currency: 'USDC',
      reference: 'supplier_c_invoice_003'
    }
  ],
  atomic: true // All succeed or all fail
});

console.log(`Batch ${batch.id}: ${batch.payments.length} payments`);
console.log(`Total amount: ${batch.total_amount} ${batch.currency}`);
console.log(`Transaction: ${batch.blockchain.signature}`);

Batch Payment Benefits:

• Atomic Execution: All payments succeed or all fail together

• Cost Efficiency: Single transaction fee for multiple transfers

• Parallel Processing: Leverages Solana's parallel execution

• Simplified Accounting: One transaction ID for entire batch

Payment States

pending ──> processing ──> completed
                │              │
                └──> failed    │
                               │
                          cancelled

State Descriptions

State	Description	Actions Available
pending	Payment created, awaiting policy validation	Cancel
processing	Policy approved, transaction submitted to blockchain	Monitor
completed	Transaction confirmed on-chain	Refund (if supported)
failed	Transaction rejected or blockchain failure	Retry, Cancel
cancelled	Payment cancelled before processing	None

Policy Enforcement

All payments are validated against agent spending policies before execution.

Policy Check Example

// Check if payment will be approved
const policyCheck = await mppfi.payments.validatePolicy({
  agentId: 'agt_7xK9mN2pQ1',
  amount: 150.00,
  currency: 'USDC',
  merchant: 'api.transcription.ai',
  category: 'ai_services'
});

if (policyCheck.approved) {
  // Proceed with payment
  const payment = await mppfi.payments.create({...});
} else {
  console.log(`Blocked: ${policyCheck.reason}`);
  console.log(`Daily limit: ${policyCheck.limits.daily_remaining}`);
}

Policy Validations:

• Amount Limits: Per-transaction, daily, weekly, monthly caps

• Merchant Allowlists: Approved recipient addresses only

• Category Restrictions: Spending limits by service category

• Time Windows: Allowed hours/days for transactions

• Velocity Checks: Maximum transactions per time period

• Balance Requirements: Minimum balance thresholds

Payment Methods

Supported Assets

MPPFi supports multiple digital assets on Solana:

Asset	Type	Network	Use Case
USDC	Stablecoin	Solana SPL	Primary payment currency
USDT	Stablecoin	Solana SPL	Alternative stablecoin
SOL	Native	Solana	Network fees, native payments
EURC	Stablecoin	Solana SPL	Euro-denominated payments
Custom SPL	Token	Solana SPL	Project-specific tokens

Currency Conversion

# Get real-time exchange rate
rate = client.payments.get_exchange_rate(
    from_currency='SOL',
    to_currency='USDC',
    amount=10.0
)

# Create payment with automatic conversion
payment = client.payments.create(
    agent_id='agt_7xK9mN2pQ1',
    amount=10.0,
    source_currency='SOL',
    destination_currency='USDC',
    destination_address='GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
    conversion={
        'rate': rate.rate,
        'rate_id': rate.id,
        'valid_until': rate.valid_until
    }
)

Transaction Fees

Fee Structure

Total Cost = Payment Amount + Platform Fee + Network Fee

Platform Fees:

• 0.2% per transaction (minimum $0.10)

• Volume discounts available for high-throughput agents

• Free for intra-MPPFi transfers

Network Fees (Solana):

• 0.000005 SOL per transaction ($0.001)

• Paid from agent's SOL balance

• Automatic SOL top-up available

Fee Estimation

let estimate = client.payments().estimate_fees(PaymentRequest {
    amount: 100.00,
    currency: "USDC".to_string(),
    payment_type: PaymentType::Transfer,
    destination_network: "solana-mainnet".to_string(),
}).await?;

println!("Payment amount: {} {}", estimate.amount, estimate.currency);
println!("Platform fee: {} {}", estimate.platform_fee, estimate.currency);
println!("Network fee: {} SOL", estimate.network_fee);
println!("Total cost: {} {}", estimate.total_cost, estimate.currency);

Payment Receipts

Every payment includes a cryptographically verifiable receipt.

const receipt = await mppfi.payments.getReceipt('pmt_9xL4mP7qR2');

console.log('Receipt Verification:');
console.log(`- Signature: ${receipt.blockchain.signature}`);
console.log(`- Block: ${receipt.blockchain.block}`);
console.log(`- Timestamp: ${receipt.blockchain.timestamp}`);
console.log(`- Confirmations: ${receipt.blockchain.confirmations}`);

// Verify on-chain
const verified = await mppfi.payments.verifyReceipt(receipt.id);
console.log(`Receipt valid: ${verified.is_valid}`);
console.log(`Explorer: ${verified.explorer_url}`);

Receipt Contents:

• Payment Details: Amount, currency, participants

• Blockchain Proof: Transaction hash, block number, timestamp

• Cryptographic Signature: Agent's signature over payment data

• Policy Attestation: Hash of enforced spending policy

• Verification URL: Direct link to blockchain explorer

Refunds and Reversals

Initiating Refunds

# Request refund from merchant
refund = client.payments.create_refund(
    payment_id='pmt_9xL4mP7qR2',
    amount=50.00,  # Partial or full refund
    reason='service_not_delivered',
    notes='API endpoint was unavailable'
)

print(f"Refund ID: {refund.id}")
print(f"Status: {refund.status}")
print(f"Transaction: {refund.blockchain.signature}")

Refund Process:

1. Agent or merchant initiates refund request

2. Counterparty approves (if required by merchant policy)

3. New blockchain transaction created for reverse transfer

4. Funds returned to agent's account

5. Original payment marked as refunded

Important Notes:

• Refunds are new transactions, not blockchain reversals

• Network fees apply to refund transactions

• Partial refunds supported

• Refund history linked to original payment

Payment Security

Cryptographic Verification

Every payment is signed with the agent's private key:

// Payment signature flow
const payment = {
  agent_id: 'agt_7xK9mN2pQ1',
  amount: 50.00,
  currency: 'USDC',
  destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
  nonce: 'unique_payment_nonce_12345',
  timestamp: '2025-01-15T14:32:43Z'
};

// SDK automatically signs with HSM-stored private key
const signature = await mppfi.agents.signPayment(
  'agt_7xK9mN2pQ1',
  payment
);

// Submit signed payment
const result = await mppfi.payments.submit({
  ...payment,
  signature: signature
});

Security Features

• HSM Key Storage: Private keys never leave hardware security modules

• Non-Replayability: Nonces prevent transaction replay attacks

• Time-Limited Signatures: Signatures expire after 60 seconds

• Multi-Signature Support: Optional co-signing for high-value payments

• Blockchain Finality: Irreversible confirmation in <1 second

• Policy Pre-Flight: All payments validated before signing

Monitoring and Analytics

Real-Time Payment Tracking

# Stream payment events
for event in client.payments.stream_events(agent_id='agt_7xK9mN2pQ1'):
    if event.type == 'payment.processing':
        print(f"Payment {event.payment_id} submitted to blockchain")
    elif event.type == 'payment.completed':
        print(f"Payment {event.payment_id} confirmed in block {event.block}")
    elif event.type == 'payment.failed':
        print(f"Payment {event.payment_id} failed: {event.reason}")

Payment Analytics

const analytics = await mppfi.payments.getAnalytics({
  agentId: 'agt_7xK9mN2pQ1',
  period: 'last_30_days',
  groupBy: 'merchant'
});

console.log('Payment Analytics:');
analytics.groups.forEach(group => {
  console.log(`${group.merchant}:`);
  console.log(`  - Total: ${group.total_amount} ${group.currency}`);
  console.log(`  - Count: ${group.payment_count}`);
  console.log(`  - Average: ${group.average_amount}`);
});

Error Handling

use mppfi::{Client, PaymentError};

match client.payments().create(payment_request).await {
    Ok(payment) => {
        println!("Payment successful: {}", payment.id);
    },
    Err(e) => match e {
        PaymentError::InsufficientFunds { required, available } => {
            eprintln!("Insufficient funds: need {}, have {}", required, available);
        },
        PaymentError::PolicyViolation { reason, limit } => {
            eprintln!("Policy blocked: {} (limit: {})", reason, limit);
        },
        PaymentError::InvalidDestination { address } => {
            eprintln!("Invalid Solana address: {}", address);
        },
        PaymentError::BlockchainError { message } => {
            eprintln!("Blockchain error: {}", message);
        },
        _ => eprintln!("Payment failed: {:?}", e),
    }
}

Best Practices

1. Idempotency

Use idempotency keys to prevent duplicate payments:

const payment = await mppfi.payments.create({
  agentId: 'agt_7xK9mN2pQ1',
  amount: 50.00,
  currency: 'USDC',
  destination: 'GHvFFSZ8dDbN9eDeTe3vPqX7jHhgYFLkLGVrHjG6FH2P',
  idempotencyKey: 'payment_invoice_abc123_attempt_1'
});

2. Webhook Confirmations

Don't rely solely on API responses for confirmation:

# Listen for webhook confirmation
@app.route('/webhooks/mppfi', methods=['POST'])
def handle_webhook():
    event = client.webhooks.construct_event(
        request.data,
        request.headers['MPPFi-Signature'],
        webhook_secret
    )

    if event.type == 'payment.completed':
        payment_id = event.data.object.id
        # Update internal records
        mark_payment_complete(payment_id)

    return '', 200

3. Balance Management

Monitor balances before initiating payments:

const balance = await mppfi.accounts.getBalance('agt_7xK9mN2pQ1');

if (balance.available.USDC >= paymentAmount + estimatedFees) {
  await mppfi.payments.create({...});
} else {
  console.log('Insufficient balance, funding required');
  await initiateTopUp();
}

4. Retry Logic

Implement exponential backoff for transient failures:

import time

def create_payment_with_retry(payment_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            payment = client.payments.create(**payment_data)
            return payment
        except mppfi.errors.RateLimitError:
            wait_time = 2 ** attempt  # Exponential backoff
            time.sleep(wait_time)
        except mppfi.errors.BlockchainError as e:
            if e.retryable:
                time.sleep(2 ** attempt)
            else:
                raise
    raise Exception('Payment failed after retries')

5. Transaction Receipts

Always store blockchain signatures for audit trails:

let payment = client.payments().create(payment_request).await?;

// Store critical fields in your database
database.store_payment_record(PaymentRecord {
    internal_id: generate_internal_id(),
    mppfi_payment_id: payment.id.clone(),
    blockchain_signature: payment.blockchain.signature.clone(),
    block_number: payment.blockchain.block,
    amount: payment.amount,
    currency: payment.currency.clone(),
    timestamp: payment.blockchain.timestamp,
    explorer_url: payment.blockchain.explorer_url.clone(),
}).await?;

Rate Limits

Payment endpoints have the following rate limits:

Endpoint	Limit	Window
Create payment	100 requests	1 minute
Batch payments	20 requests	1 minute
List payments	300 requests	1 minute
Get payment	1000 requests	1 minute

Note: Solana blockchain can process 65,000 transactions per second, so blockchain throughput is not a bottleneck.

Next Steps

• Learn about Spending Policies for payment control

• Configure Webhooks for real-time notifications

• Review API Reference for complete endpoint documentation

• Explore Architecture for system design details