Smart Agents and USDC: Developer Guide

Enable AI agents to autonomously execute commerce transactions using native USDC on StateSet

The SDK packages this page imports (@stateset/agent-sdk) are not yet published to npm — the code shows the intended integration surface. Contact us for access before building against it.

A companion guide covers the same ground from the other side — see Smart agents on the Commerce Network. If the two disagree on an endpoint or a package name, the one that matches the API reference is the current one.

Smart Agents: Autonomous Commerce with USDC

Overview

StateSet Commerce Network enables AI agents to transact autonomously using native USDC, creating a new paradigm for automated commerce. This guide covers how to build, deploy, and manage smart agents that can execute transactions, manage inventory, optimize pricing, and handle complex commercial workflows - all without human intervention.

Why Smart Agents on StateSet?

The Perfect Environment for Agent Commerce

• Native USDC: Agents transact in stable digital dollars
• No Gas Complexity: Fees paid directly in USDC
• Instant Settlement: Sub-second transaction finality
• Rich APIs: Comprehensive commerce modules
• Built-in Compliance: KYC/AML checks automated
• Programmable Logic: Smart contracts enforce boundaries

Quick Start: Your First Trading Agent

import { StatesetAgent, AgentWallet } from '@stateset/agent-sdk';

// Initialize an agent with spending limits
const agent = new StatesetAgent({
  name: 'TradingBot-001',
  wallet: new AgentWallet({
    seed: process.env.AGENT_SEED,
    spendingLimit: '10000.00', // Daily USDC limit
    approvedContracts: ['StateSet1abc...'] // Whitelisted contracts
  }),
  capabilities: ['trade', 'analyze', 'report']
});

// Agent autonomously executes trades
await agent.execute({
  task: 'optimize_inventory',
  parameters: {
    targetMargin: 0.15,
    maxOrderSize: '1000.00',
    reorderPoint: 100
  }
});

Architecture: How Agent Commerce Works

Core Concepts

1. Agent Wallets

Agent wallets are specialized accounts with built-in safety features:

const agentWallet = new AgentWallet({
  // Hierarchical deterministic wallet for the agent
  seed: generateSecureSeed(),
  
  // Safety parameters
  limits: {
    perTransaction: '1000.00',
    daily: '10000.00',
    monthly: '100000.00'
  },
  
  // Allowed operations
  permissions: {
    allowedMethods: ['transfer', 'swap', 'stake'],
    blockedAddresses: ['suspicious1...'],
    requiresApproval: ['amount > 5000']
  }
});

2. Agent Permissions

Fine-grained control over agent capabilities:

// Define agent boundaries
const permissions = {
  // Financial limits
  spending: {
    max_per_tx: '5000.00',
    max_daily: '25000.00',
    require_2fa_above: '10000.00'
  },
  
  // Operational constraints
  operations: {
    can_create_orders: true,
    can_modify_prices: true,
    max_price_change: 0.10, // 10%
    blackout_hours: [0, 6] // No trades 12am-6am
  },
  
  // Smart contract interactions
  contracts: {
    whitelist: ['dex_contract', 'lending_protocol'],
    max_gas_per_tx: '1.00' // USDC
  }
};

3. Agent State Management

Agents maintain state across transactions:

interface AgentState {
  wallet: {
    address: string;
    balance: string; // USDC balance
    nonce: number;
  };
  
  metrics: {
    total_transactions: number;
    total_volume: string;
    success_rate: number;
    profit_loss: string;
  };
  
  inventory: {
    products: Product[];
    total_value: string;
    turnover_rate: number;
  };
  
  learning: {
    model_version: string;
    last_training: Date;
    performance_score: number;
  };
}

Give an agent its own wallet with its own ceiling, never a shared treasury key. An agent’s spend is driven by a task loop that retries, and a loop that retries a failing purchase against an unbounded balance will keep paying. Fund the wallet with what the task is worth and top it up deliberately.

Use Cases

1. 🛒 E-Commerce Price Optimization

const pricingAgent = new StatesetAgent({
  name: 'DynamicPricer',
  type: 'pricing_optimizer'
});

// Agent monitors competitors and adjusts prices
pricingAgent.addStrategy({
  name: 'competitive_pricing',
  async execute(context) {
    // Get competitor prices
    const competitors = await context.fetchCompetitorPrices();
    
    // Calculate optimal price
    const optimalPrice = context.ml.calculatePrice({
      competitors,
      inventory: context.inventory,
      demand: context.demandForecast,
      targetMargin: 0.20
    });
    
    // Update price on Stateset
    if (Math.abs(optimalPrice - context.currentPrice) > 0.50) {
      await context.stateset.products.update({
        sku: context.product.sku,
        price: optimalPrice.toFixed(2),
        reason: 'Competitive adjustment'
      });
    }
  },
  
  frequency: 'every 15 minutes',
  limits: {
    maxPriceChange: 0.15, // 15% max change
    minMargin: 0.10 // 10% minimum margin
  }
});

2. 💱 Arbitrage Trading

const arbitrageBot = new StatesetAgent({
  name: 'ArbitrageHunter',
  type: 'trading'
});

// Multi-DEX arbitrage scanner
arbitrageBot.addStrategy({
  name: 'dex_arbitrage',
  async execute(context) {
    // Monitor price differences across DEXs
    const opportunities = await context.scanArbitrage({
      pairs: ['USDC/STATE', 'ATOM/USDC'],
      minProfit: '10.00', // Minimum $10 profit
      maxSlippage: 0.005 // 0.5% slippage tolerance
    });
    
    for (const opp of opportunities) {
      // Calculate profit after fees
      const netProfit = opp.profit - (opp.fees * 2);
      
      if (netProfit > 10) {
        // Execute arbitrage atomically
        await context.executeArbitrage({
          buyOn: opp.cheaperDex,
          sellOn: opp.expensiveDex,
          amount: opp.optimalAmount,
          deadline: Date.now() + 30000 // 30 second deadline
        });
      }
    }
  },
  
  frequency: 'continuous',
  riskLimits: {
    maxPositionSize: '5000.00',
    maxOpenPositions: 3,
    stopLoss: '100.00'
  }
});

3. 📦 Supply Chain Automation

const supplyChainAgent = new StatesetAgent({
  name: 'SupplyManager',
  type: 'operations'
});

// Automated reordering system
supplyChainAgent.addStrategy({
  name: 'auto_reorder',
  async execute(context) {
    const inventory = await context.stateset.inventory.list();
    
    for (const item of inventory) {
      // Check if reorder needed
      if (item.quantity <= item.reorderPoint) {
        // Calculate optimal order quantity
        const orderQty = context.calculateEOQ({
          demand: item.avgDailyDemand * 30,
          orderCost: '50.00',
          holdingCost: item.value * 0.20 / 365
        });
        
        // Find best supplier
        const suppliers = await context.findSuppliers(item.sku);
        const bestSupplier = context.selectSupplier(suppliers, {
          criteria: ['price', 'delivery_time', 'reliability'],
          weights: [0.4, 0.3, 0.3]
        });
        
        // Create purchase order
        const po = await context.stateset.purchaseorders.create({
          supplier: bestSupplier.did,
          items: [{
            sku: item.sku,
            quantity: orderQty,
            price: bestSupplier.price
          }],
          terms: 'Net 30',
          delivery: bestSupplier.estimatedDelivery
        });
        
        // Pay with USDC if early payment discount available
        if (bestSupplier.earlyPayDiscount > 0.02) {
          // Paying an order is REST-only today: POST /v1/orders/{order_id}/pay
          await fetch(`https://api.stateset.com/v1/orders/${po.id}/pay`, {
            method: 'POST',
            headers: {
              Authorization: `Bearer ${process.env.STATESET_API_KEY}`,
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              amount: po.total * (1 - bestSupplier.earlyPayDiscount)
            })
          });
        }
      }
    }
  },
  
  frequency: 'daily at 6am UTC'
});

4. 🤖 Customer Service Agent

const customerAgent = new StatesetAgent({
  name: 'CustomerSupport',
  type: 'service'
});

// Automated refund processing
customerAgent.addCapability({
  name: 'process_refunds',
  async execute(context, request) {
    // Validate refund request
    const order = await context.stateset.orders.get(request.orderId);
    const validation = await context.validateRefund(order, request);
    
    if (validation.approved) {
      // Process instant USDC refund
      const refund = await context.stateset.orders.processRefund({
        order_id: order.id,
        amount: validation.refundAmount,
        reason: validation.reason,
        items: validation.items
      });
      
      // Update customer record
      await context.updateCustomerRecord({
        customerId: order.customerId,
        event: 'refund_processed',
        amount: refund.amount,
        satisfaction: request.satisfaction
      });
      
      return {
        success: true,
        refundId: refund.id,
        message: `Refund of ${refund.amount} USDC processed successfully`
      };
    }
    
    return {
      success: false,
      reason: validation.rejectionReason,
      alternativeOptions: validation.alternatives
    };
  },
  
  limits: {
    maxRefundAmount: '500.00',
    requiresHumanApproval: ['amount > 500', 'frequency > 3']
  }
});

5. 💰 Yield Optimization

const yieldAgent = new StatesetAgent({
  name: 'YieldOptimizer',
  type: 'defi'
});

// Optimize idle USDC balances
yieldAgent.addStrategy({
  name: 'optimize_treasury',
  async execute(context) {
    // Get current balance
    const balance = await context.getUSDCBalance();
    const reserves = balance * 0.20; // Keep 20% liquid
    const deployable = balance - reserves;
    
    if (deployable > 1000) {
      // Analyze yield opportunities
      const opportunities = await context.analyzeYield({
        chains: ['Stateset', 'osmosis', 'neutron'],
        protocols: ['lending', 'liquidity', 'staking'],
        minAPR: 0.05,
        maxRisk: 'medium'
      });
      
      // Diversify across strategies
      const allocation = context.optimizeAllocation({
        amount: deployable,
        opportunities,
        constraints: {
          maxPerProtocol: 0.40,
          minLiquidity: 'daily',
          targetAPR: 0.08
        }
      });
      
      // Deploy capital
      for (const alloc of allocation) {
        await context.deployCapital({
          protocol: alloc.protocol,
          amount: alloc.amount,
          duration: alloc.lockPeriod,
          autoCompound: true
        });
      }
    }
  },
  
  frequency: 'daily',
  monitoring: {
    checkHealth: 'hourly',
    rebalanceThreshold: 0.05,
    emergencyWithdraw: ['protocol_risk > high', 'apr_drop > 50%']
  }
});

Advanced Features

Multi-Agent Systems

Deploy fleets of specialized agents working together:

const agentOrchestrator = new AgentOrchestrator({
  agents: [
    { id: 'sourcing-01', type: 'procurement', budget: '50000.00' },
    { id: 'pricing-01', type: 'revenue', budget: '10000.00' },
    { id: 'logistics-01', type: 'fulfillment', budget: '20000.00' },
    { id: 'finance-01', type: 'treasury', budget: '100000.00' }
  ],
  
  coordination: {
    communicationProtocol: 'mesh', // Agents communicate directly
    consensusRequired: ['budget > 10000', 'risk > medium'],
    disputeResolution: 'voting'
  }
});

// Agents collaborate on complex tasks
await agentOrchestrator.executeWorkflow({
  name: 'new_product_launch',
  steps: [
    { agent: 'sourcing-01', task: 'find_suppliers' },
    { agent: 'finance-01', task: 'analyze_unit_economics' },
    { agent: 'pricing-01', task: 'set_launch_price' },
    { agent: 'logistics-01', task: 'setup_fulfillment' }
  ]
});

Machine Learning Integration

Agents that learn and improve over time:

const mlAgent = new StatesetAgent({
  name: 'SmartTrader',
  ml: {
    model: 'reinforcement_learning',
    features: ['price', 'volume', 'sentiment', 'on_chain_metrics'],
    training: 'continuous',
    framework: 'tensorflow.js'
  }
});

// Agent learns from outcomes
mlAgent.addLearningLoop({
  async onTransactionComplete(tx, outcome) {
    // Record outcome for training
    await this.recordOutcome({
      action: tx.action,
      context: tx.context,
      result: outcome,
      reward: outcome.profit - outcome.costs
    });
    
    // Retrain if performance drops
    if (this.performance.last100Trades < 0.6) {
      await this.retrain({
        epochs: 100,
        batchSize: 32,
        learningRate: 0.001
      });
    }
  }
});

Risk Management Framework

Built-in risk controls for agent operations:

const riskFramework = {
  // Position limits
  positions: {
    maxConcentration: 0.20, // Max 20% in one asset
    maxLeverage: 1.0, // No leverage allowed
    maxDrawdown: 0.10 // Stop at 10% loss
  },
  
  // Operational limits
  operations: {
    maxTransactionsPerHour: 100,
    maxValuePerHour: '50000.00',
    requiredConfirmations: 1
  },
  
  // Circuit breakers
  circuitBreakers: [
    {
      condition: 'loss > 1000 USDC in 1 hour',
      action: 'pause_all_trading'
    },
    {
      condition: 'error_rate > 0.10',
      action: 'alert_human_operator'
    },
    {
      condition: 'unusual_activity_detected',
      action: 'require_2fa'
    }
  ]
};

Security Best Practices

1. Secure Key Management

// Use hardware security modules for production
const secureWallet = new AgentWallet({
  keyStorage: 'hsm',
  provider: 'aws-cloudhsm',
  backupStrategy: 'shamir-secret-sharing',
  threshold: 3,
  shares: 5
});

// Rotate keys periodically
const keyRotation = {
  frequency: 'monthly',
  strategy: 'gradual', // Overlap old and new keys
  notifyWebhook: 'https://api.company.com/key-rotation'
};

2. Transaction Verification

// Multi-signature requirements for large transactions
const multiSigPolicy = {
  thresholds: [
    { amount: '1000.00', signatures: 1 },
    { amount: '10000.00', signatures: 2 },
    { amount: '100000.00', signatures: 3 }
  ],
  
  signers: [
    { role: 'agent', weight: 1 },
    { role: 'risk_system', weight: 1 },
    { role: 'human_operator', weight: 2 }
  ]
};

3. Audit Logging

// Comprehensive audit trail
const auditLogger = new AuditLogger({
  storage: 'immutable',
  encryption: 'aes-256-gcm',
  
  logEvents: [
    'transaction_initiated',
    'transaction_signed',
    'transaction_broadcast',
    'transaction_confirmed',
    'balance_changed',
    'permission_changed',
    'error_occurred'
  ],
  
  retention: '7 years',
  export: {
    format: 'json',
    schedule: 'daily',
    destination: 's3://audit-logs/'
  }
});

Monitoring and Analytics

Real-Time Dashboards

// Monitor agent performance
const monitoring = new AgentMonitor({
  metrics: [
    'transaction_volume',
    'success_rate',
    'avg_response_time',
    'profit_loss',
    'gas_consumed'
  ],
  
  alerts: [
    {
      metric: 'error_rate',
      threshold: 0.05,
      action: 'email'
    },
    {
      metric: 'daily_loss',
      threshold: '1000.00',
      action: 'pause_agent'
    }
  ],
  
  dashboard: 'https://monitoring.company.com/agents'
});

Performance Analytics

// Track agent effectiveness
const analytics = await agent.getAnalytics({
  period: 'last_30_days',
  metrics: [
    'total_transactions',
    'volume_traded',
    'fees_paid',
    'net_profit',
    'success_rate',
    'avg_execution_time'
  ]
});

logger.info(`
Agent Performance Report:
- ROI: ${analytics.roi}%
- Win Rate: ${analytics.winRate}%
- Sharpe Ratio: ${analytics.sharpeRatio}
- Total Profit: ${analytics.totalProfit} USDC
`);

Deployment Guide

1. Development Environment

# Clone the agent template
git clone https://github.com/StateSet/agent-template
cd agent-template

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run tests
npm test

# Start local agent
npm run dev

2. Production Deployment

# kubernetes/agent-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: trading-agent
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: agent
        image: Stateset/agent:latest
        env:
        - name: AGENT_WALLET
          valueFrom:
            secretKeyRef:
              name: agent-secrets
              key: wallet-seed
        - name: SPENDING_LIMIT
          value: "10000.00"
        - name: STATESET_ENDPOINT
          value: "https://api.stateset.com"
        resources:
          limits:
            memory: "1Gi"
            cpu: "500m"

3. Monitoring Setup

// Initialize monitoring
const monitor = new StatesetMonitor({
  agentId: 'trading-bot-001',
  webhooks: {
    alerts: 'https://api.company.com/alerts',
    reports: 'https://api.company.com/reports'
  },
  
  customMetrics: [
    {
      name: 'arbitrage_opportunities',
      query: 'count(trades.type = "arbitrage")'
    },
    {
      name: 'avg_profit_per_trade',
      query: 'avg(trades.profit)'
    }
  ]
});

Cost Optimization

Fee Management

// Optimize transaction costs
const feeOptimizer = {
  // Batch transactions when possible
  batching: {
    enabled: true,
    maxBatchSize: 100,
    maxWaitTime: '5 minutes'
  },
  
  // Use efficient routes
  routing: {
    preferDirectTransfers: true,
    maxHops: 2,
    avoidHighFeeContracts: true
  },
  
  // Time transactions optimally
  timing: {
    avoidPeakHours: true,
    preferredHours: [2, 3, 4, 5], // UTC
    urgentThreshold: '1000.00' // Skip optimization for urgent
  }
};

Compliance and Regulations

Built-in Compliance

const complianceFramework = {
  // KYC/AML for agent operations
  kyc: {
    requiredFor: ['withdrawal > 10000', 'new_counterparty'],
    provider: 'chainalysis',
    refreshFrequency: 'annual'
  },
  
  // Transaction monitoring
  aml: {
    screenCounterparties: true,
    flagSuspiciousPatterns: true,
    reportingThreshold: '10000.00',
    sarsFilingWebhook: 'https://compliance.company.com/sars'
  },
  
  // Regulatory reporting
  reporting: {
    taxReporting: {
      form: '1099-K',
      frequency: 'annual',
      includeFees: true
    },
    
    regulatoryReporting: {
      jurisdictions: ['US', 'EU'],
      realTime: true
    }
  }
};

Future Roadmap

Coming Soon

1. Natural Language Control: Tell agents what to do in plain English
2. Cross-Chain Agents: Operate seamlessly across multiple blockchains
3. Agent Marketplace: Buy, sell, and license proven agent strategies
4. Collaborative Agents: Agents that work together on complex tasks
5. Quantum-Resistant Security: Future-proof cryptography

Conclusion

Smart agents on StateSet Commerce Network represent the future of autonomous commerce. With native USDC, instant settlements, and comprehensive APIs, developers can build agents that:

• Execute complex trading strategies
• Optimize business operations
• Provide 24/7 customer service
• Manage treasury and yield
• Scale without human intervention

The combination of AI and blockchain creates unprecedented opportunities for automation, efficiency, and innovation in commerce.

Resources

• Example Agents
• Discord Community

Start building your autonomous commerce agent today and join the revolution in how business gets done.

Next steps

Autonomous agent architecture

The wallet and governance model in full.

CCTP module

Moving USDC between chains.

x402 walkthrough

Machine-to-machine payment for API calls.

Sequencer

Where agent transactions are ordered and settled.