Communitygithub.com

Octav-Labs/octav-api-skill

Integración con la API de Octav para el seguimiento de carteras de criptomonedas, historial de transacciones y análisis DeFi en más de 50 redes blockchain.

¿Qué es octav-api-skill?

Esta habilidad permite a los agentes de IA conectarse a la API de Octav para acceder a datos completos de carteras de criptomonedas, seguimiento de transacciones y análisis de finanzas descentralizadas (DeFi) en más de 50 blockchains, incluyendo Ethereum, Arbitrum, Base, Solana, entre otras. El agente puede consultar saldos de carteras, valor neto, posiciones en protocolos DeFi (Aave, Uniswap), historial de transacciones con filtros avanzados y capturas de cartera históricas. Incluye soporte para el protocolo de pago por solicitud x402, permitiendo a agentes autónomos pagar por cada llamada con USDC en Base sin necesidad de una clave API. La API se autentica mediante un token Bearer y tiene un límite de 360 solicitudes por minuto por clave. Está diseñada para desarrolladores que construyen aplicaciones de análisis blockchain y agentes autónomos que necesitan monitorear posiciones cripto. Los costos se basan en créditos, con opciones de precios desde $100 por 4,000 créditos, y se recomienda optimizar el uso agrupando direcciones y utilizando endpoints gratuitos como `/v1/status` y `/v1/credits`.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Integración con la API de Octav

API para el seguimiento de carteras de criptomonedas, historial de transacciones y análisis DeFi.

Referencia Rápida

URL Base: https://api.octav.fi Autenticación: Token Bearer en el encabezado Authorization Límite de Tasa: 360 solicitudes/minuto/clave Precios: Basado en créditos ($0.02-0.025/crédito) Portal para Desarrolladores: https://data.octav.fi

Autenticación

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

Almacena la clave API en la variable de entorno OCTAV_API_KEY. Nunca la codifiques directamente.

Métodos de Acceso

Usa por defecto la API REST con clave API documentada a continuación. Cubre los 25 endpoints.

Octav también expone 5 endpoints a través del protocolo de pago x402 en /v1/agent/{portfolio,wallet,nav,status,chains} — 0.025 USDC por llamada en Base, sin necesidad de clave API. Usa x402 solo cuando:

  • el usuario haya solicitado explícitamente el acceso x402 o de pago por llamada, o
  • el agente tenga su propia billetera financiada y no haya una clave API disponible.

De lo contrario, usa /v1/* con un token Bearer, y menciona que x402 existe si se aplica uno de esos casos. No empieces con x402 por defecto.

No existe /v1/agent/transactions — el historial de transacciones requiere una clave API.

Resumen de Endpoints

EndpointMétodoCostoDescripción
/v1/portfolioGET1 créditoTenencias de la cartera entre cadenas/protocolos
/v1/portfolio/at-blockGETComplemento + 1 créditoCartera valorada en un bloque histórico (Ethereum)
/v1/virtual-usersGET1 créditoListar usuarios virtuales (Pro)
/v1/virtual-users/portfolioGET1 crédito/direcciónTenencias de usuarios virtuales (Pro)
/v1/navGET1 créditoValor Liquidativo Neto — {nav, currency, conversionPrice}
/v1/walletGET1 créditoSaldos de tokens de la billetera, excluye posiciones DeFi
/v1/transactionsGET1 créditoHistorial de transacciones con filtrado
/v1/approvals/{chain}GET1 créditoRegistros de aprobación de tokens ERC-20
/v1/token-overviewGET1 créditoDesglose de tokens por protocolo (solo PRO)
/v1/airdropGET1 créditoAirdrops reclamables (solo Solana)
/v1/historicalGET1 créditoCapturas de cartera históricas
/v1/sync-transactionsPOST1+ créditosActivar sincronización de transacciones
/v1/contract-protocolGET5 créditosResolver dirección de contrato a protocolo DeFi (reembolsado en 404)
/v1/beacon/validators/*GETComplementoDetalles de validadores ETH, recompensas, retiros, depósitos
/v1/chainsGETGratuitoListar redes blockchain compatibles
/v1/chains/{chainKey}/protocolsGETGratuitoListar protocolos en una cadena
/v1/statusGETGratuitoVerificar estado de sincronización
/v1/creditsGETGratuitoVerificar saldo de créditos

La Suscripción Snapshot (POST, 1200 créditos) habilita capturas diarias de cartera para una dirección, que luego /v1/historical lee.

Endpoints x402 (sin clave API — ver Métodos de Acceso arriba)

EndpointMétodoCostoDescripción
/v1/agent/portfolioGET0.025 USDCTenencias de billetera y protocolos
/v1/agent/walletGET0.025 USDCSolo tenencias de billetera
/v1/agent/navGET0.025 USDCValor Liquidativo Neto — {nav, currency, conversionPrice}
/v1/agent/statusGET0.025 USDCEstado de sincronización
/v1/agent/chainsGET0.025 USDCCadenas compatibles

Una solicitud no pagada devuelve HTTP 402 con un encabezado payment-required codificado en base64 que contiene el desafío de pago (USDC en Base, eip155:8453). Un cliente HTTP compatible con x402 lo resuelve y reintenta automáticamente.

Endpoints Principales

Cartera (Portfolio)

Obtén las tenencias en billeteras y 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 (obligatorio): Dirección EVM o Solana. Separa varias direcciones con comas en una sola solicitud para ahorrar créditos.
  • includeImages: Incluir URLs de imágenes de activos/protocolos (por defecto: false)
  • includeExplorerUrls: Incluir URLs de exploradores de bloques (por defecto: false)
  • waitForSync: Esperar datos frescos si están desactualizados (por defecto: false)

Estructura de la respuesta:

{
  "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 Liquidativo Neto)

Obtén el valor neto como un solo valor, opcionalmente convertido a otra moneda.

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 (obligatorio): Dirección EVM o Solana
  • currency: Fiat USD (por defecto), EUR, CAD, AED, CHF, SGD; cripto ETH, SOL, cbBTC, EURC, BNB
  • waitForSync: Esperar datos frescos si están desactualizados (por defecto: false)

conversionPrice es la tasa utilizada — para fiat, la tasa de cambio desde USD; para cripto, el precio USD promedio ponderado entre las billeteras consultadas.

Transacciones

Consulta el historial de transacciones con filtrado.

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 obligatorios:

  • addresses: Dirección(es) de billetera
  • limit: Resultados por página (1-250)
  • offset: Desplazamiento de paginación

Filtros opcionales:

  • sort: DESC (más reciente) o ASC (más antiguo)
  • networks: Filtro de cadena (ej., ethereum,arbitrum,base)
  • txTypes: Filtro de tipo de transacción (ej., SWAP,DEPOSIT)
  • protocols: Filtro de protocolo (ej., uniswap_v3,aave_v3)
  • hideSpam: Excluir spam (por defecto: false)
  • hideDust: Excluir transacciones de polvo (por defecto: false)
  • startDate/endDate: Rango de fechas ISO 8601, UTC, ambos inclusive. endDate redondea al final de su día calendario (23:59:59Z), por lo que para un solo día establece ambos a la misma fecha; nunca establezcas endDate a la medianoche del día siguiente (duplica la transacción límite)
  • interactingAddresses: Filtrar por direcciones que interactúan (separadas por comas)
  • tokenId: Filtrar por ID de token NFT
  • initialSearchText: Búsqueda de texto completo en activos

Respuesta (array de transacciones):

[{
  "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 Transacciones

Activar la sincronización manual para obtener datos de transacciones actualizados.

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

Costo: 1 crédito + 1 crédito por cada 250 transacciones indexadas (solo la primera vez).

Estado (Gratuito)

Verifica el estado de sincronización antes de operaciones costosas.

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)

Verifica el saldo restante de créditos.

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

Cartera Histórica

Obtén una captura de cartera para una fecha específica. Requiere suscripción.

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

Resumen de Tokens (Solo PRO)

Desglose detallado 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 Transacción

Tipos comunes para filtrar:

TipoDescripción
TRANSFERINTokens recibidos
TRANSFEROUTTokens enviados
SWAPIntercambio de tokens
DEPOSITDepósito DeFi
WITHDRAWRetiro DeFi
STAKEStaking de tokens
UNSTAKERetiro de staking
CLAIMReclamo de recompensas
ADDLIQUIDITYDepósito de LP
REMOVELIQUIDITYRetiro de LP
BORROWPréstamo en protocolo de préstamos
LENDSuministro en protocolo de préstamos
BRIDGEIN / BRIDGEOUTPuente entre cadenas
APPROVALAprobación de tokens
MINTAcuñación de NFT/token

Cadenas Compatibles

Soporte completo (cartera + transacciones): ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain

Solo cartera: scroll, zksync (era), mantle, manta, fantom, cronos, celo, y más de 40 más

Usa las claves de cadena en el filtro networks: ?networks=ethereum,arbitrum,base

Manejo de Errores

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

Errores comunes:

  • 401: Clave API inválida/faltante
  • 402: Créditos insuficientes
  • 403: El endpoint requiere suscripción PRO
  • 429: Límite de tasa excedido (esperar y reintentar)
  • 404: Dirección no indexada (>100k transacciones)

Optimización de Costos

  1. Agrupa direcciones: sepáralas con comas en una sola solicitud — ?addresses=0x123,0x456,0x789 — para ahorrar créditos en lugar de una llamada por cada una
  2. Usa endpoints gratuitos: /v1/status, /v1/credits, /v1/chains, y /v1/chains/{chainKey}/protocols no cuestan nada
  3. Filtra en el servidor: Usa los parámetros networks, txTypes en lugar de filtrar en el cliente
  4. Cachea los resultados: La cartera se cachea 1 minuto, las transacciones 10 minutos
  5. Verifica el estado primero: Evita sincronizaciones innecesarias

Patrones Comunes

Cartera de múltiples billeteras

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

Obtención paginada de transacciones

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

Flujo de sincronización inteligente

async function smartSync(address) {
  // Verificar estado primero (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;
}

Precios

PaqueteCréditosPrecioPor Crédito
Starter4,000$100$0.025
Small Team100,000$2,500$0.025
Intensive1,000,000$20,000$0.020

Los créditos nunca caducan. Indexación de direcciones por primera vez: 1 crédito por cada 250 transacciones.

Recursos

…

[truncated for translation]

Skills relacionados