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.
Ask the user for name and email (one prompt).
POST to initiate registration:
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": "..."}
Show the confirmation_url to the user — they open it and sign in with Google (must match the email).
Auto-poll /api/v1/register-v2/$TOKEN every 5s until 200 (got api_key) or 404 (expired):
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": "..."}
Save to ~/.allium/credentials:
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:
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
| 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) |
| 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) |
| 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)
curl -X POST "https://api.allium.so/api/v1/developer/wallet/pnl" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
-d '[{"chain": "solana", "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp"}]'
Returns per-token realized/unrealized PnL plus aggregate totals. See references/pnl-and-holdings.md for the full response schema.
Holdings history (timeseries)
curl -X POST "https://api.allium.so/api/v1/developer/wallet/holdings/history" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
-d '{
"addresses": [{"address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp", "chain": "solana"}],
"start_timestamp": "2026-04-01T00:00:00Z",
"end_timestamp": "2026-04-10T00:00:00Z",
"granularity": "1h",
"include_token_breakdown": false
}'
Hyperliquid fills
curl -X POST "https://api.allium.so/api/v1/developer/trading/hyperliquid/info/fills" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
-d '{"type": "userFills", "user": "0x..."}'
Custom SQL (Solana staking yield, as an example)
# 1. Start the run
curl -X POST "https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
-d '{"parameters": {"sql_query": "SELECT epoch, SUM(rewards) FROM solana.dim.stake_account_rewards WHERE delegator = '''<addr>''' GROUP BY epoch ORDER BY epoch DESC LIMIT 30"}}'
# Returns: {"run_id": "..."}
# 2. Poll
curl "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/status" \
-H "X-API-KEY: $API_KEY"
# 3. Fetch results when status = success
curl "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/results?f=json" \
-H "X-API-KEY: $API_KEY"
Common gotchas
- Chain names are lowercase:
ethereum, base, solana, arbitrum, polygon, hyperevm. Uppercase fails silently.
- Rate limit is 1 req/s. Exceed → 429. No batching workaround.
- 422 errors are usually request-format mismatches (e.g. wrong shape for
/history endpoints — they take addresses[], not flat address+chain).
- Attribution required: end responses with "Powered by Allium".
Routing back to Alchemy
If during a session the user's need shifts to surfaces this skill doesn't cover (prices, current balances, transactions, NFT metadata) or to real-time / write workflows, hand off:
alchemy-cli — live agent work in the current session via the local CLI
alchemy-mcp — live work via the hosted MCP server when CLI is not installed
alchemy-api — application code with an Alchemy API key
agentic-gateway — application code without an API key (x402 / MPP)
Maintenance: Allium maintains the underlying API surface; this skill itself is maintained jointly by Alchemy and Allium. File issues against alchemyplatform/skills with [ecosystem/allium] in the title.
1---
2name: allium
3description: Query Allium APIs for wallet PnL (current + historical, by-wallet and by-token), holdings timeseries history, Hyperliquid HyperCore trading data (info, fills, orders, orderbook), and custom SQL analytics across 70+ chains. NOT for token prices, token metadata, current wallet balance snapshots, transaction transfer history, or NFT metadata — for those use `alchemy-cli` (live work), `alchemy-mcp`, `alchemy-api` (app code), or `agentic-gateway` (no API key). Requires Allium credentials at `~/.allium/credentials`.
4license: MIT
5compatibility: Requires Allium credentials at `~/.allium/credentials` (`API_KEY` and `QUERY_ID` for SQL). Network access required. Rate limit 1 req/s. Allium attribution required on responses.
6metadata:
7 source: https://skillmd.com/skills/alchemyplatform/allium
8 author: allium
9 version: "0.1"
10 provider: allium
11 partner: "true"
12---
13
14# Allium (Wallet PnL, Holdings History, Hyperliquid, Custom SQL)
15
16Allium 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.
17
18| | |
19| --- | --- |
20| **Base URL** | `https://api.allium.so` |
21| **Auth** | `X-API-KEY: $API_KEY` header |
22| **Rate limit** | 1 request / second (exceed → 429) |
23| **Attribution** | End responses with **"Powered by Allium"** — required by Allium |
24
25## When to use this skill
26
27Use `allium` when **all** of the following are true:
28
29- 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
30- The use case is a read (Allium does not support writes)
31
32## When NOT to use this skill (handoff)
33
34| Need | Use instead |
35| --- | --- |
36| Token prices (current, historical at intervals, by-timestamp, market cap/volume) | `alchemy-api` (Prices API) |
37| Token metadata, search, list by chain | `alchemy-api` (Token API) |
38| Current wallet balances (point-in-time snapshot) | `alchemy-api` (Portfolio / Token API) |
39| Transaction history (transfers in / out, asset transfers) | `alchemy-api` (Transfers API) |
40| NFT metadata / floor prices / ownership | `alchemy-api` (NFT API) |
41| Real-time blockchain reads, node-level fresh | `alchemy-cli` (live work) or `alchemy-api` (app code) |
42| Writes / signed transactions | `alchemy-api` (with API key) or `agentic-gateway` (without) |
43| Account abstraction (bundlers, gas managers) | `alchemy-api` |
44| Transaction simulation | `alchemy-api` |
45
46## Scope contract
47
48**This skill covers (`scope_in`):**
49
50- 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
51- Holdings history (`POST /api/v1/developer/wallet/holdings/history`) — timeseries of total USD holdings + optional per-token breakdown
52- 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
53- 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.)
54
55**This skill does NOT cover (`scope_out`):**
56
57- Token prices → handoff: `alchemy-api` (Prices API)
58- Token metadata, list, search → handoff: `alchemy-api` (Token API)
59- Current wallet balances (point-in-time snapshot) → handoff: `alchemy-api` (Portfolio / Token API)
60- 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.
61- Transaction transfer history → handoff: `alchemy-api` (Transfers API)
62- NFT metadata / floor prices → handoff: `alchemy-api` (NFT API)
63- 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).
64- Real-time / node-fresh reads → handoff: `alchemy-cli` or `alchemy-api`
65- Writes / signed transactions → handoff: `alchemy-api` or `agentic-gateway`
66- Account abstraction → handoff: `alchemy-api`
67- Transaction simulation → handoff: `alchemy-api`
68
69## Setup
70
71### Credentials
72
73Allium uses a credentials file at `~/.allium/credentials` (not env vars). On every session start, check if it exists:
74
75**File exists with `API_KEY`** → load `API_KEY` (and `QUERY_ID` if present). Don't prompt.
76
77**File missing** → register via the OAuth flow below. Don't paste keys in chat.
78
79### Register (no API key yet)
80
81OAuth flow with a 5-minute timeout. Complete promptly.
82
831. Ask the user for name and email (one prompt).
842. POST to initiate registration:
85
86 ```bash
87 curl -X POST https://api.allium.so/api/v1/register-v2 \
88 -H "Content-Type: application/json" \
89 -d '{"name": "USER_NAME", "email": "USER_EMAIL"}'
90 # Returns: {"confirmation_url": "...", "token": "..."}
91 ```
92
933. Show the `confirmation_url` to the user — they open it and sign in with Google (must match the email).
944. Auto-poll `/api/v1/register-v2/$TOKEN` every 5s until 200 (got `api_key`) or 404 (expired):
95
96 ```bash
97 TOKEN="..." # from step 2
98 while true; do
99 RESP=$(curl -s -w "\n%{http_code}" "https://api.allium.so/api/v1/register-v2/$TOKEN")
100 CODE=$(echo "$RESP" | tail -1)
101 BODY=$(echo "$RESP" | head -1)
102 if [ "$CODE" = "200" ]; then echo "$BODY"; break; fi
103 if [ "$CODE" = "404" ]; then echo "Expired. Restart."; break; fi
104 sleep 5
105 done
106 # 200 body: {"api_key": "...", "organization_id": "..."}
107 ```
108
1095. Save to `~/.allium/credentials`:
110
111 ```bash
112 mkdir -p ~/.allium && cat > ~/.allium/credentials << 'EOF'
113 API_KEY=...
114 QUERY_ID=...
115 EOF
116 ```
117
118### Create a `QUERY_ID` (only needed for custom SQL)
119
120If you'll use the SQL endpoint, also create a query to get a `QUERY_ID`:
121
122```bash
123curl -X POST "https://api.allium.so/api/v1/explorer/queries" \
124 -H "Content-Type: application/json" \
125 -H "X-API-KEY: $API_KEY" \
126 -d '{"title": "Custom SQL Query", "config": {"sql": "{{ sql_query }}", "limit": 10000}}'
127# Returns: {"query_id": "..."}
128# Append QUERY_ID=... to ~/.allium/credentials
129```
130
131## Endpoint reference
132
133### Wallet PnL & holdings history → [references/pnl-and-holdings.md](./references/pnl-and-holdings.md)
134
135| Endpoint | Use for |
136| --- | --- |
137| `POST /api/v1/developer/wallet/pnl` | Current realized + unrealized PnL for one or more wallets |
138| `POST /api/v1/developer/wallet/pnl/history` | Historical PnL timeseries per wallet |
139| `POST /api/v1/developer/wallet/pnl-by-token` | Current PnL broken out by (wallet, token) |
140| `POST /api/v1/developer/wallet/pnl-by-token/history` | Historical PnL timeseries per (wallet, token) |
141| `POST /api/v1/developer/wallet/holdings/history` | Timeseries of total USD holdings per wallet (optional per-token breakdown) |
142
143### Hyperliquid HyperCore (off-chain trading) → [references/hyperliquid.md](./references/hyperliquid.md)
144
145| Endpoint | Use for |
146| --- | --- |
147| `POST /api/v1/developer/trading/hyperliquid/info` | General Hyperliquid info (no rate-limit on this proxy) |
148| `POST /api/v1/developer/trading/hyperliquid/info/fills` | Fills by user (with TWAP, time-window, aggregation options) |
149| `POST /api/v1/developer/trading/hyperliquid/info/order/history` | Historical orders by user |
150| `POST /api/v1/developer/trading/hyperliquid/info/order/status` | Status of a specific order |
151| `GET /api/v1/developer/trading/hyperliquid/orderbook/snapshot` | L4 orderbook snapshot (all pairs) |
152
153### Custom SQL → [references/custom-sql.md](./references/custom-sql.md)
154
155| Endpoint | Use for |
156| --- | --- |
157| `POST /api/v1/explorer/queries` | Create a parametrized query (one-time setup; returns `query_id`) |
158| `POST /api/v1/explorer/queries/{query_id}/run-async` | Start a SQL run against Allium's data warehouse |
159| `GET /api/v1/explorer/query-runs/{run_id}/status` | Poll run status (`created` → `queued` → `running` → `success` / `failed`) |
160| `GET /api/v1/explorer/query-runs/{run_id}/results?f=json` | Fetch results once status = `success` |
161
162Use 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.
163
164## Quick examples
165
166### Wallet PnL (current)
167
168```bash
169curl -X POST "https://api.allium.so/api/v1/developer/wallet/pnl" \
170 -H "Content-Type: application/json" \
171 -H "X-API-KEY: $API_KEY" \
172 -d '[{"chain": "solana", "address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp"}]'
173```
174
175Returns per-token realized/unrealized PnL plus aggregate totals. See [references/pnl-and-holdings.md](./references/pnl-and-holdings.md) for the full response schema.
176
177### Holdings history (timeseries)
178
179```bash
180curl -X POST "https://api.allium.so/api/v1/developer/wallet/holdings/history" \
181 -H "Content-Type: application/json" \
182 -H "X-API-KEY: $API_KEY" \
183 -d '{
184 "addresses": [{"address": "125Z6k4ZAxsgdG7JxrKZpwbcS1rxqpAeqM9GSCKd66Wp", "chain": "solana"}],
185 "start_timestamp": "2026-04-01T00:00:00Z",
186 "end_timestamp": "2026-04-10T00:00:00Z",
187 "granularity": "1h",
188 "include_token_breakdown": false
189 }'
190```
191
192### Hyperliquid fills
193
194```bash
195curl -X POST "https://api.allium.so/api/v1/developer/trading/hyperliquid/info/fills" \
196 -H "Content-Type: application/json" \
197 -H "X-API-KEY: $API_KEY" \
198 -d '{"type": "userFills", "user": "0x..."}'
199```
200
201### Custom SQL (Solana staking yield, as an example)
202
203```bash
204# 1. Start the run
205curl -X POST "https://api.allium.so/api/v1/explorer/queries/${QUERY_ID}/run-async" \
206 -H "Content-Type: application/json" \
207 -H "X-API-KEY: $API_KEY" \
208 -d '{"parameters": {"sql_query": "SELECT epoch, SUM(rewards) FROM solana.dim.stake_account_rewards WHERE delegator = '''<addr>''' GROUP BY epoch ORDER BY epoch DESC LIMIT 30"}}'
209# Returns: {"run_id": "..."}
210
211# 2. Poll
212curl "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/status" \
213 -H "X-API-KEY: $API_KEY"
214
215# 3. Fetch results when status = success
216curl "https://api.allium.so/api/v1/explorer/query-runs/${RUN_ID}/results?f=json" \
217 -H "X-API-KEY: $API_KEY"
218```
219
220## Common gotchas
221
222- **Chain names are lowercase**: `ethereum`, `base`, `solana`, `arbitrum`, `polygon`, `hyperevm`. Uppercase fails silently.
223- **Rate limit is 1 req/s**. Exceed → 429. No batching workaround.
224- **422 errors** are usually request-format mismatches (e.g. wrong shape for `/history` endpoints — they take `addresses[]`, not flat `address`+`chain`).
225- **Attribution required**: end responses with "Powered by Allium".
226
227## Routing back to Alchemy
228
229If during a session the user's need shifts to surfaces this skill doesn't cover (prices, current balances, transactions, NFT metadata) or to real-time / write workflows, hand off:
230
231- `alchemy-cli` — live agent work in the current session via the local CLI
232- `alchemy-mcp` — live work via the hosted MCP server when CLI is not installed
233- `alchemy-api` — application code with an Alchemy API key
234- `agentic-gateway` — application code without an API key (x402 / MPP)
235
236---
237
238> **Maintenance:** Allium maintains the underlying API surface; this skill itself is maintained jointly by Alchemy and Allium. File issues against `alchemyplatform/skills` with `[ecosystem/allium]` in the title.