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支付协议在/v1/agent/{portfolio,wallet,nav,status,chains}暴露了5个端点——每次调用0.025 USDC,运行在Base上,无需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 信用点 | 列出虚拟用户(专业版) |
/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协议(未找到时退款) |
/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 | 支持的链 |
未支付的请求会返回带有base64编码payment-required头部(包含支付挑战)的HTTP 402状态码(USDC on Base,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}¤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代币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;
}
定价
| 套餐 | 信用点 | 价格 | 每信用点价格 |
|---|---|---|---|
| Starter | 4,000 | $100 | $0.025 |
| Small Team | 100,000 | $2,500 | $0.025 |
| Intensive | 1,000,000 | $20,000 | $0.020 |
信用点永不过期。首次地址索引:每250笔交易1信用点。
资源
- 开发者门户: https://data.octav.fi
- API文档: https://docs.octav.fi
- 完整端点参考: http
…
[已截断以进行翻译]