octav-api

Octav API 統合

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

クイックリファレンス

ベース URL: https://api.octav.fi 認証: Authorization ヘッダーの Bearer トークン レート制限: キーごとに 360 リクエスト／分 料金: クレジット制（1 クレジットあたり $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 支払いプロトコルを介して /v1/agent/{portfolio,wallet,nav,status,chains} の 5 つのエンドポイントも提供しています。Base 上で 1 回あたり 0.025 USDC で、API キーは不要です。x402 を使用するのは、以下の場合に限ります。

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

それ以外の場合は Bearer トークンを使用して /v1/* を利用してください。上記のいずれかに該当する場合は、x402 が利用可能であることも伝えてください。デフォルトで x402 を使い始めないでください。

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

エンドポイント一覧

エンドポイント	メソッド	コスト	説明
/v1/portfolio	GET	1 クレジット	チェーン／プロトコルをまたいだポートフォリオ保有資産
/v1/portfolio/at-block	GET	アドオン + 1 クレジット	過去のブロック時点で評価したポートフォリオ（Ethereum）
/v1/virtual-users	GET	1 クレジット	仮想ユーザーの一覧（Pro）
/v1/virtual-users/portfolio	GET	1 クレジット／アドレス	仮想ユーザーの保有資産（Pro）
/v1/nav	GET	1 クレジット	純資産価値 — {nav, currency, conversionPrice}
/v1/wallet	GET	1 クレジット	ウォレットのトークン残高。DeFi ポジションは含まれません
/v1/transactions	GET	1 クレジット	絞り込みに対応した取引履歴
/v1/approvals/{chain}	GET	1 クレジット	ERC-20 トークンの承認記録
/v1/token-overview	GET	1 クレジット	プロトコル別のトークン内訳（PRO のみ）
/v1/airdrop	GET	1 クレジット	請求可能なエアドロップ（Solana のみ）
/v1/historical	GET	1 クレジット	過去のポートフォリオスナップショット
/v1/sync-transactions	POST	1 クレジット以上	取引の同期を開始
/v1/contract-protocol	GET	5 クレジット	コントラクトアドレスから DeFi プロトコルを特定（404 の場合は返金）
/v1/beacon/validators/*	GET	アドオン	ETH バリデーターの詳細、報酬、引き出し、入金
/v1/chains	GET	無料	対応するブロックチェーンネットワークの一覧
/v1/chains/{chainKey}/protocols	GET	無料	チェーン上のプロトコル一覧
/v1/status	GET	無料	同期状態を確認
/v1/credits	GET	無料	クレジット残高を確認

スナップショット登録（POST、1200 クレジット）を行うと、アドレスのポートフォリオスナップショットが毎日作成されます。/v1/historical はそのスナップショットを読み取ります。

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

エンドポイント	メソッド	コスト	説明
/v1/agent/portfolio	GET	0.025 USDC	ウォレットおよびプロトコルの保有資産
/v1/agent/wallet	GET	0.025 USDC	ウォレットの保有資産のみ
/v1/agent/nav	GET	0.025 USDC	純資産価値 — {nav, currency, conversionPrice}
/v1/agent/status	GET	0.025 USDC	同期状態
/v1/agent/chains	GET	0.025 USDC	対応チェーン

未払いのリクエストは HTTP 402 を返します。payment-required ヘッダーには、支払いチャレンジが base64 形式で含まれます（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 のアドレス。同一リクエストで複数のアドレスをカンマ区切りで指定すると、クレジットを節約できます。
• 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ページあたりの結果数（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）に切り上げられるため、1日分を指定する場合は両方に同じ日付を設定してください。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	トークン交換
DEPOSIT	DeFi への預け入れ
WITHDRAW	DeFi からの引き出し
STAKE	トークンのステーキング
UNSTAKE	トークンのステーキング解除
CLAIM	報酬の請求
ADDLIQUIDITY	LP への預け入れ
REMOVELIQUIDITY	LP からの引き出し
BORROW	レンディングプロトコルでの借り入れ
LEND	レンディングプロトコルへの供給
BRIDGEIN / BRIDGEOUT	クロスチェーンブリッジ
APPROVAL	トークンの承認
MINT	NFT／トークンのミント

対応チェーン

完全対応（ポートフォリオ + トランザクション）： 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) {
  // Check status first (free)
  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;
}

Pricing

Package	Credits	Price	Per Credit
Starter	4,000	$100	$0.025
Small Team	100,000	$2,500	$0.025
Intensive	1,000,000	$20,000	$0.020

Credits never expire. First-time address indexing: 1 credit per 250 transactions.

Resources

• Dev Portal: https://data.octav.fi
• API Docs: https://docs.octav.fi
• Full endpoint reference: https://docs.octav.fi/api/introduction
• Agent-readable docs (llms.txt): https://docs.octav.fi/llms.txt
• x402 agent endpoints: https://docs.octav.fi/api/endpoints/agent-x402
• Discord: https://discord.com/invite/qvcknAa73A
• Protocol List: https://protocols.octav.fi