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/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 | 無料 | クレジット残高の確認 |
Subscribe Snapshot (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 | サポートされているチェーン |
未払いのリクエストは、支払いチャレンジを含む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}¤cy=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、BNBwaitForSync: データが古い場合に新しいデータを待つ(デフォルト: 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 | トークン交換 |
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つのリクエストでカンマ区切り —
?addresses=0x123,0x456,0x789— にすると、個別に呼び出すよりもクレジットを節約できます - 無料エンドポイントを使用:
/v1/status、/v1/credits、/v1/chains、/v1/chains/{chainKey}/protocolsは料金がかかりません - サーバー側でフィルタリング: クライアント側でのフィルタリングではなく、
networks、txTypesパラメータを使用 - 結果をキャッシュ: ポートフォリオは1分、トランザクションは10分間キャッシュされます
- 最初にステータスを確認: 不要な同期を避ける
一般的なパターン
マルチウォレットポートフォリオ
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クレジット。
リソース
- 開発者ポータル: https://data.octav.fi
- APIドキュメント: https://docs.octav.fi
- 全エンドポイントリファレンス: http...
…
[翻訳のため省略]