Allium

View saved version →

---
name: beam-pipelines
description: |
  **Required for Beam pipeline tools: create_beam_config, deploy_beam_pipeline, etc.**
  **Beam** is Allium's custom real-time data pipeline product, built on top of
  [Allium Datastreams](https://app.allium.so/build/datastreams). It lets you tap into
  any of Allium's real-time blockchain data streams — covering 80+ chains — and apply
  your own filters and JavaScript transformations before delivering the results to
  Kafka, SNS, or other destinations.

  Common use cases: real-time alerts on contract events, custom data feeds filtered
  to specific wallets or protocols, and streaming enriched data to your own pipeline.

  Browse available data streams at [app.allium.so/build/datastreams](https://app.allium.so/build/datastreams).
  To get access or learn more, reach out to support@allium.so.

  Read this skill for detailed configuration guides and examples.
gate: app__custom_transforms
---

# Beam Pipeline Configuration Guide

## What is Beam?

Beam is Allium's custom real-time data pipeline product, built on top of [Allium Datastreams](https://app.allium.so/build/datastreams). It lets you tap into any of Allium's real-time blockchain data streams — covering 80+ chains — and apply your own filters and transformations before delivering the results to your preferred destination.

```text
Source (any Allium Datastream) → Transforms (filter/transform) → Sinks (Kafka, SNS, and more)
```

With Beam, you can:

- **Filter** high-volume blockchain streams down to just the events you care about (specific contracts, addresses, event signatures)
- **Transform** data in-flight using JavaScript to parse, enrich, or reshape records before delivery
- **Deliver** processed data to Kafka topics or SNS (with more sink types coming soon) for consumption by your applications

Browse the full catalog of available data streams at [app.allium.so/build/datastreams](https://app.allium.so/build/datastreams).

**Common use cases:**

- Real-time alerts on contract events (e.g., large token transfers, liquidations)
- Custom data feeds filtered to specific wallet addresses or protocols
- Live monitoring and anomaly detection for DeFi activity
- Streaming enriched trade data to your own analytics pipeline

**Interested in Beam?** Reach out to <support@allium.so> to get access.

## Quick Start Workflow

1. **Create config** → `create_beam_config`
2. **Deploy pipeline** → `deploy_beam_pipeline`
3. **Verify deployment** → `get_beam_deployment_stats`

Always check deployment stats after deploying to confirm workers are healthy.

After deploying, you'll receive:

- **Kafka connection credentials** (bootstrap server, username, password)
- **Consumer code snippets** in Python and TypeScript, ready to copy-paste
- A **UI link** to manage your pipeline at `app.allium.so/build/beam/{config_id}`

**Updating a pipeline:** Just call `deploy_beam_pipeline` again after updating the config.
Deployment is idempotent and applies changes in place with zero downtime.
Do NOT teardown before redeploying—that causes unnecessary downtime.

## Configuration Reference

### Source

Beam sources connect to Allium's Datastreams. You select a chain and entity type to stream.

```json
{
  "chain": "polygon",
  "entity": "log",
  "is_zerolag": false
}
```

| Field        | Required | Description                              |
| ------------ | -------- | ---------------------------------------- |
| `chain`      | Yes      | Blockchain to source data from           |
| `entity`     | Yes      | Entity type to stream (see table below)  |
| `is_zerolag` | No       | Low-latency source mode (default: false) |

#### Supported Chains & Entities

Check the [Datastreams catalog](https://app.allium.so/build/datastreams) for the latest availability, or reach out to <support@allium.so> to request a specific chain or entity.

### Transforms

Two transform types are available. You can chain multiple transforms together — data flows through them in order.

#### re

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: customer-support
description: |
  **Customer support and solutions engineering guidance using internal runbooks.**

  Read this skill when a user:
  - Reports errors, timeouts, or unexpected query results
  - Asks how to get started with Allium or choose a product
  - Needs help integrating Allium APIs, datashares, or datastreams
  - Has questions about data coverage, schemas, or chain-specific behavior
  - Wants guidance on a use case (DEX, NFT, bridge, stablecoin, etc.)
  - Asks about account access, API keys, billing, or permissions
  - Needs help with AI/MCP setup or troubleshooting
  - Mentions data discrepancies or missing data
---

# Customer Support & Solutions Engineering

You are acting as a support engineer and solutions engineer for Allium. Use the internal support runbooks to answer customer questions accurately and consistently.

## Identify the mode

Determine whether the customer needs **support** or **solutions** help:

- **Support** (something is broken or confusing): errors, timeouts, missing data, unexpected results, access issues
- **Solutions** (building something new): product selection, integration guidance, use-case architecture, onboarding

This affects tone and approach. Support is diagnostic and reassuring. Solutions is consultative and forward-looking.

## How to use runbooks

The runbooks live at `internal/support-runbooks` in the docs system. **Navigate progressively** - never guess file paths.

### Step 1: Browse the top-level structure

```text
browse_docs(path="internal/support-runbooks")
```

This returns the README with the full directory layout and category descriptions.

### Step 2: Browse the relevant category

```text
browse_docs(path="internal/support-runbooks/{category}")
```

### Step 3: Read the specific runbook

```text
browse_docs(path="internal/support-runbooks/{category}/{file}.md")
```

### Fallback: search

If the category isn't obvious, use `search_docs` with relevant keywords to find the right runbook.

## Intent routing table

Map customer intent to the right runbook category:

| Intent                                                         | Category path         | Examples                                                                                               |
| -------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
| Onboarding, product selection, first query, billing questions  | `getting-started/`    | "How do I get started?", "Which product should I use?", "How does pricing work?"                       |
| Explorer, Realtime APIs, Datastreams, Datashares product help  | `products/`           | "How do I use Explorer?", "How do I set up a datashare?", "What realtime APIs are available?"          |
| Schema questions, data coverage, data quality                  | `data/`               | "What chains do you support?", "What tables have DEX data?", "Why is this column null?"                |
| Solana, Hyperliquid, Bitcoin, EVM, Cosmos chain-specific help  | `chains/`             | "How do I query Solana transactions?", "Do you support Hyperliquid?", "How are EVM traces structured?" |
| Bridge, DEX, NFT, stablecoin, DeFi use cases                   | `use-cases/`          | "How do I track bridge transfers?", "Can I get DEX volume by protocol?"                                |
| AI agent setup, MCP server configuration                       | `ai-and-mcp/`         | "How do I set up the MCP server?", "Can I use Allium with my AI agent?"                                |
| API keys, permissions, team access, security                   | `account-and-access/` | "How do I rotate my API key?", "How do I add a teammate?", "What permissions does my key have?"        |
| Data discrepancies, query failures, error messages, escalation | `troubleshooting/`    | "My query is timing out", "The data doesn't match Etherscan", "I'm ge

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: pdf-reports
description: |
  **Required for generate_pdf_report tool.**

  Read this skill BEFORE calling generate_pdf_report to understand
  how to write professional analytical reports with narrative depth.
---

# PDF Report Generation

## Report Architecture

Every report MUST follow this structure. No exceptions.

### 1. Executive Summary (text section)

- 2-3 paragraph narrative. Lead with a thesis statement about the key finding.
- Bold key statistics inline: **$266.3 billion**, **+317% YoY**.
- Provide context for every number (vs prior period, vs benchmark, vs market total).
- NOT a bullet list. Write flowing prose that tells the story.

### 2. Key Insights (text section)

- 3-5 numbered insights. The "if you read nothing else" page.
- Each insight: **Bold headline (10 words max)** followed by supporting data and one-sentence implication.
- Example: "**1. Stablecoin payments surpassed credit card volume.** Monthly payment volume hit **$48.3B** in February, exceeding Visa's average merchant settlement volume for the first time. This signals stablecoins are crossing from speculation into real commerce."

### 3. Themed Analytical Sections (3-6 sections)

Each theme follows a repeating pattern of three sections:

1. **Context text** (titled) - Why this data matters. Frame the question being answered. 1-2 sentences.
2. **Chart or table** (titled) - The visualization itself.
3. **Interpretation text** (empty title `""`) - What the data reveals. Bold the key takeaway. Call out anomalies, benchmarks, or surprising patterns. 2-4 sentences.

This interleaved pattern is critical. Charts must never appear without surrounding context and interpretation.

### 4. Methodology (text section, for reports with 3+ data sections)

- Data sources and APIs used.
- Time periods and filters applied.
- Known limitations or caveats.
- Keep it brief but honest about what the data does and doesn't cover.

## Content Writing Rules

### Before every chart/table

Write 1-2 sentences framing what the reader is about to see and why it matters.

### After every chart/table

Use an empty-title text section (`"title": ""`) for interpretation:

- 2-4 sentences interpreting findings.
- **Bold the key takeaway** so a skimmer catches it.
- Call out anomalies, inflection points, or surprising patterns.
- Provide context: vs prior period, vs benchmark, vs total.

### Statistics and numbers

- Bold key statistics inline: **$266.3 billion**, **+317%**.
- Always contextualize: "representing **42%** of total DEX volume, up from 28% last quarter."
- Don't just report WHAT. Explain WHY it matters.

### Section titles

- Use insight-driven titles, not metric-driven titles.
- Good: "Payment Adoption Outpaces Speculation"
- Bad: "Daily Trading Volume"

### Cross-references

- When data in one section relates to another, say so: "Consistent with the supply shift noted above..."

## Anti-Patterns (avoid these)

- **Bullet-list executive summaries** - Write prose paragraphs instead.
- **Naked charts** - Every chart needs context before AND interpretation after.
- **Data-descriptive section titles** - "Daily Trading Volume" tells the reader nothing. Use insight-driven titles.
- **Reports without methodology** - Include data sources and limitations for any report with 3+ data sections.
- **Restating numbers without interpretation** - Don't say "Volume was $10B." Say "Volume hit **$10B**, a **+34%** increase that coincided with the ETH ETF approval."
- **Flat structure** - Don't dump a sequence of charts. Group related data into themed sections with narrative flow.

## Empty-Title Sections

Set `"title": ""` on a section to render it without a header or TOC entry. The content flows directly below the previous section. Use this for chart/table interpretations:

```json
{"title": "Payment Adoption Outpaces Speculation", "type": "text", "data": {"content": "The shift from speculative trading to real payment usage is the defining trend of 2026..."}},
{"title": "Monthly 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: product-guide
description: |
  Guide to Allium's four core products: Explorer, Realtime APIs, Datastreams,
  and Datashares. Explains what each product does, who it's for, and how to
  choose the right one for a customer's use case.

  Read this skill when a customer asks about Allium's products, wants to
  understand the difference between them, needs help choosing a product, or
  asks questions like "which product should I use?" or "what does Allium offer?"
  It also carries the canonical, dated list of supported blockchains — read it
  for any "what chains / how many chains does Allium support?" question and cite
  that list instead of answering from memory.
---

# Allium Product Guide

Allium offers four core products for accessing blockchain data. Each serves a
different access pattern, latency requirement, and integration style. Explorer,
Datashares, and Datastreams share one historical data platform; the Realtime
APIs serve a smaller, separate set of chains.

> **Answering "what chains does Allium support?" (grounding rule)**
>
> Chain names and counts must come from the canonical list, never from memory —
> generating them from memory produces unstable totals and invented chains.
>
> 1. Fetch the **Allium Supported Chains — Canonical List** reference file (see
>    "Reference files" below) and quote it. For an up-to-the-minute Realtime
>    figure, call the `realtime_get_supported_chains` tool.
> 2. Always say **which product** a count refers to — the historical data
>    platform (Explorer / Datashares / Datastreams) and the Realtime APIs have
>    different totals.
> 3. The headline total must equal the number of rows for that product in the
>    canonical list. Do not round to a vague "80+/130+/150+" — cite the exact
>    count and state the list's snapshot date in the answer, so a reader can see
>    how current it is (e.g. "**[N]** chains on the historical data platform, as
>    of **[snapshot date]**"). Pull both **[N]** and the date from the fetched
>    reference file — never from this instruction or from memory.
> 4. If a chain is not in the canonical list, say it is not currently supported
>    rather than guessing.

## Product Overview

| Product           | Access Pattern                      | Latency                                | Pricing Model              | Best For                                            |
| ----------------- | ----------------------------------- | -------------------------------------- | -------------------------- | --------------------------------------------------- |
| **Explorer**      | SQL queries via web UI or API       | ~1 hour freshness, ~4-5s query time    | Query compute time         | Ad-hoc analysis, dashboards, research               |
| **Realtime APIs** | REST API (pull)                     | 50-100ms response, 3-5s data freshness | API call volume            | Application backends, wallets, trading UIs          |
| **Datastreams**   | Push via Kafka/PubSub/SNS/WebSocket | 3-5s data freshness                    | Data destinations & egress | Event-driven architectures, real-time pipelines     |
| **Datashares**    | Native tables in your warehouse     | 1-3 hours batch, sub-minute streaming  | Number of chains & schemas | Institutional analytics, joining with internal data |

## Explorer

**What it is:** A SQL-based analytics workspace at `app.allium.so/explorer` that
lets users query, visualize, and share blockchain data across every chain on the
historical data platform (see the canonical chain list for the exact count). Powered
by Snowflake (OLAP).

**Key capabilities:**

- Full SQL interface with cross-chain queries (e.g., `crosschain.dex.trades`)
- 1,000+ enriched schemas: raw, decoded, DEX, DeFi, NFTs, stablecoins, wallet 360, metrics, bridges, prices, PnL
- Interactive chart builder with public sharing and embed links
- CSV and API data upload — join your own data with on-chain data
- Parameterized queries for reusable, dynamic SQL
- AI Assistant 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: sql-optimization
description: |
  **Required reading before writing or running any SQL.** Patterns for Snowflake
  query performance and chain-specific pitfalls.

  Covers: default time ranges, partition-pruning rules, CTE filtering, `QUALIFY`
  for dedup, `UNION ALL` over `UNION`, `APPROX_COUNT_DISTINCT` for exploration,
  pre-aggregated `*.metrics.*` tables vs raw aggregation, EVM address lowercasing
  (and when not to), per-chain vs `crosschain.*` tables, verifying guessed
  categorical filter values with `SELECT DISTINCT`, and Solana voting/non-voting
  optimized views.

  Call `get_skill(name="sql-optimization")` before writing SQL —
  especially for large tables, long time ranges, or crosschain queries.
---

# SQL Optimization for Snowflake

Apply these patterns when writing or optimizing SQL against Allium's Snowflake
warehouse, especially for multi-billion-row tables (`*.raw.transactions`,
`*.raw.transfers`, `*.raw.logs`, `*.dex.trades`).

## Verify Guessed Categorical Filters

Before committing to guessed categorical values in a `WHERE` clause, run a
quick exploration query to verify the values present in the table. Use schema
descriptions to choose the table and column; use data exploration when the
exact stored value is not already confirmed.

**For categorical/text columns** you plan to filter on (e.g., `coin`,
`market_type`, `pair`, `status`, `type`, `dex_name`, `chain`):

- Run `SELECT DISTINCT <column> FROM <table> [WHERE <recent_timestamp_filter>] LIMIT 50` first
- On large tables, scope with a recent timestamp filter (e.g., `WHERE timestamp >= DATEADD('day', -7, CURRENT_DATE())`) to keep exploration cheap
- For small metadata/dimension tables, a bare `SELECT DISTINCT` is fine

If schema content or sample rows show the exact stored value, use that spelling.
If they do not, verify the value from the table before using it as a filter.

**If a query unexpectedly returns 0 rows, check categorical filters before
concluding the data is missing.** Re-run with `SELECT DISTINCT` or a `LIKE
'%term%'` pattern.

## SQL Pitfalls (Always Apply)

**Date-filter every query on large tables.** Most large tables
(`*.raw.transactions`, `*.raw.transfers`, `*.dex.trades`, `*.raw.logs`) are
clustered on `block_timestamp::date` or `timestamp::date`. Without a date
filter, queries scan the entire table — billions of rows, slow and expensive.
Always include a bounded date range (e.g., `WHERE block_timestamp >=
'2026-01-01'`). If the user didn't specify a range, pick a default (last 30
days for activity, last 1 day for current state) and state the assumption.

**Default to recent time windows when the user is silent:**

- **7 days** (1 week) — for exploratory queries, quick analysis
- **30 days** (1 month) — for trend analysis, aggregations

```sql
-- 1 week (default for exploration)
WHERE block_timestamp >= DATEADD(day, -7, CURRENT_DATE())

-- 1 month (for trends)
WHERE block_timestamp >= DATEADD(day, -30, CURRENT_DATE())
```

If the user needs data beyond 30 days: confirm first ("This query covers a
large time range and may be slow. Is that okay?"), consider breaking into
smaller batches (e.g., monthly), or use more aggressive filtering on other
columns.

**Lowercase EVM addresses before filtering or joining — but only EVM.** Allium
stores EVM addresses (`0x...` hex) lowercase, while users and block explorers
often paste them checksummed. `WHERE from_address = '0xAbC123...'` on an EVM
table silently returns 0 rows; apply `LOWER()` to user-supplied EVM addresses.
**Do NOT lowercase non-EVM addresses.** Solana, Tron, Sui, and other non-EVM
chains store addresses in their native case-sensitive form (e.g., Solana
base58 `HyperSPG8w4j...`); lowercasing changes the address's meaning. In
`crosschain.*` tables, key on `chain` to decide whether to apply `LOWER()` per
row.

**Prefer per-chain tables; crosschain joins need `(chain, address)`.** The
`crosschain.*` schemas are convenient but significantly slower than per-chain
tables, esp

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: vercel-app-deployment
description: |
  **Required for Vercel app tools.**

  Read this skill BEFORE using create_vercel_app to understand
  app types, configuration options, and the iteration workflow.
---

# Vercel App Deployment

Generate and deploy Next.js apps powered by Allium data APIs.

## App Types

### wallet_tracker

Track wallet holdings, PnL, and transaction history.

**Features:**

- Token holdings with USD values
- PnL chart showing portfolio value over time
- Transaction history with send/receive indicators
- Multi-chain support

**Options:**

```json
{
  "show_pnl": true,           // Show PnL chart (default: true)
  "show_transactions": true   // Show transaction history (default: true)
}
```

**Example:**

```json
{
  "app_type": "wallet_tracker",
  "title": "My Wallet Tracker",
  "chains": ["ethereum", "polygon", "arbitrum"],
  "theme": "dark",
  "options": {"show_pnl": true, "show_transactions": true}
}
```

### token_analytics

Analyze token prices and market stats.

**Features:**

- Price chart with time range selection (24H, 7D, 30D, 90D)
- Token stats cards (price, price change 24h)

**Options:**

```json
{
  "show_stats": true    // Show stats cards (default: true)
}
```

**Example:**

```json
{
  "app_type": "token_analytics",
  "title": "Token Analyzer",
  "chains": ["ethereum", "base"],
  "theme": "light"
}
```

### price_chart

Dedicated OHLCV price chart with dynamic coloring and detailed stats.

**Features:**

- OHLCV (Open, High, Low, Close, Volume) price chart
- Dynamic green/red coloring based on price direction
- Detailed OHLC tooltip showing all price data points
- Stats card with current price, 24h change, 24h high/low
- Time range selection (24H, 7D, 30D, 90D)
- Optional pre-configured token address

**Options:**

```json
{
  "default_token_address": null,  // Pre-configured token (default: null)
  "default_chain": null,          // Pre-configured chain (default: first chain)
  "show_ohlc_details": true,      // Show OHLC in tooltip (default: true)
  "show_stats_card": true,        // Show price stats card (default: true)
  "show_token_selector": true     // Allow changing token (default: true)
}
```

**Example:**

```json
{
  "app_type": "price_chart",
  "title": "WETH Price Tracker",
  "chains": ["ethereum", "base", "arbitrum"],
  "theme": "dark",
  "options": {
    "default_token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "show_ohlc_details": true
  }
}
```

**When to use price_chart vs token_analytics:**

- Use `price_chart` when the focus is on detailed price visualization with OHLCV data and dynamic coloring
- Use `token_analytics` for general token analysis with market cap, volume, and liquidity stats

### wallet_flows

Visualize wallet inflows and outflows as a Sankey diagram.

**Features:**

- Sankey flow chart showing token transfers
- Table view with detailed inflow/outflow data
- Aggregates transfers by counterparty

**Example:**

```json
{
  "app_type": "wallet_flows",
  "title": "Wallet Flow Analyzer",
  "chains": ["ethereum", "polygon"],
  "theme": "dark"
}
```

### custom_dashboard

Custom SQL dashboard with configurable widgets.

**Features:**

- Data tables from Allium Explorer queries
- Charts (line, bar, pie) from query results
- Metric cards for single values

**Options:**

```json
{
  "widgets": [
    {
      "type": "metric",
      "title": "Total Users",
      "query_id": "abc123"
    },
    {
      "type": "chart",
      "title": "Daily Active Users",
      "query_id": "def456",
      "chart_type": "line"
    },
    {
      "type": "table",
      "title": "Top Wallets",
      "query_id": "ghi789"
    }
  ]
}
```

Widget types:

- `metric`: Single value (first cell of query result)
- `chart`: Line, bar, or pie chart
- `table`: Data table with all results

## Supported Chains

- `ethereum` - Ethereum Mainnet
- `polygon` - Polygon PoS
- `arbitrum` - Arbitrum One
- `optimism` - Optimism
- `base` - Base
- `avalanche` - Avalanche C-Chain
- `bsc

Preview of the first 4,000 characters. Read full instructions →