CloddsBot/docs/VIRTUALS.md

Virtuals Protocol Integration

AI Agent marketplace trading on Base chain.

Overview

Virtuals Protocol is a platform for creating, trading, and interacting with AI agents. Each agent has its own token that trades on a bonding curve until graduation (42K VIRTUAL accumulated), then moves to Uniswap V2.

┌─────────────────────────────────────────────────────────────┐
│                   Virtuals Protocol                          │
├─────────────────┬─────────────────┬─────────────────────────┤
│   Discovery     │    Trading      │      Staking            │
├─────────────────┼─────────────────┼─────────────────────────┤
│ • Search agents │ • Bonding curve │ • veVIRTUAL             │
│ • Trending      │ • Uniswap V2    │ • Voting power          │
│ • New launches  │ • Auto-routing  │ • Delegation            │
└─────────────────┴─────────────────┴─────────────────────────┘

Quick Start

1. Configure Base RPC (optional)

# Default: https://mainnet.base.org
export BASE_RPC_URL="https://your-base-rpc.com"

2. For trading, set wallet key

export EVM_PRIVATE_KEY="0x..."

3. Use commands

/agents luna              # Search for AI agents
/trending-agents          # See what's hot
/agent 0x1234...          # Get agent details
/agent-quote buy 0x... 100  # Get trade quote

Commands

Discovery

Command	Description
/agents <query>	Search AI agents by name/symbol
/agent <token-address>	Get detailed agent info
/trending-agents [limit]	Top agents by 24h volume
/new-agents [limit]	Recently launched agents

Trading

Command	Description
/agent-quote <buy|sell> <token> <amount>	Get quote with price impact
/virtual-balance [address]	Check VIRTUAL & veVIRTUAL balances
/markets virtuals <query>	Search via unified markets command

Agent Lifecycle

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  PROTOTYPE   │ ──► │   SENTIENT   │ ──► │  GRADUATED   │
│              │     │              │     │              │
│ Just created │     │ Has traction │     │ On Uniswap   │
│ 100 VIRTUAL  │     │ <42K VIRTUAL │     │ 42K+ VIRTUAL │
│ to launch    │     │ accumulated  │     │ in curve     │
└──────────────┘     └──────────────┘     └──────────────┘
       │                    │                    │
       └────────────────────┴────────────────────┘
                     Bonding Curve          Uniswap V2

Contract Addresses (Base Chain)

Contract	Address
VIRTUAL Token	0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b
Bonding Proxy	0xF66DeA7b3e897cD44A5a231c61B6B4423d613259
Sell Executor	0xF8DD39c71A278FE9F4377D009D7627EF140f809e
Creator Vault	0xdAd686299FB562f89e55DA05F1D96FaBEb2A2E32
veVIRTUAL	0x14559863b6E695A8aa4B7e68541d240ac1BBeB2f
Uniswap V2 Router	0x4752ba5DBc23f44D87826276BF6Fd6b1C372aD24
Uniswap V2 Factory	0x8909Dc15e40173Ff4699343b6eB8132c65e18eC6

Programmatic Usage

Get Agent Info

import { getAgentTokenInfo, getAgentStatus } from './evm/virtuals';

const info = await getAgentTokenInfo('0x1234...');
console.log(info.name, info.symbol);
console.log('Graduated:', info.isGraduated);
console.log('Progress:', info.bondingCurve?.progressToGraduation);

const status = await getAgentStatus('0x1234...');
// 'prototype' | 'sentient' | 'graduated'

Get Quote

import { getVirtualsQuote } from './evm/virtuals';

const quote = await getVirtualsQuote({
  agentToken: '0x1234...',
  amount: '100',        // VIRTUAL for buy, tokens for sell
  side: 'buy',
  slippageBps: 100,     // 1%
});

console.log('Route:', quote.route);  // 'bonding' or 'uniswap'
console.log('Output:', quote.outputAmount);
console.log('Price Impact:', quote.priceImpact, '%');

Execute Trade

import { buyAgentToken, sellAgentToken } from './evm/virtuals';

// Buy agent tokens with VIRTUAL
const buyResult = await buyAgentToken({
  agentToken: '0x1234...',
  amount: '100',          // 100 VIRTUAL
  slippageBps: 100,
});

if (buyResult.success) {
  console.log('TX:', buyResult.txHash);
  console.log('Received:', buyResult.outputAmount);
  console.log('Route:', buyResult.route);
}

// Sell agent tokens for VIRTUAL
const sellResult = await sellAgentToken({
  agentToken: '0x1234...',
  amount: '1000000',      // 1M agent tokens
  slippageBps: 100,
});

Staking

import { stakeVirtual, getVeVirtualBalance, delegateVotingPower } from './evm/virtuals';

// Stake VIRTUAL for veVIRTUAL
const stakeResult = await stakeVirtual({
  amount: '1000',
  delegatee: '0x...',  // Optional: delegate voting power
});

// Check balance
const veBalance = await getVeVirtualBalance();

// Delegate to another address
await delegateVotingPower('0x...');

Agent Discovery

import { searchAgents, getTrendingAgents, getNewAgents } from './evm/virtuals';

// Search
const results = await searchAgents('luna', 10);

// Trending by volume
const trending = await getTrendingAgents(10);

// New launches
const newAgents = await getNewAgents(10);

Check Creation Requirements

import { canCreateAgent } from './evm/virtuals';

const check = await canCreateAgent();
console.log('Can create:', check.canCreate);
console.log('Balance:', check.balance);
console.log('Required:', check.required);  // 100 VIRTUAL
console.log('Shortfall:', check.shortfall);

Feed Integration

Virtuals is integrated with the feed manager for unified market access:

// Via FeedManager
const markets = await feeds.searchMarkets('luna', 'virtuals');

// Subscribe to price updates
const unsub = feeds.subscribePrice('virtuals', agentId, (update) => {
  console.log('Price:', update.price);
});

Key Constants

Constant	Value	Description
GRADUATION_THRESHOLD	42,000 VIRTUAL	Triggers move to Uniswap
AGENT_CREATION_COST	100 VIRTUAL	Minimum to create agent
AGENT_TOKEN_SUPPLY	1 billion	Fixed supply per agent
BASE_CHAIN_ID	8453	Base mainnet

Trading Notes

1. Auto-routing: Trades automatically route to bonding curve (pre-graduation) or Uniswap (post-graduation)

2. Price Impact: Bonding curve trades can have significant impact - always check quotes first

3. Graduation: Once an agent accumulates 42K VIRTUAL, it graduates to Uniswap with locked liquidity (10 years)

4. Fees: 1% tax on trades:

   • Pre-graduation: 100% to protocol treasury
   • Post-graduation: 30% creator, 20% affiliates, 50% agent SubDAO

5. Slippage: Default 1% (100 bps) - increase for volatile agents

Resources

• Virtuals Protocol Whitepaper
• App
• Fun (Agent Creation)
• BaseScan VIRTUAL Token