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

# Dune Queries

> Reference for all Dune Analytics queries used in WalletWall — purpose, field contracts, cadence, and staleness thresholds.

# Dune Queries

WalletWall uses Dune Analytics scheduled queries as a source-backed data layer for holder analytics, whale activity, and Quantum Intelligence signals. All Dune data is scheduled and cached — it is never live streaming.

<Note>
  Public docs use source aliases instead of deployment environment variable names. Runtime secret and query-ID configuration belongs in the private deployment environment, not Mintlify docs.
</Note>

## Holder Wall queries

### 48h Active Wallets

**Public source alias:** Active wallet feed

Powers the Active Wallets tab in the Holder Wall treemap. Returns wallets that have been active within the last 48 hours, with balance and activity tier information.

Used by: the Holder Wall API route (`/api/holder-wall`)

### Whale Trades

**Public source alias:** Whale trade feed

Powers the Whale Wallets tab in the Holder Wall treemap. Returns large-balance wallets with trade activity data.

Used by: the Holder Wall API route (`/api/holder-wall`)

## Whale Watcher queries

### 12-Week Active Wallets

**Public source alias:** 12-week activity feed

Provides per-day activity data for the 12-week heatmap in the Whale Watcher workspace.

**Required row fields:**

| Field                  | Description                             |
| ---------------------- | --------------------------------------- |
| `address`              | Wallet address                          |
| `label`                | Entity label or category                |
| `category`             | Activity category                       |
| `tx_count_48h`         | Transaction count in the last 48h       |
| `unique_receivers_48h` | Unique receiver count in the last 48h   |
| `usd_volume_48h`       | USD volume in the last 48h              |
| `last_seen`            | Last observed activity timestamp        |
| `activity_tier`        | Overall activity tier                   |
| `activity_day`         | Date of the activity row                |
| `week_number`          | Week number in the 12-week window       |
| `day_of_week`          | Day of week (0–6)                       |
| `tx_count_day`         | Transaction count for this day          |
| `unique_receivers_day` | Unique receivers for this day           |
| `usd_volume_day`       | USD volume for this day                 |
| `intensity_score`      | Computed intensity for heatmap coloring |
| `day_activity_tier`    | Activity tier for this specific day     |

Optional — falls back to 48h display when not configured.

### Wallet Portfolio

**Public source alias:** Wallet portfolio feed

Provides per-wallet token holdings or trading exposure for the wallet holdings strip.

Two query shapes are supported. The API detects the shape from the columns present:

<Tabs>
  <Tab title="Option A — Balance">
    ```
    wallet_address, token_symbol, token_address, balance, balance_usd
    ```

    Shows the wallet's current holdings denominated in USD.
  </Tab>

  <Tab title="Option B — Trading Exposure">
    ```
    wallet_address, token_symbol, token_address, total_traded_usd, trade_count, last_trade_at
    ```

    Shows the wallet's historical DEX trading exposure.
  </Tab>
</Tabs>

Wallets not present in the result set silently show no holdings strip (`inDataset: false`).

## Quantum Intelligence queries

These queries provide source-backed facts for the Quantum Exposure Score and its components. All four queries run on scheduled cadences and their results are cached.

### walletwall\_dormant\_quantum\_exposure\_v1

**Public source alias:** Dormancy exposure feed\
**Suggested cadence:** Weekly

Emits one row per wallet that is both dormant (no observed outgoing activity beyond a configurable threshold) and has implied ECDSA/secp256k1 signature exposure. Provides the primary data for dormant-holder quantum-exposure signals in the Holder Wall treemap and the Vault Readiness Card.

**Key output fields:**

| Field                       | Description                                                                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `wallet_address`            | EVM wallet address (checksummed)                                                                 |
| `signature_exposure_status` | `signature_exposure_observed`, `no_outgoing_signature_observed`, `contract_wallet`, or `unknown` |
| `dormancy_bucket`           | `warm_dormant_30_180d`, `cold_dormant_180_730d`, or `ancient_dormant_730d_plus`                  |
| `days_dormant`              | Days since last observed outgoing transaction                                                    |
| `balance_usd`               | USD-denominated balance at query execution time                                                  |
| `entity_label`              | Community/source-backed category label                                                           |
| `is_contract`               | True if the address is a contract wallet                                                         |
| `migration_readiness_hint`  | e.g., `safe_wallet_detected`, `account_abstraction_detected`                                     |

**Staleness threshold:** 30 hours — show stale badge but do not hide signal.

### walletwall\_wallet\_signature\_exposure\_v1

**Public source alias:** Signature exposure feed\
**Suggested cadence:** Daily or on-demand per wallet

Emits per-wallet source facts for quantum-signature exposure heuristics. Used for single-wallet lookups in Whale Watcher and Coinstellation detail panels.

**Key output fields:**

| Field                  | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `is_contract`          | True if address has deployed contract code                     |
| `first_outgoing_tx_at` | Timestamp of first outgoing transaction; null if none observed |
| `signed_tx_count`      | Count of outgoing transactions                                 |
| `days_dormant`         | Days since last activity; null if no activity observed         |
| `signature_scheme`     | `ecdsa_secp256k1` for EVM EOAs; `unknown` for contracts        |
| `exposure_status`      | Same four-value enum as above                                  |

**Staleness threshold:** 30 hours.

### walletwall\_quantum\_value\_at\_risk\_v1

**Public source alias:** Value-at-risk feed\
**Suggested cadence:** Daily

Provides source-backed balance and supply-share facts for the `valueAtRiskScore` component of the Quantum Exposure Score.

**Key output fields:**

| Field                | Description                                 |
| -------------------- | ------------------------------------------- |
| `native_balance_usd` | Native asset (ETH) balance in USD           |
| `token_balance_usd`  | ERC-20 token balance in USD                 |
| `total_balance_usd`  | Sum of native + token balances              |
| `top_token_symbol`   | Symbol of the largest single token position |
| `holder_rank`        | Holder rank for this token at query time    |
| `supply_share`       | Fraction of token supply held (0.0–1.0)     |

**Staleness threshold:** 30 hours. USD values are snapshots — present them as estimates.

### walletwall\_wallet\_migration\_readiness\_v1

**Public source alias:** Migration readiness feed\
**Suggested cadence:** Weekly

Emits migration-readiness signals and wallet structure facts. Feeds the `migrationReadinessScore` component and the `migrationReadinessHints` section of the Vault Readiness Card.

**Key output fields:**

| Field                           | Description                                                         |
| ------------------------------- | ------------------------------------------------------------------- |
| `is_contract_wallet`            | True if the address is any contract-based wallet                    |
| `contract_wallet_type`          | `safe`, `gnosis_multisig`, `erc4337_aa`, `other_contract`, or null  |
| `is_safe_wallet`                | True if wallet is a Gnosis Safe instance                            |
| `is_account_abstraction_wallet` | True if ERC-4337 AA is detected                                     |
| `recent_migration_signal`       | True if a token migration or key-rotation event was observed        |
| `risky_approval_count`          | Count of active ERC-20 approvals with unlimited or large allowances |

**Staleness threshold:** 7 days — migration-readiness facts change slowly.

## Stable Seer queries (drafts)

Draft SQL for two Stable Seer queries is maintained privately (not in these public docs):

* **Peg metrics** — peg stability and deviation across major stablecoins
* **Liquidity flows** — stablecoin inflows and outflows across major DeFi protocols

These are drafts for Ethereum and EVM-compatible chains. Solana holder analytics are excluded.

## Freshness and staleness summary

| Query                                      | Cadence           | Staleness threshold | Stale behaviour                            |
| ------------------------------------------ | ----------------- | ------------------- | ------------------------------------------ |
| `walletwall_dormant_quantum_exposure_v1`   | Weekly            | 30 hours            | Show stale badge; do not hide signal       |
| `walletwall_wallet_signature_exposure_v1`  | Daily / on-demand | 30 hours            | Show stale badge; keep last known value    |
| `walletwall_quantum_value_at_risk_v1`      | Daily             | 30 hours            | Show stale badge; USD values are estimates |
| `walletwall_wallet_migration_readiness_v1` | Weekly            | 7 days              | Show stale badge; facts change slowly      |

All timestamps are surfaced to the UI via `queryRunAt` and the `freshnessStatus` / `staleMessage` mechanism in the Dune caching layer.

## Integration pattern

Queries are consumed through the `readOrCache()` pattern in the Dune caching layer. Each query requires:

1. A Dune saved query with a numeric query ID
2. A private deployment configuration entry that maps the relevant public source alias to that saved query ID
3. The configuration entry set in the deployment provider and local development environment

Missing query-ID configuration causes a `"query ID not configured"` warning to be appended to the API response's `metadata.warnings` array, which is then promoted to a caveat on the Quantum Exposure Score via `appendDuneSourceCaveats()`.

## Guardrails

* Dune data is scheduled/cached, never live. All outputs must be labeled as scheduled/cached in the UI.
* No exploitability claims. Dormancy and signature exposure are migration-readiness heuristics, not statements that any wallet is currently quantum-exploitable.
* No deanonymization. Entity labels are community/source-backed category labels only.
* No investment advice. These signals are informational risk indicators.
* Missing data returns `Unknown / insufficient data`, not fake precision.