Communitygithub.com

Octav-Labs/octav-api-skill

Integre com a API Octav para rastreamento de portfólio de criptomoedas, histórico de transações e análises DeFi em mais de 50 redes blockchain.

O que é octav-api-skill?

Esta skill permite que agentes de IA e aplicações se integrem à API Octav para gerenciar portfólios de criptomoedas, consultar históricos de transações e obter análises DeFi em mais de 50 blockchains. Ela suporta tanto autenticação por chave de API (padrão) quanto o protocolo de pagamento por chamada x402 (0,025 USDC por requisição, sem chave de API). As funcionalidades principais incluem: consultar saldos agregados de carteiras e protocolos DeFi (endpoint `/v1/portfolio`), obter valor patrimonial líquido (`/v1/nav`), listar transações com filtros avançados (`/v1/transactions`), verificar saldos de tokens e posições em protocolos como Aave e Uniswap, além de acessar snapshots históricos do portfólio. Ideal para desenvolvedores que precisam de dados on-chain atualizados para bots de trading, dashboards financeiros ou assistentes autônomos que operam no ecossistema cripto.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add Octav-Labs/octav-api-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Integração com a API Octav

API para rastreamento de portfólio de criptomoedas, histórico de transações e análises DeFi.

Referência Rápida

URL Base: https://api.octav.fi Autenticação: Token Bearer no cabeçalho Authorization Limite de Taxa: 360 requisições/minuto/chave Precificação: Baseado em créditos ($0,02-0,025/crédito) Portal do Desenvolvedor: https://data.octav.fi

Autenticação

curl -X GET "https://api.octav.fi/v1/credits" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Armazene a chave de API na variável de ambiente OCTAV_API_KEY. Nunca codifique diretamente.

Métodos de Acesso

Prefira a API REST com chave de API documentada abaixo. Ela cobre todos os 25 endpoints.

A Octav também expõe 5 endpoints através do protocolo de pagamento x402 em /v1/agent/{portfolio,wallet,nav,status,chains} — 0,025 USDC por chamada na Base, sem necessidade de chave de API. Use x402 apenas quando:

  • o usuário solicitou explicitamente acesso x402 ou pagamento por chamada, ou
  • o agente possui sua própria carteira financiada e nenhuma chave de API está disponível.

Caso contrário, use /v1/* com um token Bearer, e mencione que o x402 existe se um desses casos se aplicar. Não comece com x402 por padrão.

Não existe /v1/agent/transactions — o histórico de transações requer uma chave de API.

Visão Geral dos Endpoints

EndpointMétodoCustoDescrição
/v1/portfolioGET1 créditoHoldings do portfólio entre cadeias/protocolos
/v1/portfolio/at-blockGETAdicional + 1 créditoPortfólio avaliado em um bloco histórico (Ethereum)
/v1/virtual-usersGET1 créditoListar usuários virtuais (Pro)
/v1/virtual-users/portfolioGET1 crédito/endereçoHoldings de usuário virtual (Pro)
/v1/navGET1 créditoValor Patrimonial Líquido — {nav, currency, conversionPrice}
/v1/walletGET1 créditoSaldos de tokens da carteira, exclui posições DeFi
/v1/transactionsGET1 créditoHistórico de transações com filtragem
/v1/approvals/{chain}GET1 créditoRegistros de aprovação de tokens ERC-20
/v1/token-overviewGET1 créditoDetalhamento de tokens por protocolo (apenas PRO)
/v1/airdropGET1 créditoAirdrops resgatáveis (apenas Solana)
/v1/historicalGET1 créditoSnapshots históricos do portfólio
/v1/sync-transactionsPOST1+ créditosGatilho para sincronização de transações
/v1/contract-protocolGET5 créditosResolver endereço de contrato para protocolo DeFi (reembolsado em 404)
/v1/beacon/validators/*GETAdicionalDetalhes de validadores ETH, recompensas, saques, depósitos
/v1/chainsGETGratuitoListar redes blockchain suportadas
/v1/chains/{chainKey}/protocolsGETGratuitoListar protocolos em uma cadeia
/v1/statusGETGratuitoVerificar status de sincronização
/v1/creditsGETGratuitoVerificar saldo de créditos

O Snapshot de Inscrição (POST, 1200 créditos) habilita snapshots diários do portfólio para um endereço, que /v1/historical então lê.

Endpoints x402 (sem chave de API — veja Métodos de Acesso acima)

EndpointMétodoCustoDescrição
/v1/agent/portfolioGET0,025 USDCHoldings de carteira e protocolos
/v1/agent/walletGET0,025 USDCApenas holdings da carteira
/v1/agent/navGET0,025 USDCValor Patrimonial Líquido — {nav, currency, conversionPrice}
/v1/agent/statusGET0,025 USDCStatus de sincronização
/v1/agent/chainsGET0,025 USDCCadeias suportadas

Uma requisição não paga retorna HTTP 402 com um cabeçalho payment-required codificado em base64 contendo o desafio de pagamento (USDC na Base, eip155:8453). Um cliente HTTP compatível com x402 processa o pagamento e tenta novamente automaticamente.

Endpoints Principais

Portfólio

Obtenha holdings entre carteiras e protocolos 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

Parâmetros:

  • addresses (obrigatório): Endereço EVM ou Solana. Separe múltiplos endereços por vírgula em uma requisição para economizar créditos.
  • includeImages: Incluir URLs de imagens de ativos/protocolos (padrão: false)
  • includeExplorerUrls: Incluir URLs de exploradores de blocos (padrão: false)
  • waitForSync: Aguardar dados atualizados se desatualizados (padrão: false)

Estrutura da resposta:

{
  "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 (Valor Patrimonial Líquido)

Obtenha o patrimônio líquido como um valor único, opcionalmente convertido para outra moeda.

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 }

Parâmetros:

  • addresses (obrigatório): Endereço EVM ou Solana
  • currency: Moeda fiduciária USD (padrão), EUR, CAD, AED, CHF, SGD; cripto ETH, SOL, cbBTC, EURC, BNB
  • waitForSync: Aguardar dados atualizados se desatualizados (padrão: false)

conversionPrice é a taxa usada — para fiduciárias, a taxa de câmbio de USD; para cripto, o preço médio ponderado em USD nas carteiras consultadas.

Transações

Consulte o histórico de transações com filtragem.

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

Parâmetros obrigatórios:

  • addresses: Endereço(s) da(s) carteira(s)
  • limit: Resultados por página (1-250)
  • offset: Deslocamento da paginação

Filtros opcionais:

  • sort: DESC (mais recente) ou ASC (mais antigo)
  • networks: Filtro de cadeia (ex.: ethereum,arbitrum,base)
  • txTypes: Filtro de tipo de transação (ex.: SWAP,DEPOSIT)
  • protocols: Filtro de protocolo (ex.: uniswap_v3,aave_v3)
  • hideSpam: Excluir spam (padrão: false)
  • hideDust: Excluir transações de poeira (padrão: false)
  • startDate/endDate: Intervalo de datas ISO 8601, UTC, ambos inclusive. endDate arredonda para o final do dia calendário (23:59:59Z), então para um único dia defina ambos para a mesma data; nunca defina endDate para a meia-noite do dia seguinte (duplica a transação de fronteira)
  • interactingAddresses: Filtrar por endereços que interagem (separados por vírgula)
  • tokenId: Filtrar por ID de token NFT
  • initialSearchText: Pesquisa de texto completo nos ativos

Resposta (array de transações):

[{
  "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" }]
}]

Sincronizar Transações

Acione a sincronização manual para obter dados de transações atualizados.

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...'] })
});
// Retorna: "Address is syncing" ou "Address already syncing"

Custo: 1 crédito + 1 crédito por 250 transações indexadas (apenas na primeira vez).

Status (Gratuito)

Verifique o status de sincronização antes de operações caras.

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

Créditos (Gratuito)

Verifique o saldo de créditos restante.

const credits = await fetch('https://api.octav.fi/v1/credits', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// Retorna: 19033 (número)

Portfólio Histórico

Obtenha um snapshot do portfólio para uma data específica. Requer assinatura.

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

Visão Geral de Tokens (Apenas PRO)

Detalhamento de tokens por protocolo.

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

Tipos de Transação

Tipos comuns para filtragem:

TipoDescrição
TRANSFERINTokens recebidos
TRANSFEROUTTokens enviados
SWAPTroca de tokens
DEPOSITDepósito DeFi
WITHDRAWSaque DeFi
STAKEStaking de tokens
UNSTAKERetirada de staking
CLAIMReivindicação de recompensas
ADDLIQUIDITYDepósito de LP
REMOVELIQUIDITYRetirada de LP
BORROWEmpréstimo em protocolo de lending
LENDFornecimento em protocolo de lending
BRIDGEIN / BRIDGEOUTPonte cross-chain
APPROVALAprovação de token
MINTMint de NFT/token

Cadeias Suportadas

Suporte completo (portfólio + transações): ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain

Apenas portfólio: scroll, zksync (era), mantle, manta, fantom, cronos, celo e mais de 40 outras

Use as chaves das cadeias no filtro networks: ?networks=ethereum,arbitrum,base

Tratamento de Erros

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(`Erro de API ${response.status}: ${error.message}`);
    }

    return response;
  }
  throw new Error('Número máximo de tentativas excedido');
}

Erros comuns:

  • 401: Chave de API inválida/ausente
  • 402: Créditos insuficientes
  • 403: Endpoint requer assinatura PRO
  • 429: Limite de taxa excedido (aguarde e tente novamente)
  • 404: Endereço não indexado (>100k transações)

Otimização de Custos

  1. Agrupe endereços: separe-os por vírgula em uma requisição — ?addresses=0x123,0x456,0x789 — para economizar créditos em vez de uma chamada cada
  2. Use endpoints gratuitos: /v1/status, /v1/credits, /v1/chains e /v1/chains/{chainKey}/protocols não custam nada
  3. Filtre no servidor: Use parâmetros networks, txTypes em vez de filtrar no cliente
  4. Armazene em cache: Portfólio em cache por 1 minuto, transações por 10 minutos
  5. Verifique o status primeiro: Evite sincronizações desnecessárias

Padrões Comuns

Portfólio multi-carteira

const addresses = ['0x123...', '0x456...', '0x789...'];
const response = await fetch(
  `https://api.octav.fi/v1/portfolio?addresses=${addresses.join(',')}`,
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);

Busca paginada de transações

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

Fluxo de sincronização inteligente

async function smartSync(address) {
  // Verifique o status primeiro (gratuito)
  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] })
    });
  }
}

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

Precificação

PacoteCréditosPreçoPor Crédito
Starter4.000$100$0,025
Small Team100.000$2.500$0,025
Intensive1.000.000$20.000$0,020

Os créditos nunca expiram. Indexação de endereço pela primeira vez: 1 crédito por 250 transações.

Recursos

...

[truncado para tradução]

Habilidades Relacionadas