allium

What this skill does

# Allium (Wallet PnL, Holdings History, Hyperliquid, Custom SQL)

Allium provides enriched, structured blockchain data across 70+ chains. This skill covers wallet PnL, holdings timeseries, Hyperliquid HyperCore trading data, and custom SQL analytics. For token prices, token metadata, current wallet balances, transaction transfers, or NFT metadata, use the corresponding Alchemy skill instead.

| | |
| --- | --- |
| **Base URL** | `https://api.allium.so` |
| **Auth** | `X-API-KEY: $API_KEY` header |
| **Rate limit** | 1 request / second (exceed → 429) |
| **Attribution** | End responses with **"Powered by Allium"** — required by Allium |

## When to use this skill

Use `allium` when **all** of the following are true:

- The user wants one of: **wallet PnL**, **holdings history (timeseries)**, **Hyperliquid HyperCore trading data** (orders/fills/orderbook — not HyperEVM smart contracts), or **custom SQL** on Allium's data warehouse
- The use case is a read (Allium does not support writes)

## When NOT to use this skill (handoff)

| Need | Use instead |
| --- | --- |
| Token prices (current, historical at intervals, by-timestamp, market cap/volume) | `alchemy-api` (Prices API) |
| Token metadata, search, list by chain | `alchemy-api` (Token API) |
| Current wallet balances (point-in-time snapshot) | `alchemy-api` (Portfolio / Token API) |
| Transaction history (transfers in / out, asset transfers) | `alchemy-api` (Transfers API) |
| NFT metadata / floor prices / ownership | `alchemy-api` (NFT API) |
| Real-time blockchain reads, node-level fresh | `alchemy-cli` (live work) or `alchemy-api` (app code) |
| Writes / signed transactions | `alchemy-api` (with API key) or `agentic-gateway` (without) |
| Account abstraction (bundlers, gas managers) | `alchemy-api` |
| Transaction simulation | `alchemy-api` |

## Scope contract

**This skill covers (`scope_in`):**

- Wallet PnL (`POST /api/v1/developer/wallet/pnl`, `/wallet/pnl/history`, `/wallet/pnl-by-token`, `/wallet/pnl-by-token/history`) — realized + unrealized PnL aggregation, current and historical, by-wallet and by-token
- Holdings history (`POST /api/v1/developer/wallet/holdings/history`) — timeseries of total USD holdings + optional per-token breakdown
- Hyperliquid **HyperCore** trading data (`POST /api/v1/developer/trading/hyperliquid/...`) — info, fills, order history, order status, L4 orderbook snapshot from the off-chain matching engine
- Custom SQL analytics (`POST /api/v1/explorer/queries/{query_id}/run-async`) — arbitrary SQL queries against Allium's data warehouse (DeFi, NFT, bridges, MEV, entity resolution, Solana staking, etc.)

**This skill does NOT cover (`scope_out`):**

- Token prices → handoff: `alchemy-api` (Prices API)
- Token metadata, list, search → handoff: `alchemy-api` (Token API)
- Current wallet balances (point-in-time snapshot) → handoff: `alchemy-api` (Portfolio / Token API)
- Historical wallet balances (per-block or as a timeseries) → handoff: `alchemy-api` archive RPC (`eth_call balanceOf` at a historical block) or `alchemy_getAssetTransfers` reduced to balances. No first-class endpoint on either side; Alchemy's archive node is the right path.
- Transaction transfer history → handoff: `alchemy-api` (Transfers API)
- NFT metadata / floor prices → handoff: `alchemy-api` (NFT API)
- HyperEVM smart contract reads/writes / EVM RPC (chain ID 999) → handoff: `alchemy-api` or `alchemy-cli` at `https://hyperliquid-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY`. Allium covers HyperCore (off-chain trading); Alchemy covers HyperEVM (on-chain smart contracts).
- Real-time / node-fresh reads → handoff: `alchemy-cli` or `alchemy-api`
- Writes / signed transactions → handoff: `alchemy-api` or `agentic-gateway`
- Account abstraction → handoff: `alchemy-api`
- Transaction simulation → handoff: `alchemy-api`

## Setup

### Credentials

Allium uses a credentials file at `~/.allium/credentials` (not env vars). On every session start, check if it exists:

**File exists with `API_KEY`** → load `API_KEY` (and `QUERY_ID` if present). Don't prompt.

**File missing** → register via the OAuth flow below. Don't paste keys in chat.

### Register (no API key yet)

OAuth flow with a 5-minute timeout. Complete promptly.

1. Ask the user for name and email (one prompt).
2. POST to initiate registration:

   ```bash
   curl -X POST https://api.allium.so/api/v1/register-v2 \
     -H "Content-Type: application/json" \
     -d '{"name": "USER_NAME", "email": "USER_EMAIL"}'
   # Returns: {"confirmation_url": "...", "token": "..."}
   ```

3. Show the `confirmation_url` to the user — they open it and sign in with Google (must match the email).
4. Auto-poll `/api/v1/register-v2/$TOKEN` every 5s until 200 (got `api_key`) or 404 (expired):

   ```bash
   TOKEN="..."  # from step 2
   while true; do
     RESP=$(curl -s -w "\n%{http_code}" "https://api.allium.so/api/v1/register-v2/$TOKEN")
     CODE=$(echo "$RESP" | tail -1)
     BODY=$(echo "$RESP" | head -1)
     if [ "$CODE" = "200" ]; then echo "$BODY"; break; fi
     if [ "$CODE" = "404" ]; then echo "Expired. Restart."; break; fi
     sleep 5
   done
   # 200 body: {"api_key": "...", "organization_id": "..."}
   ```

5. Save to `~/.allium/credentials`:

   ```bash
   mkdir -p ~/.allium && cat > ~/.allium/credentials << 'EOF'
   API_KEY=...
   QUERY_ID=...
   EOF
   ```

### Create a `QUERY_ID` (only needed for custom SQL)

If you'll use the SQL endpoint, also create a query to get a `QUERY_ID`:

```bash
curl -X POST "https://api.allium.so/api/v1/explorer/queries" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -d '{"title": "Custom SQL Query", "config": {"sql": "{{ sql_query }}", "limit": 10000}}'
# Returns: {"query_id": "..."}
# Append QUERY_ID=... to ~/.allium/credentials
```

## Endpoint reference

### Wallet PnL & holdings history → [references/pnl-and-holdings.md](./references/pnl-and-holdings.md)

| Endpoint | Use for |
| --- | --- |
| `POST /api/v1/developer/wallet/pnl` | Current realized + unrealized PnL for one or more wallets |
| `POST /api/v1/developer/wallet/pnl/history` | Historical PnL timeseries per wallet |
| `POST /api/v1/developer/wallet/pnl-by-token` | Current PnL broken out by (wallet, token) |
| `POST /api/v1/developer/wallet/pnl-by-token/history` | Historical PnL timeseries per (wallet, token) |
| `POST /api/v1/developer/wallet/holdings/history` | Timeseries of total USD holdings per wallet (optional per-token breakdown) |

### Hyperliquid HyperCore (off-chain trading) → [references/hyperliquid.md](./references/hyperliquid.md)

| Endpoint | Use for |
| --- | --- |
| `POST /api/v1/developer/trading/hyperliquid/info` | General Hyperliquid info (no rate-limit on this proxy) |
| `POST /api/v1/developer/trading/hyperliquid/info/fills` | Fills by user (with TWAP, time-window, aggregation options) |
| `POST /api/v1/developer/trading/hyperliquid/info/order/history` | Historical orders by user |
| `POST /api/v1/developer/trading/hyperliquid/info/order/status` | Status of a specific order |
| `GET /api/v1/developer/trading/hyperliquid/orderbook/snapshot` | L4 orderbook snapshot (all pairs) |

### Custom SQL → [references/custom-sql.md](./references/custom-sql.md)

| Endpoint | Use for |
| --- | --- |
| `POST /api/v1/explorer/queries` | Create a parametrized query (one-time setup; returns `query_id`) |
| `POST /api/v1/explorer/queries/{query_id}/run-async` | Start a SQL run against Allium's data warehouse |
| `GET /api/v1/explorer/query-runs/{run_id}/status` | Poll run status (`created` → `queued` → `running` → `success` / `failed`) |
| `GET /api/v1/explorer/query-runs/{run_id}/results?f=json` | Fetch results once status = `success` |

Use SQL for things the typed endpoints don't cover: DeFi protocol analytics, NFT marketplace data, bridge flows, MEV, entity resolution, labeled wallets, **Solana staking analytics**, and anything else in Allium's warehouse.

## Quick examples

### Wallet PnL (current)

```bash
curl -X POST "http