allium-onchain-data

Allium ブロックチェーンデータ

あなたの仕事： 迷わずオンチェーンデータを取得します。エンドポイントを間違えると、呼び出しが無駄になります。形式を間違えると、422 エラーになります。

ベース URL	https://api.allium.so
認証	X-API-KEY: {key} ヘッダー
レート制限	1 秒あたり 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. ユーザーに名前とメールアドレスを尋ねます（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 をユーザーに表示し、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 を読みます。ここには、サポート対象チェーンの確認方法、エラーコード、すべてのリアルタイムエンドポイントに共通する注意点が記載されています。

---

エンドポイントを選ぶ

選択を誤ると、API 呼び出しが無駄になります。タスクに合ったものを選んでください。

必要なもの	使用するエンドポイント	参照
現在の価格	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	エクスプローラー SQL（クエリの作成、実行、結果のポーリング）