allium-onchain-data

Allium 区块链数据

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

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

---

前提条件

• 已安装 curl 和 jq
• 拥有 Allium 账户 — 通过下方的 /register-v2 OAuth 流程注册（可使用免费层级）
• API 密钥已保存到 ~/.allium/credentials

---

凭据

每次会话开始时检查 ~/.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
chmod 600 ~/.allium/credentials  # restrict read access to current user only

注册（没有 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. 立即自动轮询 — 不要等待用户确认。显示网址后立即启动后台轮询循环：

# 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

---

步骤 0：检查支持的链（必需）

每个会话调用一次，以了解每个 /developer/ 端点支持哪些链。缓存结果 — 该结果适用于所有端点。Explorer SQL 和 Docs 端点除外。

curl "https://api.allium.so/api/v1/supported-chains/realtime-apis/simple"

返回 { "/api/v1/developer/prices": ["ethereum", "solana", ...], ... } — 一个将端点映射到所支持链的映射表。使用它来：

• 调用前验证链。链错误 = 静默返回空结果或报错。
• 查找支持用户所询链的端点。

---

选择正确的端点

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

你需要	使用此端点
支持的链	GET /api/v1/supported-chains/realtime-apis/simple
当前价格	POST /api/v1/developer/prices
指定时间戳的价格	POST /api/v1/developer/prices/at-timestamp
历史 OHLCV	POST /api/v1/developer/prices/history
代币统计数据	POST /api/v1/developer/prices/stats
按地址查询代币信息	POST /api/v1/developer/tokens/chain-address
列出代币	GET /api/v1/developer/tokens
搜索代币	GET /api/v1/developer/tokens/search
钱包余额	POST /api/v1/developer/wallet/balances
钱包余额历史	POST /api/v1/developer/wallet/balances/history
钱包交易	POST /api/v1/developer/wallet/transactions
钱包盈亏	POST /api/v1/developer/wallet/pnl
自定义 SQL	POST /api/v1/explorer/queries/{query_id}/run-async
浏览文档	GET /api/v1/docs/docs/browse
搜索架构	GET /api/v1/docs/schemas/search
浏览架构	GET /api/v1/docs/schemas/browse

---

常见代币

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

代币	链	地址
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\"}"

---

相关技能

• moonpay-check-wallet — 查询链上信息前，检查 MoonPay 钱包余额
• moonpay-swap-tokens — 通过兑换代币，根据查询结果采取行动
• moonpay-x402 — 通过 x402 微支付按请求付费使用 API