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

# RetinaOS Data Model: Tokens, Wallets, and Events Explained

> The three core objects RetinaOS tracks on Robinhood Chain — Tokens, Wallets, and Events — and how each relates to dashboards and API responses.

RetinaOS indexes Robinhood Chain in real time and organizes everything it captures into three core objects: Tokens, Wallets, and Events. Understanding these objects helps you interpret dashboards, API responses, and Cortex scores accurately.

## The Three Core Objects

**Token**

A Token represents any ERC-20 or compatible token deployed on Robinhood Chain. Each Token object includes:

* `address` — the on-chain contract address
* `name`, `symbol`
* `market_cap_usd` — current market cap in USD
* `volume_24h_usd` — 24-hour trading volume
* `liquidity_usd` — current liquidity pool depth
* `holder_count` — number of unique holders
* `age_hours` — time since token creation
* `risk_score` — Cortex-generated composite risk score (0–100, lower is safer)
* `ai_summary` — most recent AI-generated market summary
* `launchpad` — launchpad used for deployment (if applicable)

***

**Wallet**

A Wallet represents any on-chain address that has interacted with Robinhood Chain. Each Wallet object includes:

* `address` — the on-chain address
* `portfolio` — list of current token holdings with quantities
* `pnl_estimate` — estimated historical PnL from on-chain data (best-effort)
* `classification` — Cortex behavioral tag (Early Mover, Momentum Trader, Liquidity Provider, Sniper/Bot, Long-Term Holder)
* `reputation_score` — Cortex composite reputation score (0–100)
* `sector_preference` — inferred sector/category preference from trade history

***

**Event**

An Event represents a discrete on-chain action. Event types include:

* `swap` — token exchange in a DEX pool
* `liquidity_add` / `liquidity_remove` — pool liquidity changes
* `transfer` — token transfer between addresses
* `token_creation` — new token deployed

Each Event carries: `type`, `token_address`, `wallet_address`, `amount`, `timestamp`, `tx_hash`.

## How Data Flows

RetinaOS processes on-chain activity through a layered pipeline:

1. **Indexer** watches Robinhood Chain (Arbitrum Orbit RPC) and captures raw events.
2. **Enrichment** transforms raw events into structured Token, Wallet, and Event objects.
3. **Cortex scoring** reads enriched objects and continuously updates risk and reputation scores.
4. **AI layer** reads scored objects and generates plain-language summaries.
5. **Dashboard and API** surface the final results to you in real time.

<Note>
  All data is derived from public on-chain activity. RetinaOS does not use or require access to Robinhood's private infrastructure.
</Note>

## Data Freshness

| Data Type                 | Update Frequency            |
| ------------------------- | --------------------------- |
| Token price & volume      | Near real-time (seconds)    |
| AI summaries (hot tokens) | Every few minutes           |
| Cortex scores             | Continuously as events land |
| Historical PnL            | Recalculated on new events  |