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/portfolio | GET | 1 積分 | 跨鏈/協議的投資組合持有量 |
/v1/portfolio/at-block | GET | 附加 + 1 積分 | 以歷史區塊(以太坊)估值的投資組合 |
/v1/virtual-users | GET | 1 積分 | 列出虛擬使用者(專業版) |
/v1/virtual-users/portfolio | GET | 每地址 1 積分 | 虛擬使用者持有量(專業版) |
/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 積分 | 按協議劃分的代幣細分(僅限專業版) |
/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:包含資產/協議圖片網址(預設: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}¤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設定為第二天的午夜(會重複邊界交易)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 | 代幣交換 |
DEPOSIT | DeFi 存款 |
WITHDRAW | DeFi 提款 |
STAKE | 質押代幣 |
UNSTAKE | 取消質押代幣 |
CLAIM | 領取獎勵 |
ADDLIQUIDITY | 流動性池存款 |
REMOVELIQUIDITY | 流動性池提款 |
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:端點需要專業版訂閱429:超出速率限制(請等待並重試)404:地址未索引(>100k 筆交易)
成本最佳化
- 批次地址處理: 在一個請求中用逗號分隔它們 —
?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;
}
定價
| 套裝 | 積分 | 價格 | 每積分成本 |
|---|---|---|---|
| 入門版 | 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
…
[為翻譯而截斷]