octav-api

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 个端点——在 Base 上每次调用 0.025 USDC，无需 API 密钥。仅在以下情况使用 x402：

• 用户明确要求使用 x402 或按次付费访问，或
• Agent 拥有已注资的钱包，且没有可用的 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	免费	检查积分余额

订阅 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	受支持的链

未付款的请求会返回 HTTP 402，并在 base64 编码的 payment-required 标头中包含付款挑战（在 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-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...'] })
});
// 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——相比每个地址单独调用可节省额度
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