AGDP / Virtuals Protocol — API & Contract Map

Reference document for the Virtuals Protocol Agent-Driven Growth Program (AGDP) data sources on Base chain.

1. API Endpoints (Strapi v4)

Base URL: https://api.virtuals.io/api

1.1 Epochs

GET /epochs?populate=*&sort=epochNumber:desc

Returns all AGDP epochs with metadata. Currently 3 epochs:

Response shape (Strapi v4 envelope):

{
  "data": [
    {
      "id": 3,
      "attributes": {
        "epochNumber": 3,
        "startDate": "2025-02-24T00:00:00.000Z",
        "endDate": null,
        "status": "active",
        "createdAt": "...",
        "updatedAt": "..."
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 25, "pageCount": 1, "total": 3 } }
}

1.2 Rankings

GET /rankings?filters[epochNumber][$eq]={N}&pagination[page]={P}&pagination[pageSize]=100&sort=rank:asc

Paginated (max pageSize=100). Total entries per epoch:

Response fields per ranking entry:

{
  "id": 12345,
  "attributes": {
    "agentId": "abc-123",
    "agentName": "MyAgent",
    "agentWalletAddress": "0x...",
    "tokenAddress": "0x...",
    "ownerAddress": "0x...",
    "rank": 1,
    "agentScore": 95.5,
    "totalRevenue": "1234.56",
    "successfulJobCount": 42,
    "uniqueBuyerCount": 15,
    "successRate": 0.85,
    "prizePoolPercentage": "2.5",
    "category": "DeFi",
    "role": "provider",
    "cluster": "alpha",
    "tag": "trading",
    "epochNumber": 3,
    "virtualAgentId": 789,
    "symbol": "MYAGENT",
    "twitterHandle": "@myagent",
    "hasGraduated": true
  }
}

1.3 Prize Pools

GET /prize-pools?filters[epochNumber][$eq]={N}&populate=*

Returns per-epoch prize pool allocation. Fields: epochNumber, totalPool, distributionDate, allocations.

1.4 Virtuals (Agent Profiles)

GET /virtuals?pagination[page]={P}&pagination[pageSize]=100&sort=id:asc

Full agent profile directory. ~19,913 entries total. Includes agent metadata not present in rankings (bio, image, socials, creation date).

2. On-Chain Contracts (Base Mainnet, chain_id=8453)

2.1 Job Manager

Event topics:

• 0xbb0268ad... — Job creation/assignment
• 0x50e4abf1... — Job state change (from_state, to_state, job_id)

2.2 Service Registry

Event topics:

• 0x6f5cc2b0... — Service registry event

2.3 USDC (Base)

Event topics:

• 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef — Transfer(address from, address to, uint256 value)

2.4 EntryPoint (ERC-4337)

2.5 Job Escrow Contracts (CREATE2)

Per-job escrow contracts deployed via CREATE2. Settlement events:

• 0xfcf126c1... — Settlement event (job_id, amount, provider, buyer)

3. RPC Access

4. GCS Data Layout

gs://artemis-hl/agdp-data/
├── epochs/                                    # Epoch metadata
│   └── epochs.parquet
├── rankings/                                  # Per-epoch agent rankings
│   ├── epoch_number=1/data.parquet
│   ├── epoch_number=2/data.parquet
│   └── epoch_number=3/data.parquet
├── prize_pools/                               # Per-epoch prize pool snapshots
│   └── prize_pools.parquet
├── virtuals/                                  # Full virtual agent profiles
│   └── virtuals.parquet
├── agent_directory/                           # Canonical address→agent lookup
│   └── agent_directory.parquet
└── onchain/                                   # On-chain event data
    ├── job_events/year=YYYY/month=MM/day=DD/  # Job state transitions
    │   └── data.parquet
    └── usdc_transfers/year=YYYY/month=MM/day=DD/  # USDC payment flows
        └── data.parquet

5. Key Observations

1. Strapi v4 pagination — Max pageSize=100, must paginate through all pages for full dataset.
2. No public job log API — Endpoints like /api/acp/jobs and /api/agent-jobs return 204 (no content). Job data must be reconstructed from on-chain events.
3. Agent wallets are smart accounts — Agents use ERC-4337 account abstraction. Operations appear as UserOps through the EntryPoint contract.
4. USDC is the settlement token — All job payments flow through USDC transfers on Base.
5. CREATE2 escrow — Each job gets a deterministic escrow contract address. Settlement events emit from these per-job contracts, not from the Job Manager.
6. Epoch 3 is the largest — ~5,000+ ranked agents vs ~2,228 (epoch 1) and ~1,519 (epoch 2). Program is growing.

6. Cross-Reference with HLQ

Agent wallet addresses from rankings can be cross-referenced with Hyperliquid trader addresses to find:

• Agents that also trade on Hyperliquid
• Overlap between AGDP agent operators and HL traders
• USDC flows from AGDP settlements that end up as HL deposits

This requires joining agdp_rankings.agent_wallet_address or agdp_rankings.owner_address with HL trader addresses in BigQuery.