AICWProtocol

Agent backend

Design a backend that manages AICW agent operations

The agent backend handles autonomous operations: heartbeats, transfers, and business logic. It communicates with the MPC Bridge for signing and the Solana RPC for broadcasting.

Recommended architecture

Architecture
┌─────────────────────────────────────────────────┐
│ Agent Backend                                   │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌─────────────┐   ┌─────────────────────────┐ │
│  │ Scheduler   │   │ Business Logic           │ │
│  │ (cron)      │   │ - Transfer rules         │ │
│  │ - heartbeat │   │ - Amount caps            │ │
│  │ - health    │   │ - Recipient allowlists   │ │
│  └─────────────┘   └─────────────────────────┘ │
│          │                     │                │
│          ▼                     ▼                │
│  ┌─────────────────────────────────────────┐   │
│  │ Transaction Builder                      │   │
│  │ - Build instructions from IDL            │   │
│  │ - Serialize for signing                  │   │
│  └─────────────────────────────────────────┘   │
│                     │                           │
│                     ▼                           │
│  ┌───────────────┐     ┌──────────────────┐   │
│  │ MPC Bridge    │     │ Solana RPC       │   │
│  │ (sign)        │     │ (broadcast)      │   │
│  └───────────────┘     └──────────────────┘   │
└─────────────────────────────────────────────────┘

Heartbeat scheduler

Example using APScheduler:

Python
from apscheduler.schedulers.background import BackgroundScheduler
from aicw_ops import heartbeat

scheduler = BackgroundScheduler()

@scheduler.scheduled_job("interval", days=10)
def send_heartbeat():
    try:
        result = heartbeat(
            mpc_wallet_id=os.environ["MPC_WALLET_ID"],
            ai_agent_pubkey=os.environ["AI_AGENT_PUBKEY"],
            rpc_url=os.environ["SOLANA_RPC_URL"],
            bridge_url=os.environ["MPC_BRIDGE_URL"],
        )
        logger.info(f"Heartbeat sent: {result}")
    except Exception as e:
        logger.error(f"Heartbeat failed: {e}")
        alert_admin(e)

scheduler.start()

Transfer with business rules

Python
MAX_SINGLE_TRANSFER = 1.0  # SOL
ALLOWED_RECIPIENTS = ["merchant1...", "merchant2..."]

def process_transfer(recipient, amount, reasoning):
    # Enforce business rules
    if amount > MAX_SINGLE_TRANSFER:
        raise ValueError(f"Amount {amount} exceeds cap {MAX_SINGLE_TRANSFER}")
    if recipient not in ALLOWED_RECIPIENTS:
        raise ValueError(f"Recipient {recipient} not in allowlist")

    # Build and sign transaction
    result = ai_transfer(
        mpc_wallet_id=os.environ["MPC_WALLET_ID"],
        ai_agent_pubkey=os.environ["AI_AGENT_PUBKEY"],
        recipient=recipient,
        amount_sol=amount,
        reasoning=reasoning,
        rpc_url=os.environ["SOLANA_RPC_URL"],
        bridge_url=os.environ["MPC_BRIDGE_URL"],
    )
    return result

Environment variables

Never commit this file to version control.

.env
MPC_WALLET_ID=your-mpc-wallet-uuid
AI_AGENT_PUBKEY=your-base58-solana-pubkey
MPC_BRIDGE_URL=https://your-bridge.example.com
SOLANA_RPC_URL=https://api.devnet.solana.com
AICW_PROGRAM_ID=9RUEw4jcMi8xcGf3tJRCAdzUzLuhEurts8Z2QQLsRbaV

Monitoring and alerting

  • Heartbeat health — Alert if heartbeat fails or is overdue. This is the most critical monitor.
  • Balance threshold — Alert when agent pubkey SOL drops below fee buffer (e.g., 0.05 SOL).
  • Bridge health — Periodically check /health endpoint. Alert on 5xx errors.
  • Transaction failures — Log all failed transactions with error codes for debugging.