> ## Documentation Index
> Fetch the complete documentation index at: https://artemis.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtuals

> Virtuals Schema Description and Methodology

This schema contains comprehensive datasets for tracking Virtuals Protocol fundamental data across multiple metrics categories, including AI agent activity, trading volume, fee distribution, token economics, and market data for the decentralized AI agent marketplace.

## Available Tables

Virtuals data is available in two main tables:

* **ez\_metrics**: Main aggregated metrics for the Virtuals Protocol
* **ez\_metrics\_by\_chain**: Chain-specific metrics (currently focused on Base network)

## Table Schema

### AI Agent and Activity Metrics

| Table Name  | Column Name   | Description                                             |
| ----------- | ------------- | ------------------------------------------------------- |
| ez\_metrics | daily\_agents | The number of AI agents active on a given day           |
| ez\_metrics | spot\_dau     | The number of daily active traders on Virtuals Protocol |
| ez\_metrics | dau           | Same as spot\_dau (legacy naming)                       |

### Trading and Volume Metrics

| Table Name  | Column Name    | Description                                   |
| ----------- | -------------- | --------------------------------------------- |
| ez\_metrics | spot\_volume   | The total trading volume on Virtuals Protocol |
| ez\_metrics | volume\_usd    | Same as spot\_volume (legacy naming)          |
| ez\_metrics | volume\_native | Trading volume in native token units          |

### Fee Structure and Revenue Metrics

| Table Name  | Column Name               | Description                                                                                                                                                                                                |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ez\_metrics | spot\_fees                | The total amount of fees (in USD) paid by users on Virtuals Protocol                                                                                                                                       |
| ez\_metrics | fees                      | The sum of all taxes, 1% fee on all trades, and agent fees (in USD) paid on Virtuals Protocol                                                                                                              |
| ez\_metrics | service\_fee\_allocation  | All fees paid to AI agents on Virtuals Protocol                                                                                                                                                            |
| ez\_metrics | treasury\_fee\_allocation | Revenue allocated to the protocol's treasury. All taxes paid on trades first go to the treasury, then post-bond are distributed across Agent Creator (30%), Agent Affiliates (20%), and Agent subDAO (50%) |
| ez\_metrics | fee\_fun\_usd             | Agent fees collected in USD (legacy naming)                                                                                                                                                                |
| ez\_metrics | fee\_fun\_native          | Agent fees collected in native tokens (legacy naming)                                                                                                                                                      |
| ez\_metrics | tax\_usd                  | Tax fees collected from trades (legacy naming)                                                                                                                                                             |
| ez\_metrics | fees                      | Total fees collected (legacy naming)                                                                                                                                                                       |

### Token Supply Metrics

| Table Name  | Column Name                 | Description                                                 |
| ----------- | --------------------------- | ----------------------------------------------------------- |
| ez\_metrics | circulating\_supply\_native | The circulating supply of VIRTUALS tokens in native units   |
| ez\_metrics | net\_supply\_change\_native | The net change in the circulating supply of VIRTUALS tokens |
| ez\_metrics | premine\_unlocks\_native    | The amount of native VIRTUALS tokens unlocked from premine  |

### Market and Token Metrics

| Table Name  | Column Name                  | Description                                                     |
| ----------- | ---------------------------- | --------------------------------------------------------------- |
| ez\_metrics | price                        | The price of VIRTUALS token in USD                              |
| ez\_metrics | market\_cap                  | The market cap of VIRTUALS token in USD                         |
| ez\_metrics | fdmc                         | The fully diluted market cap of VIRTUALS token in USD           |
| ez\_metrics | token\_volume                | The trading volume of VIRTUALS token in USD                     |
| ez\_metrics | token\_turnover\_circulating | The turnover of VIRTUALS token based on circulating supply      |
| ez\_metrics | token\_turnover\_fdv         | The turnover of VIRTUALS token based on fully diluted valuation |

### Chain-Specific Metrics

| Table Name             | Column Name     | Description                                         |
| ---------------------- | --------------- | --------------------------------------------------- |
| ez\_metrics\_by\_chain | chain           | The blockchain (currently 'base')                   |
| ez\_metrics\_by\_chain | trading\_volume | Trading volume on the specific chain                |
| ez\_metrics\_by\_chain | volume\_native  | Trading volume in native token units                |
| ez\_metrics\_by\_chain | ai\_volume      | AI-related trading volume (same as trading\_volume) |

## Sample Queries

### Basic Protocol Activity Query

```sql theme={null}
-- Pull fundamental activity data for Virtuals Protocol
SELECT
    date,
    daily_agents,
    spot_dau,
    spot_volume,
    spot_fees,
    fees,
    price
FROM
    art_share.virtuals.ez_metrics
WHERE
    date >= DATEADD(month, -3, CURRENT_DATE())
ORDER BY
    date ASC
```

### AI Agent Activity Analysis

```sql theme={null}
-- Analyze AI agent activity and user engagement
SELECT
    date,
    daily_agents,
    spot_dau,
    spot_volume,
    spot_volume / NULLIF(spot_dau, 0) as avg_volume_per_user,
    spot_volume / NULLIF(daily_agents, 0) as avg_volume_per_agent,
    spot_dau / NULLIF(daily_agents, 0) as avg_users_per_agent
FROM
    art_share.virtuals.ez_metrics
WHERE
    date >= DATEADD(month, -2, CURRENT_DATE())
    AND daily_agents > 0
ORDER BY
    date ASC
```

### Fee Distribution Analysis

```sql theme={null}
-- Analyze Virtuals Protocol fee structure and distribution
SELECT
    date,
    ecosystem_
```