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

# Data Model

> Understanding Cryptique's unified data model for Web3 analytics

## Overview

Cryptique's data model is designed to solve the unique challenges of Web3 analytics by unifying three types of data into cohesive user profiles:

```mermaid theme={null}
flowchart LR
    subgraph Profile["USER PROFILE"]
        E[Events<br/>off-chain<br/>distinct_id]
        W[Wallets<br/>connected<br/>wallet_address]
        T[Transactions<br/>on-chain<br/>wallet_address]
    end
    E <--> W
    W <--> T
```

## Core Concepts

### Events

Events are discrete actions that users take. They form the foundation of behavioral analytics.

```javascript theme={null}
{
  "event_name": "swap_initiated",
  "distinct_id": "user_12345",
  "timestamp": "2024-01-15T10:30:00Z",
  "properties": {
    "input_token": "ETH",
    "output_token": "USDC",
    "amount": 1.5
  }
}
```

**Event Types**:

* **Auto-events**: Captured when enabled (`page_view`, `element_click`, `page_scroll`, `page_summary`, etc.) — see [Auto-Events](/data-in/auto-events)
* **Custom events**: Tracked via `Cryptique.track()`
* **Transaction events**: Generated from indexed smart contracts

See [Events & Properties](/data-in/events-and-properties) for details.

### User Profiles

User profiles aggregate all activity for a single user, identified by `distinct_id`.

```javascript theme={null}
{
  "distinct_id": "user_12345",
  "properties": {
    // Identity
    "email": "user@example.com",
    "username": "defi_whale",
    
    // Lifecycle
    "first_seen": "2024-01-01T00:00:00Z",
    "last_seen": "2024-01-15T10:30:00Z",
    "session_count": 47,
    
    // Custom
    "plan": "pro",
    "referral_source": "twitter",
    
    // Web3
    "wallets": ["0x1234...", "0xabcd..."],
    "primary_wallet": "0x1234...",
    "is_web3_user": true
  }
}
```

**Profile Sources**:

* **identify()**: Explicitly set user properties
* **people methods**: Set, increment, append properties
* **Wallet enrichment**: Automatically added from blockchain data
* **Computed**: Derived from event history

See [User Profiles](/data-in/user-profiles) for details.

### Groups

Users can belong to **groups** (companies, workspaces, teams) under a string **group key** and one or more **group IDs**. Membership is updated with `Cryptique.set_group` / `add_group` / `remove_group`. Properties on the group itself (not the person) are updated via `Cryptique.get_group(key, id).set(...)`. Group fields are merged into event `custom_properties` when events are sent. See [Groups](/data-in/sdk-reference/groups).

### Transactions

On-chain transactions from your indexed smart contracts.

```javascript theme={null}
{
  "transaction_hash": "0xabc123...",
  "wallet_address": "0x1234567890abcdef...",
  "contract_name": "Swap Router",
  "method_name": "swapExactTokensForTokens",
  "timestamp": "2024-01-15T10:30:15Z",
  "chain": "ethereum",
  "properties": {
    "input_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "output_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount_in": "1500000000000000000",
    "amount_out": "1500000000"
  }
}
```

See [Transactions](/data-in/transactions) for details.

## Data Linking

The power of Cryptique is in automatically linking these data types:

### distinct\_id ↔ wallet\_address

When a user connects their wallet:

```javascript theme={null}
// User visits site (anonymous)
distinct_id: "anon_xyz789"

// User connects wallet
Cryptique.walletAddress("0x1234...");

// Profile now linked
{
  "distinct_id": "anon_xyz789",
  "wallet_address": "0x1234..."
}
```

### wallet\_address ↔ Transactions

Once a wallet is linked, all transactions from that wallet are attributed to the user:

```mermaid theme={null}
flowchart TB
    P[User Profile<br/>distinct_id: anon_xyz789]
    P --> E[Events<br/>page_view, element_click, custom…]
    P --> W[Wallet: 0x1234...]
    P --> T[Transactions]
    T --> T1[Swap Jan 15]
    T --> T2[Stake Jan 16]
    T --> T3[Claim Jan 20]
```

### Multiple Wallets

Users can connect multiple wallets:

```javascript theme={null}
Cryptique.walletAddress("0x1234..."); // First wallet
Cryptique.walletAddress("0xabcd..."); // Second wallet

// Profile now has both
{
  "distinct_id": "user_12345",
  "wallets": ["0x1234...", "0xabcd..."],
  "primary_wallet": "0x1234..."
}
```

## Property Types

Cryptique supports these property data types:

| Type              | Example                     | Operators                                     |
| ----------------- | --------------------------- | --------------------------------------------- |
| **String**        | `"ethereum"`                | is, is\_not, contains, is\_set                |
| **Number**        | `1500.50`                   | equals, greater\_than, less\_than, between    |
| **Boolean**       | `true`                      | is\_true, is\_false                           |
| **Date/Datetime** | `"2024-01-15"`              | before, after, between, in\_the\_last         |
| **List**          | `["ETH", "USDC"]`           | any\_in\_list, all\_in\_list + item operators |
| **Object**        | `{name: "...", value: 100}` | Nested property access                        |

See [Filters & Operators](/analysis/filters-and-operators) for full operator reference.

## Sessions

Sessions group user activity with these rules:

* **Timeout**: 30 minutes of inactivity starts a new session
* **Midnight**: New session at midnight (user's local time)
* **UTM change**: New campaign parameters start a new session

Session properties are inherited by all events within the session:

```javascript theme={null}
// Session properties (set once)
{
  "session_id": "sess_abc123",
  "initial_referrer": "https://twitter.com/...",
  "utm_source": "twitter",
  "landing_page": "/"
}

// Event inherits session context
{
  "event_name": "swap_completed",
  "session_id": "sess_abc123",  // inherited
  "utm_source": "twitter"       // inherited
}
```

## Data Flow

```mermaid theme={null}
flowchart LR
    subgraph Collection["Collection"]
        A[Website / dApp]
        B[Blockchain Indexer]
    end
    subgraph Processing["Processing"]
        C[Cryptique API]
        D[CQ Intel Merge Engine]
    end
    subgraph Output["Output"]
        E[Dashboard & Reports]
        F[User Profiles]
    end
    A -->|Events SDK| C
    B -->|Transactions| D
    C --> D
    D --> F
    D --> E
```

1. **Collection**: SDK sends events; indexer captures transactions
2. **Processing**: CQ Intelligence links wallets to users
3. **Enrichment**: Wallet data adds profile properties
4. **Storage**: Unified profiles stored for analysis
5. **Query**: Reports access complete user journeys

## Next Steps

<CardGroup cols={2}>
  <Card title="Events & Properties" icon="bolt" href="/data-in/events-and-properties">
    Deep dive into event structure
  </Card>

  <Card title="User Profiles" icon="user" href="/data-in/user-profiles">
    Understand profile management
  </Card>

  <Card title="Transactions" icon="file-contract" href="/data-in/transactions">
    On-chain data integration
  </Card>

  <Card title="Default Properties" icon="list" href="/data-in/default-properties">
    Auto-captured properties
  </Card>
</CardGroup>