Communitygithub.com

Octav-Labs/octav-api-skill

Octav APIと統合し、50以上のブロックチェーンネットワークにわたる暗号通貨ポートフォリオ追跡、取引履歴、DeFi分析を実現します。

octav-api-skill とは?

このスキルは、Octav APIを利用して、複数チェーンにわたるウォレット残高や純資産の追跡、取引履歴のフィルタリング・検索、AaveやUniswapなどのDeFiプロトコル上のポジション監視、過去のポートフォリオスナップショットへのアクセス、トークン分布と保有状況の分析を可能にします。クレジットベースの課金体系で、1リクエストあたり0.02~0.025ドルのコストがかかり、スターターパッケージは4,000クレジットで100ドルです。また、x402支払いプロトコルを介した従量課金制のアクセスもサポートしており、エージェントが自身の資金を持つウォレットを持ち、APIキーがない場合に使用できます。主要なエンドポイントには、ポートフォリオ取得、純資産価値(NAV)、取引履歴、同期トリガー、ステータス確認などがあり、レスポンスはJSON形式で返されます。エラー処理として、レート制限超過(429)時のリトライや、不正なAPIキー(401)、クレジット不足(402)などのハンドリングが実装されています。

対応~Claude Code~Codex CLI~Cursor
npx skills add Octav-Labs/octav-api-skill

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Octav API 統合

暗号通貨ポートフォリオ追跡、取引履歴、DeFi分析のためのAPI。

クイックリファレンス

ベースURL: https://api.octav.fi 認証: AuthorizationヘッダーのBearerトークン レート制限: 360リクエスト/分/キー 価格: クレジットベース($0.02-0.025/クレジット) 開発者ポータル: https://data.octav.fi

認証

curl -X GET "https://api.octav.fi/v1/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

APIキーは環境変数 OCTAV_API_KEY に保存してください。ハードコードは避けてください。

アクセス方法

デフォルトでは、以下に文書化されているAPIキーREST APIを使用してください。 25の全エンドポイントをカバーしています。

Octavはまた、x402支払いプロトコルを介して5つのエンドポイントを /v1/agent/{portfolio,wallet,nav,status,chains} で公開しています。Base上で1コールあたり0.025 USDC、APIキーは不要です。x402は以下の場合のみ使用してください。

  • ユーザーが明示的にx402または従量課金制アクセスを要求した場合、または
  • エージェントが自身の資金を持つウォレットを持ち、APIキーが利用できない場合。

それ以外の場合は、Bearerトークンを使用して /v1/* を使用し、上記のいずれかのケースに該当する場合にx402が存在することを言及してください。デフォルトではx402から開始しないでください。

/v1/agent/transactions はありません — 取引履歴にはAPIキーが必要です。

エンドポイント概要

エンドポイントメソッドコスト説明
/v1/portfolioGET1クレジットチェーン/プロトコル全体のポートフォリオ保有状況
/v1/portfolio/at-blockGETアドオン + 1クレジット過去のブロック時点のポートフォリオ評価額(Ethereum)
/v1/virtual-usersGET1クレジット仮想ユーザー一覧(Pro)
/v1/virtual-users/portfolioGET1クレジット/アドレス仮想ユーザーの保有状況(Pro)
/v1/navGET1クレジット純資産価値 — {nav, currency, conversionPrice}
/v1/walletGET1クレジットウォレットトークン残高(DeFiポジションは除く)
/v1/transactionsGET1クレジットフィルタリング可能な取引履歴
/v1/approvals/{chain}GET1クレジットERC-20トークン承認記録
/v1/token-overviewGET1クレジットプロトコル別トークン内訳(PROのみ)
/v1/airdropGET1クレジット請求可能なエアドロップ(Solanaのみ)
/v1/historicalGET1クレジット過去のポートフォリオスナップショット
/v1/sync-transactionsPOST1+クレジットトランザクション同期のトリガー
/v1/contract-protocolGET5クレジットコントラクトアドレスをDeFiプロトコルに解決(404の場合は返金)
/v1/beacon/validators/*GETアドオンETHバリデーター詳細、報酬、引き出し、デポジット
/v1/chainsGET無料サポートされているブロックチェーンネットワーク一覧
/v1/chains/{chainKey}/protocolsGET無料チェーン上のプロトコル一覧
/v1/statusGET無料同期ステータスの確認
/v1/creditsGET無料クレジット残高の確認

Subscribe Snapshot (POST, 1200クレジット) により、アドレスの毎日のポートフォリオスナップショットが有効になり、/v1/historical がそれを読み取ります。

x402エンドポイント(APIキー不要 — 上記のアクセス方法を参照)

エンドポイントメソッドコスト説明
/v1/agent/portfolioGET0.025 USDCウォレットおよびプロトコルの保有状況
/v1/agent/walletGET0.025 USDCウォレットの保有状況のみ
/v1/agent/navGET0.025 USDC純資産価値 — {nav, currency, conversionPrice}
/v1/agent/statusGET0.025 USDC同期ステータス
/v1/agent/chainsGET0.025 USDCサポートされているチェーン

未払いのリクエストは、支払いチャレンジを含むbase64エンコードされた payment-required ヘッダーとともにHTTP 402を返します(Base上のUSDC、eip155:8453)。x402対応のHTTPクライアントはそれを決済し、自動的に再試行します。

コアエンドポイント

ポートフォリオ

ウォレットとDeFiプロトコル全体の保有状況を取得します。

const response = await fetch(
  `https://api.octav.fi/v1/portfolio?addresses=${address}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const portfolio = await response.json();
// portfolio.networth, portfolio.assetByProtocols, portfolio.chains

パラメータ:

  • addresses (必須): EVMまたはSolanaアドレス。1つのリクエストで複数のアドレスをカンマ区切りで指定するとクレジットを節約できます。
  • includeImages: アセット/プロトコルの画像URLを含める(デフォルト: false)
  • includeExplorerUrls: ブロックエクスプローラーのURLを含める(デフォルト: false)
  • waitForSync: データが古い場合に新しいデータを待つ(デフォルト: false)

レスポンス構造:

{
  "address": "0x...",
  "networth": "45231.89",
  "assetByProtocols": {
    "wallet": { "key": "wallet", "name": "Wallet", "value": "12453.20", "assets": [...] },
    "aave_v3": { "key": "aave_v3", "name": "Aave V3", "value": "8934.12", "assets": [...] }
  },
  "chains": {
    "ethereum": { "value": "25123.45", "protocols": [...] },
    "arbitrum": { "value": "20108.44", "protocols": [...] }
  }
}

NAV(純資産価値)

純資産を単一の値として取得し、オプションで別の通貨に換算します。

const response = await fetch(
  `https://api.octav.fi/v1/nav?addresses=${address}&currency=USD`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { nav, currency, conversionPrice } = await response.json();
// { "nav": 1235564.43, "currency": "USD", "conversionPrice": 1 }

パラメータ:

  • addresses (必須): EVMまたはSolanaアドレス
  • currency: 法定通貨 USD(デフォルト)、EUR、CAD、AED、CHF、SGD; 暗号通貨 ETH、SOL、cbBTC、EURC、BNB
  • waitForSync: データが古い場合に新しいデータを待つ(デフォルト: false)

conversionPrice は使用されたレートです。法定通貨の場合はUSDからの為替レート、暗号通貨の場合は照会されたウォレット全体の加重平均USD価格です。

トランザクション

フィルタリングを使用して取引履歴を照会します。

const params = new URLSearchParams({
  addresses: '0x...',
  limit: '50',
  offset: '0',
  sort: 'DESC',
  hideSpam: 'true'
});

const response = await fetch(
  `https://api.octav.fi/v1/transactions?${params}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

必須パラメータ:

  • addresses: ウォレットアドレス
  • limit: ページあたりの結果数(1-250)
  • offset: ページネーションオフセット

オプションフィルター:

  • sort: DESC(新しい順)または ASC(古い順)
  • networks: チェーンフィルター(例: ethereum,arbitrum,base)
  • txTypes: トランザクションタイプフィルター(例: SWAP,DEPOSIT)
  • protocols: プロトコルフィルター(例: uniswap_v3,aave_v3)
  • hideSpam: スパムを除外(デフォルト: false)
  • hideDust: ダストトランザクションを除外(デフォルト: false)
  • startDate/endDate: ISO 8601の日付範囲、UTC、両端を含む。endDate はその暦日の終わり(23:59:59Z)に切り上げられるため、単一日の場合は両方に同じ日付を設定します。endDate を翌日の午前0時に設定しないでください(境界のトランザクションが重複します)。
  • interactingAddresses: 相互作用するアドレスでフィルター(カンマ区切り)
  • tokenId: NFTトークンIDでフィルター
  • initialSearchText: アセット内の全文検索

レスポンス(トランザクションの配列):

[{
  "hash": "0xa1b2c3...",
  "timestamp": "1699012800",
  "chain": { "key": "ethereum", "name": "Ethereum" },
  "type": "SWAP",
  "protocol": { "key": "uniswap_v3", "name": "Uniswap V3" },
  "fees": "0.002134",
  "feesFiat": "7.12",
  "assetsIn": [{ "symbol": "WETH", "amount": "1.5", "value": "4800.00" }],
  "assetsOut": [{ "symbol": "USDC", "amount": "4795.23", "value": "4795.23" }]
}]

トランザクション同期

最新のトランザクションデータを取得するために手動同期をトリガーします。

const response = await fetch('https://api.octav.fi/v1/sync-transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ addresses: ['0x...'] })
});
// Returns: "Address is syncing" or "Address already syncing"

コスト: 1クレジット + インデックスされた250トランザクションあたり1クレジット(初回のみ)。

ステータス(無料)

高コストな操作の前に同期ステータスを確認します。

const response = await fetch(
  `https://api.octav.fi/v1/status?addresses=${address}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const [status] = await response.json();
// status.portfolioLastSync, status.transactionsLastSync, status.syncInProgress

クレジット(無料)

残りのクレジット残高を確認します。

const credits = await fetch('https://api.octav.fi/v1/credits', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// Returns: 19033 (number)

過去のポートフォリオ

特定の日付のポートフォリオスナップショットを取得します。サブスクリプションが必要です。

const response = await fetch(
  `https://api.octav.fi/v1/historical?addresses=${address}&date=2024-11-01`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

トークン概要(PROのみ)

プロトコル別の詳細なトークン内訳。

const response = await fetch(
  `https://api.octav.fi/v1/token-overview?addresses=${address}&date=2024-11-01`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

トランザクションタイプ

フィルタリングに使用する一般的なタイプ:

タイプ説明
TRANSFERINトークンを受信
TRANSFEROUTトークンを送信
SWAPトークン交換
DEPOSITDeFiへの預け入れ
WITHDRAWDeFiからの引き出し
STAKEステーキング
UNSTAKEアンステーキング
CLAIM報酬の請求
ADDLIQUIDITYLPへの預け入れ
REMOVELIQUIDITYLPからの引き出し
BORROWレンディングプロトコルからの借入
LENDレンディングプロトコルへの貸付
BRIDGEIN / BRIDGEOUTクロスチェーンブリッジ
APPROVALトークン承認
MINTNFT/トークンのミント

サポートされているチェーン

フルサポート(ポートフォリオ + トランザクション): ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain

ポートフォリオのみ: scroll, zksync (era), mantle, manta, fantom, cronos, celo, および40以上

チェーンキーを networks フィルターで使用します: ?networks=ethereum,arbitrum,base

エラーハンドリング

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error ${response.status}: ${error.message}`);
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

一般的なエラー:

  • 401: APIキーが無効/見つかりません
  • 402: クレジットが不足しています
  • 403: エンドポイントにはPROサブスクリプションが必要です
  • 429: レート制限を超過しました(待ってから再試行)
  • 404: アドレスがインデックスされていません(10万トランザクション超)

コスト最適化

  1. アドレスをバッチ処理: 1つのリクエストでカンマ区切り — ?addresses=0x123,0x456,0x789 — にすると、個別に呼び出すよりもクレジットを節約できます
  2. 無料エンドポイントを使用: /v1/status、/v1/credits、/v1/chains、/v1/chains/{chainKey}/protocols は料金がかかりません
  3. サーバー側でフィルタリング: クライアント側でのフィルタリングではなく、networks、txTypes パラメータを使用
  4. 結果をキャッシュ: ポートフォリオは1分、トランザクションは10分間キャッシュされます
  5. 最初にステータスを確認: 不要な同期を避ける

一般的なパターン

マルチウォレットポートフォリオ

const addresses = ['0x123...', '0x456...', '0x789...'];
const response = await fetch(
  `https://api.octav.fi/v1/portfolio?addresses=${addresses.join(',')}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

ページネーションを使用したトランザクション取得

async function getAllTransactions(address) {
  const transactions = [];
  let offset = 0;
  const limit = 250;

  while (true) {
    const response = await fetch(
      `https://api.octav.fi/v1/transactions?addresses=${address}&limit=${limit}&offset=${offset}&sort=DESC`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const batch = await response.json();
    if (batch.length === 0) break;
    transactions.push(...batch);
    offset += batch.length;
    if (batch.length < limit) break;
  }

  return transactions;
}

スマート同期ワークフロー

async function smartSync(address) {
  // 最初にステータスを確認(無料)
  const [status] = await fetch(
    `https://api.octav.fi/v1/status?addresses=${address}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  ).then(r => r.json());

  const lastSync = new Date(status.transactionsLastSync);
  const minutesSinceSync = (Date.now() - lastSync) / 1000 / 60;

  if (minutesSinceSync > 10 && !status.syncInProgress) {
    await fetch('https://api.octav.fi/v1/sync-transactions', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ addresses: [address] })
    });
  }
}

TypeScriptインターフェース

interface Portfolio {
  address: string;
  networth: string;
  cashBalance: string;
  dailyIncome: string;
  dailyExpense: string;
  fees: string;
  feesFiat: string;
  lastUpdated: string;
  assetByProtocols: Record<string, Protocol>;
  chains: Record<string, Chain>;
}

interface Protocol {
  key: string;
  name: string;
  value: string;
  assets: Asset[];
}

interface Asset {
  balance: string;
  symbol: string;
  price: string;
  value: string;
  contractAddress?: string;
  chain?: string;
}

interface Transaction {
  hash: string;
  timestamp: string;
  chain: { key: string; name: string };
  from: string;
  to: string;
  type: string;
  protocol?: { key: string; name: string };
  value: string;
  valueFiat: string;
  fees: string;
  feesFiat: string;
  assetsIn: Asset[];
  assetsOut: Asset[];
  functionName?: string;
}

価格

パッケージクレジット価格1クレジットあたり
スターター4,000$100$0.025
スモールチーム100,000$2,500$0.025
インテンシブ1,000,000$20,000$0.020

クレジットは期限切れになりません。初回アドレスインデックス:250トランザクションあたり1クレジット。

リソース

…

[翻訳のため省略]

関連スキル