Communitygithub.com

Octav-Labs/octav-api-skill

集成Octav API,用于跨50+区块链网络的加密货币投资组合追踪、交易历史和DeFi分析。当需要构建以下应用时使用:(1) 跨链追踪钱包余额和净资产,(2) 查询带过滤和搜索的交易历史,(3) 监控DeFi协议仓位(Aave, Uniswap等),(4) 访问历史投资组合快照,(5) 分析代币分布和持仓,(6) 通过x402协议作为自主代理按请求付费。触发器包括:"Octav API", "crypto portfolio API", "blockchain portfolio tracking", "DeFi analytics API", "wallet balance API", "transaction history API", "multi-chain portfolio", "Octav x402"。

octav-api-skill 是什么?

该技能为AI代理(如Claude Code, Cursor, Codex等)提供完整的Octav API集成功能,用于加密货币投资组合追踪、交易历史查询和DeFi分析。它支持50多个区块链网络,包括Ethereum、Arbitrum、Base等主流链,提供全面支持(投资组合+交易)和仅投资组合支持两种模式。核心功能包括:通过单一请求批量查询多个钱包地址的投资组合、获取净资产价值(支持多种法定货币和加密货币转换)、过滤和分页查询交易历史、触发交易同步、检查同步状态以及监控信用额度。重点优化了成本:批量地址请求、使用免费端点、服务端过滤、结果缓存以及同步前检查状态。还支持x402支付协议,允许代理在无API密钥情况下通过USDC按请求付费(每个请求0.025 USDC),适用于独立钱包场景。错误处理清晰,包含重试逻辑和常见状态码指南(401密钥无效、402信用不足、403需PRO订阅、429限流、404未索引)。该技能专为需要自主追踪和管理加密货币投资组合的AI代理设计。

兼容平台~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令牌 速率限制: 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/portfolioGET1 信用点跨链/协议的投资组合持仓
/v1/portfolio/at-blockGET附加 + 1 信用点按历史区块估值的投资组合(Ethereum)
/v1/virtual-usersGET1 信用点列出虚拟用户(专业版)
/v1/virtual-users/portfolioGET1 信用点/地址虚拟用户持仓(专业版)
/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协议(未找到时退款)
/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支持的链

未支付的请求会返回带有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}&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...'] })
});
// 返回: "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;
}

定价

套餐信用点价格每信用点价格
Starter4,000$100$0.025
Small Team100,000$2,500$0.025
Intensive1,000,000$20,000$0.020

信用点永不过期。首次地址索引:每250笔交易1信用点。

资源

…

[已截断以进行翻译]

相关技能