Virtuals Agent Integration

Overview

Virtuals agents can integrate with Opacus to gain access to:

• MPC Parameter Management with 0G Storage — Update agent parameters (slippage, risk level, position size) trustlessly at runtime, with automatic backup to 0G decentralized storage for audit trails
• Decentralized Storage on 0G — Store agent state, trading logs, and model parameters on 0G network with Merkle proof guarantees and DA settlement
• Cross-Chain Payments — Pay for services on Base, 0G, and other networks with automatic routing
• Escrow Services — Trustless payments between agents with 0G-backed settlement
• H3 Geospatial Discovery — Find nearby agents by capability
• ZK Proofs — Generate proofs for escrow states and reputation

Installation

npm install opacus-agent-sdk

Basic Integration

Create an Opacus worker for your Virtuals agent:

import { createOpacusWorker } from 'opacus-agent-sdk';

const { worker, agentDID } = await createOpacusWorker({
  kernelUrl: 'https://kernel.opacus.xyz',
  apiKey: process.env.OPACUS_API_KEY,
  userAddress: '0x...', // Your wallet address
  mpcServerUrl: 'https://mpc.opacus.xyz', // Optional: for MPC
  mpcApiKey: 'sk-mpc-...', // Optional: MPC token
  enableMpc: true, // Enable MPC parameter management
});

// Add to your Virtuals GameAgent
const agent = new GameAgent({
  workers: [worker],
  // ... other config
});

MPC Parameter Management with 0G Storage

Update agent parameters trustlessly without exposing private keys, with automatic 0G storage backup:

// Update slippage parameter with 0G storage backup
await agent.execute('manage_mpc_parameters', {
  agentName: 'my-trading-bot',
  paramKey: 'swapSlippage',
  paramValue: '50', // 0.5%
  enableStorage: true, // Enable 0G storage backup
  storageNetwork: 'mainnet' // 'mainnet' or 'testnet'
});

// Update risk level and store in 0G
await agent.execute('manage_mpc_parameters', {
  agentName: 'my-trading-bot',
  paramKey: 'riskLevel',
  paramValue: 'medium',
  enableStorage: true
});

// Update position size with full storage versioning
await agent.execute('manage_mpc_parameters', {
  agentName: 'my-trading-bot',
  paramKey: 'maxPositionSize',
  paramValue: '1000',
  enableStorage: true,
  storageMetadata: {
    version: '1.2.0',
    updatedBy: 'governance-proposal-45',
    timestamp: Date.now()
  }
});

// Retrieve historical parameters from 0G storage
const history = await agent.execute('get_parameter_history', {
  agentName: 'my-trading-bot',
  paramKey: 'swapSlippage',
  fromStorage: true // Fetch from 0G network
});

0G Storage Configuration for MPC

Set up 0G storage integration in your environment:

# 0G Storage Network (required for MPC parameter storage)
OG_RPC_URL=https://evmrpc.0g.ai
OG_STORAGE_INDEXER=https://indexer-storage-turbo.0g.ai
OG_PRIVATE_KEY=0x... # Your 0G executor private key

# For testnet:
OG_STORAGE_TESTNET_INDEXER=https://indexer-storage-testnet-standard.0g.ai
OG_STORAGE_RPC_URL=https://evmrpc-testnet.0g.ai

# MPC with 0G Storage
MPC_ENABLE_0G_STORAGE=true
MPC_SERVER_URL=https://mpc.opacus.xyz
MPC_API_KEY=sk-mpc-...

Available GameFunctions

All Opacus features are available as native GameFunctions:

Decentralized Storage (0G Network)

Store agent data on 0G network with Merkle proof guarantees and DA settlement:

// Store agent state on 0G
await agent.execute('store_on_0g', {
  data: JSON.stringify({
    agentState: {
      positions: agent.getOpenPositions(),
      balances: agent.getBalances(),
      lastUpdate: Date.now()
    },
    agentId: agent.id
  }),
  metadata: {
    type: 'agent-state-backup',
    agentName: 'my-trading-bot',
    version: '1.0.0',
    encrypted: true
  },
  network: 'mainnet' // or 'testnet'
});

// Store trading logs for audit trail
await agent.execute('store_on_0g', {
  data: JSON.stringify(tradingLogs),
  metadata: {
    type: 'trading-audit-log',
    date: new Date().toISOString(),
    hash: computeChecksum(tradingLogs)
  }
});

// Retrieve stored data from 0G
const storedState = await agent.execute('retrieve_from_0g', {
  rootHash: '0x...', // Hash returned from store operation
  network: 'mainnet'
});

Cross-Chain Payments

Pay for services across multiple networks:

// Bridge USDC to 0G for storage/compute
await agent.execute('bridge_to_0g', {
  amountUsdc: '10'
});

// Lock escrow for agent-to-agent payment
await agent.execute('lock_escrow', {
  amount: '0.5',
  counterparty: '0xAgentAddress',
  taskId: 'trading-signal-delivery'
});

Configuration

Environment variables needed for full Opacus + 0G Storage integration:

# ── REQUIRED ──────────────────────────────────────────────────
OPACUS_API_KEY=sk-opacus-...
OPACUS_USER_ADDRESS=0xYourWalletAddress

# ── MPC PARAMETERS ─────────────────────────────────────────────
MPC_SERVER_URL=https://mpc.opacus.xyz
MPC_API_KEY=sk-mpc-...
MPC_ENABLE_0G_STORAGE=true

# ── 0G STORAGE (REQUIRED FOR DECENTRALIZED STORAGE) ──────────────
OG_RPC_URL=https://evmrpc.0g.ai
OG_STORAGE_INDEXER=https://indexer-storage-turbo.0g.ai
OG_PRIVATE_KEY=0x...  # Your 0G executor private key

# ── 0G TESTNET (OPTIONAL) ─────────────────────────────────────
OG_STORAGE_TESTNET_INDEXER=https://indexer-storage-testnet-standard.0g.ai
OG_STORAGE_RPC_URL=https://evmrpc-testnet.0g.ai

# ── 0G STORAGE ENCRYPTION (OPTIONAL) ──────────────────────────
OG_STORAGE_ENCRYPTION_KEY=0x...
OG_STORAGE_COMPRESSION=true

Example: Trading Bot with 0G Storage

Complete trading bot with MPC parameter management and decentralized storage:

import { createOpacusWorker } from 'opacus-agent-sdk';

class VirtualsTradingBot {
  constructor() {
    this.initializeOpacus();
  }

  async initializeOpacus() {
    const { worker, agentDID } = await createOpacusWorker({
      kernelUrl: 'https://kernel.opacus.xyz',
      apiKey: process.env.OPACUS_API_KEY,
      userAddress: process.env.OPACUS_USER_ADDRESS,
      mpcServerUrl: process.env.MPC_SERVER_URL,
      mpcApiKey: process.env.MPC_API_KEY,
      enableMpc: true,
      // 0G Storage configuration
      ogRpcUrl: process.env.OG_RPC_URL,
      ogStorageIndexer: process.env.OG_STORAGE_INDEXER,
      ogPrivateKey: process.env.OG_PRIVATE_KEY,
      enableStorage: true
    });

    this.agent = new GameAgent({
      workers: [worker],
      name: 'Opacus Trading Bot',
    });

    console.log('Agent DID:', agentDID);
  }

  async updateSlippage(newSlippage) {
    // Update MPC parameter AND store in 0G
    return await this.agent.execute('manage_mpc_parameters', {
      agentName: 'trading-bot',
      paramKey: 'swapSlippage',
      paramValue: newSlippage.toString(),
      enableStorage: true  // Backup to 0G
    });
  }

  async executeTrade(tokenIn, tokenOut, amount) {
    const tradeResult = await this.agent.execute('run_skill', {
      skill: 'swap-cross-chain',
      params: { tokenIn, tokenOut, amount },
    });

    // Store trade execution proof in 0G for audit trail
    await this.storeTradeProof(tradeResult);
    return tradeResult;
  }

  async storeTradeHistory(tradeData) {
    return await this.agent.execute('store_on_0g', {
      data: JSON.stringify({
        trades: tradeData,
        timestamp: Date.now(),
        botId: this.agent.id
      }),
      metadata: {
        type: 'trading-audit-log',
        version: '1.0.0',
        encrypted: true
      },
      network: 'mainnet'
    });
  }

  async storeTradeProof(tradeResult) {
    return await this.agent.execute('store_on_0g', {
      data: JSON.stringify({
        txHash: tradeResult.txHash,
        timestamp: Date.now(),
        amount: tradeResult.amount,
        slippage: tradeResult.slippage
      }),
      metadata: {
        type: 'trade-execution-proof',
        indexed: true
      }
    });
  }

  async getAgentCapabilities() {
    const identity = await this.agent.execute('get_opacus_identity', {});
    return {
      did: identity.did,
      capabilities: identity.capabilities,
      storageEnabled: identity.ogStorageEnabled,
      mpcEnabled: identity.mpcEnabled
    };
  }
}

Troubleshooting

• 0G Storage not configured: Set OG_RPC_URL and OG_STORAGE_INDEXER environment variables. Check with GET /api/og-storage/usage
• MPC parameters not updating: Verify MPC server URL and API key are correct. Check MPC_ENABLE_0G_STORAGE=true for storage integration
• Insufficient funds: Ensure your agent wallet has USDC on Base network and 0G tokens for storage operations
• Bridge stuck: Check bridge status at /api/runtime/bridge-status
• Storage upload failed: Verify OG_PRIVATE_KEY is set and has sufficient gas on 0G network. Use network: 'testnet' for testing
• Skill not found: Use get_opacus_identity to list available capabilities and storage support

Next Steps

• Get started with Opacus
• Explore full API reference
• View code examples
• SDK on GitHub