allium

Allium（ウォレットの損益、保有履歴、Hyperliquid、カスタム SQL）

Allium は、70 以上のチェーンにわたる、拡充された構造化ブロックチェーンデータを提供します。このスキルでは、ウォレットの損益、保有資産の時系列データ、Hyperliquid HyperCore の取引データ、カスタム SQL 分析を扱います。トークン価格、トークンメタデータ、現在のウォレット残高、トランザクションの送金、NFT メタデータには、代わりに該当する Alchemy スキルを使用してください。

ベース URL	https://api.allium.so
認証	X-API-KEY: $API_KEY ヘッダー
レート制限	1 リクエスト / 秒（超過すると → 429）
クレジット表記	レスポンスの末尾に "Powered by Allium" を付けてください — Allium の必須要件です

このスキルを使用する場合

以下の条件をすべて満たす場合は、allium を使用してください。

• ユーザーが求めているのが、次のいずれかであること：ウォレットの損益、保有履歴（時系列）、Hyperliquid HyperCore の取引データ（注文／約定／オーダーブック — HyperEVM のスマートコントラクトではありません）、または Allium のデータウェアハウスに対するカスタム SQL
• ユースケースが読み取りであること（Allium は書き込みをサポートしていません）

このスキルを使用しない場合（引き継ぎ先）

必要な機能	代わりに使用
トークン価格（現在、一定間隔の過去価格、タイムスタンプ指定、時価総額／取引高）	alchemy-api（Prices API）
トークンメタデータ、検索、チェーン別リスト	alchemy-api（Token API）
現在のウォレット残高（特定時点のスナップショット）	alchemy-api（Portfolio / Token API）
トランザクション履歴（送金の入出、資産の送金）	alchemy-api（Transfers API）
NFT メタデータ／フロア価格／所有権	alchemy-api（NFT API）
リアルタイムのブロックチェーン読み取り、最新のノードデータ	alchemy-cli（ライブ処理）または alchemy-api（アプリコード）
書き込み／署名済みトランザクション	alchemy-api（API キーあり）または agentic-gateway（API キーなし）
アカウント抽象化（バンドラー、ガスマネージャー）	alchemy-api
トランザクションのシミュレーション	alchemy-api

対応範囲の契約

このスキルの対応範囲（scope_in）：

• ウォレットの損益（POST /api/v1/developer/wallet/pnl、/wallet/pnl/history、/wallet/pnl-by-token、/wallet/pnl-by-token/history）— 実現損益と未実現損益の集計。現在と過去のデータに対応し、ウォレット別およびトークン別に取得できます
• 保有履歴（POST /api/v1/developer/wallet/holdings/history）— 合計 USD 保有額の時系列データと、オプションのトークン別内訳
• Hyperliquid HyperCore の取引データ（POST /api/v1/developer/trading/hyperliquid/...）— オフチェーンのマッチングエンジンから取得する情報、約定、注文履歴、注文ステータス、L4 オーダーブックのスナップショット
• カスタム SQL 分析（POST /api/v1/explorer/queries/{query_id}/run-async）— Allium のデータウェアハウスに対する任意の SQL クエリ（DeFi、NFT、ブリッジ、MEV、エンティティ解決、Solana ステーキングなど）

このスキルの対応範囲外（scope_out）：

• トークン価格 → 引き継ぎ先：alchemy-api（Prices API）
• トークンメタデータ、リスト、検索 → 引き継ぎ先：alchemy-api（Token API）
• 現在のウォレット残高（特定時点のスナップショット） → 引き継ぎ先：alchemy-api（Portfolio / Token API）
• 過去のウォレット残高（ブロックごと、または時系列） → 引き継ぎ先：alchemy-api のアーカイブ RPC（過去のブロックで eth_call balanceOf を実行）または alchemy_getAssetTransfers の結果から残高を算出します。どちらにも専用エンドポイントはありません。適切な方法は Alchemy のアーカイブノードです。
• トランザクションの送金履歴 → 引き継ぎ先：alchemy-api（Transfers API）
• NFT メタデータ／フロア価格 → 引き継ぎ先：alchemy-api（NFT API）
• HyperEVM スマートコントラクトの読み取り／書き込み／EVM RPC（チェーン ID 999） → 引き継ぎ先：https://hyperliquid-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY の alchemy-api または alchemy-cli。Allium は HyperCore（オフチェーン取引）を、Alchemy は HyperEVM（オンチェーンのスマートコントラクト）を扱います。
• リアルタイム／最新のノードデータの読み取り → 引き継ぎ先：alchemy-cli または alchemy-api
• 書き込み／署名済みトランザクション → 引き継ぎ先：alchemy-api または agentic-gateway
• アカウント抽象化 → 引き継ぎ先：alchemy-api
• トランザクションのシミュレーション → 引き継ぎ先：alchemy-api

セットアップ

認証情報

Allium は ~/.allium/credentials の認証情報ファイルを使用します（環境変数ではありません）。セッション開始時に、ファイルが存在するかどうかを必ず確認してください。

ファイルがあり、API_KEY が設定されている → API_KEY を読み込みます（QUERY_ID があれば、それも読み込みます）。ユーザーには尋ねません。

ファイルがない → 以下の OAuth フローで登録します。キーをチャットに貼り付けないでください。

登録（API キーがまだない場合）

タイムアウトは5分の OAuth フローです。速やかに完了してください。

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. /api/v1/register-v2/$TOKEN を5秒ごとに自動ポーリングし、200（api_key を取得）または404（期限切れ）になるまで続けます。

   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. ~/.allium/credentials に保存します。

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

QUERY_ID の作成（カスタム SQL に必要な場合のみ）

SQL エンドポイントを使用する場合は、クエリも作成して 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

エンドポイントのリファレンス

ウォレットの PnL と保有資産の履歴 → references/pnl-and-holdings.md

エンドポイント	用途
POST /api/v1/developer/wallet/pnl	1つ以上のウォレットの現在の実現損益と未実現損益
POST /api/v1/developer/wallet/pnl/history	ウォレットごとの過去の PnL 時系列データ
POST /api/v1/developer/wallet/pnl-by-token	（ウォレット、トークン）ごとの現在の PnL の内訳
POST /api/v1/developer/wallet/pnl-by-token/history	（ウォレット、トークン）ごとの過去の PnL 時系列データ
POST /api/v1/developer/wallet/holdings/history	ウォレットごとの USD 建て保有資産総額の時系列データ（トークンごとの内訳も任意で取得可能）

Hyperliquid HyperCore（オフチェーン取引） → references/hyperliquid.md

エンドポイント	用途
POST /api/v1/developer/trading/hyperliquid/info	Hyperliquid の一般情報（このプロキシにはレート制限がありません）
POST /api/v1/developer/trading/hyperliquid/info/fills	ユーザーごとの約定（TWAP、時間範囲、集計のオプションあり）
POST /api/v1/developer/trading/hyperliquid/info/order/history	ユーザーごとの過去の注文
POST /api/v1/developer/trading/hyperliquid/info/order/status	特定の注文のステータス
GET /api/v1/developer/trading/hyperliquid/orderbook/snapshot	L4 オーダーブックのスナップショット（全ペア）

カスタム SQL → references/custom-sql.md

エンドポイント	用途
POST /api/v1/explorer/queries	パラメーター化されたクエリを作成（一度だけのセットアップ。query_id を返します）
POST /api/v1/explorer/queries/{query_id}/run-async	Allium のデータウェアハウスに対する SQL 実行を開始
GET /api/v1/explorer/query-runs/{run_id}/status	実行ステータスをポーリング（created → queued → running → success / failed）
GET /api/v1/explorer/query-runs/{run_id}/results?f=json	ステータスが success になった後に結果を取得

型付きエンドポイントで対応できない内容には、SQL を使用してください。対象は DeFi プロトコル分析、NFT マーケットプレイスのデータ、ブリッジの資金フロー、MEV、エンティティ解決、ラベル付きウォレット、Solana のステーキング分析など、Allium のデータウェアハウスにあるあらゆるデータです。

簡単な例

ウォレットの PnL（現在）

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"}]'

トークンごとの実現損益／未実現損益と、集計合計を返します。完全なレスポンススキーマについては、references/pnl-and-holdings.md を参照してください。

保有資産の履歴（時系列）

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 の約定

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..."}'

カスタム SQL（例：Solana のステーキング利回り）

# 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"

よくある注意点

• チェーン名は小文字です：ethereum、base、solana、arbitrum、polygon、hyperevm。大文字にすると、エラーを返さずに失敗します。
• レート制限は1 req/sです。超過すると 429 が返されます。バッチ処理による回避策はありません。
• 422 エラーは通常、リクエスト形式の不一致が原因です（例：/history エンドポイントに誤った形式を指定している場合。address と chain を個別に渡すのではなく、addresses[] を受け取ります）。
• 帰属表示が必要です：レスポンスの末尾に「Powered by Allium」を記載してください。

Alchemy へのルーティング

セッション中にユーザーのニーズが、このスキルでカバーしていない領域（価格、現在の残高、トランザクション、NFT メタデータ）や、リアルタイム／書き込みワークフローに移った場合は、引き継いでください。

• alchemy-cli — ローカル CLI を使って現在のセッション内で行うライブなエージェント作業
• alchemy-mcp — CLI がインストールされていない場合に、ホスト型 MCP サーバーを介して行うライブ作業
• alchemy-api — Alchemy API キーを使ったアプリケーションコード
• agentic-gateway — API キーを使わないアプリケーションコード（x402 / MPP）

---

メンテナンス： 基盤となる API サーフェスは Allium がメンテナンスしています。このスキル自体は Alchemy と Allium が共同でメンテナンスしています。alchemyplatform/skills に、タイトルに [ecosystem/allium] を含めてイシューを登録してください。