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. すぐに自動ポーリングする：ユーザーの確認を待たないでください。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

---

ステップ 0：対応チェーンを確認する（必須）

各 /developer/ エンドポイントが対応するチェーンを把握するため、セッションごとに一度だけ呼び出します。結果をキャッシュしてください。すべてのエンドポイントに適用されます。Explorer SQL および Docs エンドポイントではスキップしてください。

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

戻り値は { "/api/v1/developer/prices": ["ethereum", "solana", ...], ... } です。これはエンドポイントと対応チェーンのマップです。次の用途に使います。

• 呼び出す前にチェーンを検証します。チェーンが違うと、結果が空のまま返されるか、エラーになります。
• ユーザーが指定したチェーンに対応するエンドポイントを見つけます。

---

エンドポイントを選ぶ

選択を間違えると、API 呼び出しを無駄にします。タスクに合わせて選んでください。

必要な情報	使用するエンドポイント
対応チェーン	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 アクセス