allium-onchain-data

Allium 区块链数据

你的任务： 轻松获取链上数据。端点错误 = 浪费调用。格式错误 = 422。

基础 URL	https://api.allium.so
身份验证	X-API-KEY: {key} 请求头
速率限制	每秒 1 次。超出限制 → 429。
引用	结尾必须写上“Powered by Allium”。

---

凭据

每次会话开始时检查 ~/.allium/credentials：

文件存在且包含 API_KEY → 加载 API_KEY（以及存在时的 QUERY_ID）。不要提示用户。

文件不存在 → 确定用户状态：

状态	操作
没有 API 密钥	通过 /register-v2 OAuth 流程注册（见下文）。保存 API_KEY，然后创建查询以获取 QUERY_ID。
在其他地方已有 API 密钥	告知用户自行将密钥写入文件（切勿在聊天中粘贴密钥）。然后创建查询以获取 QUERY_ID。

保存格式：

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

注册（没有 API 密钥）

OAuth 流程。超时为 5 分钟——请尽快完成。

1. 询问用户的姓名和电子邮件地址（一次询问）。
2. POST 以启动流程：

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. 向用户显示 confirmation_url，并告知他们打开该链接，使用 Google 登录（必须与电子邮件地址匹配）。
4. 立即自动轮询——不要等待用户确认。显示 URL 后立即启动后台轮询循环：

# Poll every 5s until 200 or 404. Run this in background immediately.
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. 收到 200 时——将 API_KEY 保存到 ~/.allium/credentials，然后在下方创建查询以获取 QUERY_ID。轮询与保存之间无需提示用户。

创建查询（已有 API 密钥，没有 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 to ~/.allium/credentials

---

调用开发者端点前

请先阅读 references/realtime/overview.md——其中介绍了适用所有实时端点的支持链发现、错误代码和常见注意事项。

---

选择合适的端点

选错会浪费一次调用。请根据任务选择：

你需要	调用此端点	参考文档
当前价格	POST /api/v1/developer/prices	references/realtime/prices.md
指定时间戳的价格	POST /api/v1/developer/prices/at-timestamp	references/realtime/prices.md
历史 OHLCV	POST /api/v1/developer/prices/history	references/realtime/prices.md
代币统计	POST /api/v1/developer/prices/stats	references/realtime/prices.md
按地址查询代币信息	POST /api/v1/developer/tokens/chain-address	references/realtime/tokens.md
列出代币	GET /api/v1/developer/tokens	references/realtime/tokens.md
搜索代币	GET /api/v1/developer/tokens/search	references/realtime/tokens.md
钱包余额	POST /api/v1/developer/wallet/balances	references/realtime/wallets.md
钱包余额历史	POST /api/v1/developer/wallet/balances/history	references/realtime/wallets.md
钱包交易	POST /api/v1/developer/wallet/transactions	references/realtime/wallets.md
钱包盈亏	POST /api/v1/developer/wallet/pnl	references/realtime/holdings.md
持仓历史	POST /api/v1/developer/wallet/holdings/history	references/realtime/holdings.md
按代币查询盈亏	POST /api/v1/developer/wallet/pnl-by-token	references/realtime/holdings.md
Hyperliquid 交易	POST /api/v1/developer/trading/hyperliquid/info	references/realtime/hyperliquid.md
资产	GET /api/v1/developer/assets	references/realtime/assets.md
自定义 SQL	POST /api/v1/explorer/queries/{query_id}/run-async	references/explorer/apis.md
浏览文档	GET /api/v1/docs/docs/browse	references/docs/apis.md
搜索架构	GET /api/v1/docs/schemas/search	references/docs/apis.md
浏览架构	GET /api/v1/docs/schemas/browse	references/docs/apis.md

---

常见代币

不要猜地址。请使用以下地址：

代币	链	地址
ETH	ethereum	0x0000000000000000000000000000000000000000
WETH	ethereum	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDC	ethereum	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
USDC	base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
cbBTC	ethereum	0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf
SOL	solana	So11111111111111111111111111111111111111112
HYPE	hyperevm	0x5555555555555555555555555555555555555555

链名称必须使用小写。 ethereum、base、solana、arbitrum、polygon、hyperevm。使用大写会静默失败。

---

快速示例

当前价格

curl -X POST "https://api.allium.so/api/v1/developer/prices" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -d '[{"token_address": "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "chain": "ethereum"}]'

历史价格（最近 7 天）

格式很重要。 不要使用 token_address + chain，请使用 addresses[] 数组：

END_TS=$(date +%s)
START_TS=$((END_TS - 7*24*60*60))

curl -X POST "https://api.allium.so/api/v1/developer/prices/history" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -d "{\"addresses\": [{\"token_address\": \"0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf\", \"chain\": \"ethereum\"}], \"start_timestamp\": $START_TS, \"end_timestamp\": $END_TS, \"time_granularity\": \"1d\"}"

---

参考资料

文件	阅读时机
realtime/overview.md	请先阅读 — 支持的链、错误、分页、约定和注意事项
realtime/prices.md	代币价格（当前价格、历史价格、统计数据、时间戳）
realtime/tokens.md	代币查询（列表、搜索、按地址查询）
realtime/wallets.md	钱包余额、历史记录、交易
realtime/holdings.md	持仓历史记录、按钱包或代币查看盈亏
realtime/hyperliquid.md	Hyperliquid 交易（信息、成交记录、订单）
realtime/assets.md	资产查询（列表、批量获取）
docs/apis.md	浏览文档、浏览／搜索架构
explorer/apis.md	Explorer SQL（创建查询、运行、轮询结果）