Communitygithub.com

Octav-Labs/octav-api-skill

整合 Octav API,用於加密貨幣投資組合追蹤、交易歷史查詢以及跨 50+ 區塊鏈網路的 DeFi 分析。

octav-api-skill 是什麼?

此技能提供與 Octav API 的完整整合,這是一個專門用於加密貨幣投資組合追蹤、交易歷史記錄和 DeFi 分析的資料服務。它支援所有主要的區塊鏈網路,包括 Ethereum、Arbitrum、Base、Solana、Polygon 等,使其成為需要監控多鏈資產持有量的開發者和 AI 代理的必備工具。主要功能包括擷取錢包和協議層級的投資組合餘額、查詢具有進階篩選功能的交易歷史、存取歷史投資組合快照、監控特定的 DeFi 協議部位 (如 Aave、Uniswap),以及分析代幣分配。此 API 使用基於積分制的付費模式,大部分端點每次呼叫花費 1 個積分,新地址索引另有不同的定價。該技能詳細說明了兩種存取方式:透過在 HTTP 標頭中傳遞 Bearer token 的標準 REST API,以及創新的 x402 支付協議,該協議允許代理在 Base 網路上按每次呼叫以 USDC 付費,而無需 API 金鑰。文件提供了全面的端點清單、請求範例、錯誤處理策略和成本最佳化技巧,涵蓋了 batch 地址處理和使用免費狀態端點等。它還包含了智慧同步工作流程和分頁查詢的常見模式,以及對所有操作強烈建議放入環境變數的安全 API 金鑰儲存。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add Octav-Labs/octav-api-skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Octav API 整合

用於加密貨幣投資組合追蹤、交易歷史和 DeFi 分析的 API。

快速參考

基礎 URL: https://api.octav.fi 身分驗證: Authorization 標頭中的 Bearer token 速率限制: 每分鐘 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-key REST API。 它涵蓋了所有 25 個端點。

Octav 也在 x402 支付協議 上公開了 5 個端點,位於 /v1/agent/{portfolio,wallet,nav,status,chains} — 在 Base 上每次呼叫 0.025 USDC,不需要 API 金鑰。僅在以下情況使用 x402:

  • 使用者明確要求 x402 或按次付費存取,或
  • 代理有自己的資助錢包且沒有可用的 API 金鑰。

否則,請使用帶有 Bearer token 的 /v1/*,如果符合上述任一情況,則提及 x402 的存在。預設不從 x402 開始。

沒有 /v1/agent/transactions — 交易歷史需要 API 金鑰。

端點概覽

端點方法費用描述
/v1/portfolioGET1 積分跨鏈/協議的投資組合持有量
/v1/portfolio/at-blockGET附加 + 1 積分以歷史區塊(以太坊)估值的投資組合
/v1/virtual-usersGET1 積分列出虛擬使用者(專業版)
/v1/virtual-users/portfolioGET每地址 1 積分虛擬使用者持有量(專業版)
/v1/navGET1 積分資產淨值 — {nav, currency, conversionPrice}
/v1/walletGET1 積分錢包代幣餘額,排除 DeFi 部位
/v1/transactionsGET1 積分具有篩選功能的交易歷史
/v1/approvals/{chain}GET1 積分ERC-20 代幣授權記錄
/v1/token-overviewGET1 積分按協議劃分的代幣細分(僅限專業版)
/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免費檢查積分餘額

訂閱快照(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支援的鏈

未支付的請求會回傳 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:包含資產/協議圖片網址(預設:false)
  • includeExplorerUrls:包含區塊瀏覽器網址(預設: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 設定為第二天的午夜(會重複邊界交易)
  • interactingAddresses:按互動地址過濾(逗號分隔)
  • tokenId:按 NFT token 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...'] })
});
// 回傳:"Address is syncing" 或 "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());
// 回傳:19033 (數字)

歷史投資組合

取得特定日期的投資組合快照。需要訂閱。

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

代幣概覽(僅限專業版)

按協議詳細劃分的代幣細分。

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領取獎勵
ADDLIQUIDITY流動性池存款
REMOVELIQUIDITY流動性池提款
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:端點需要專業版訂閱
  • 429:超出速率限制(請等待並重試)
  • 404:地址未索引(>100k 筆交易)

成本最佳化

  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;
}

定價

套裝積分價格每積分成本
入門版4,000$100$0.025
小型團隊100,000$2,500$0.025
密集型1,000,000$20,000$0.020

積分永不過期。首次地址索引:每 250 筆交易 1 積分。

資源

…

[為翻譯而截斷]

相關技能