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
| Endpoint | Método | Costo | Descripción |
|---|---|---|---|
/v1/portfolio | GET | 1 crédito | Tenencias de la cartera entre cadenas/protocolos |
/v1/portfolio/at-block | GET | Complemento + 1 crédito | Cartera valorada en un bloque histórico (Ethereum) |
/v1/virtual-users | GET | 1 crédito | Listar usuarios virtuales (Pro) |
/v1/virtual-users/portfolio | GET | 1 crédito/dirección | Tenencias de usuarios virtuales (Pro) |
/v1/nav | GET | 1 crédito | Valor Liquidativo Neto — {nav, currency, conversionPrice} |
/v1/wallet | GET | 1 crédito | Saldos de tokens de la billetera, excluye posiciones DeFi |
/v1/transactions | GET | 1 crédito | Historial de transacciones con filtrado |
/v1/approvals/{chain} | GET | 1 crédito | Registros de aprobación de tokens ERC-20 |
/v1/token-overview | GET | 1 crédito | Desglose de tokens por protocolo (solo PRO) |
/v1/airdrop | GET | 1 crédito | Airdrops reclamables (solo Solana) |
/v1/historical | GET | 1 crédito | Capturas de cartera históricas |
/v1/sync-transactions | POST | 1+ créditos | Activar sincronización de transacciones |
/v1/contract-protocol | GET | 5 créditos | Resolver dirección de contrato a protocolo DeFi (reembolsado en 404) |
/v1/beacon/validators/* | GET | Complemento | Detalles de validadores ETH, recompensas, retiros, depósitos |
/v1/chains | GET | Gratuito | Listar redes blockchain compatibles |
/v1/chains/{chainKey}/protocols | GET | Gratuito | Listar protocolos en una cadena |
/v1/status | GET | Gratuito | Verificar estado de sincronización |
/v1/credits | GET | Gratuito | Verificar 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)
| Endpoint | Método | Costo | Descripción |
|---|---|---|---|
/v1/agent/portfolio | GET | 0.025 USDC | Tenencias de billetera y protocolos |
/v1/agent/wallet | GET | 0.025 USDC | Solo tenencias de billetera |
/v1/agent/nav | GET | 0.025 USDC | Valor Liquidativo Neto — {nav, currency, conversionPrice} |
/v1/agent/status | GET | 0.025 USDC | Estado de sincronización |
/v1/agent/chains | GET | 0.025 USDC | Cadenas 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}¤cy=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 Solanacurrency: FiatUSD(por defecto),EUR,CAD,AED,CHF,SGD; criptoETH,SOL,cbBTC,EURC,BNBwaitForSync: 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 billeteralimit: Resultados por página (1-250)offset: Desplazamiento de paginación
Filtros opcionales:
sort:DESC(más reciente) oASC(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.endDateredondea 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 establezcasendDatea 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 NFTinitialSearchText: 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:
| Tipo | Descripción |
|---|---|
TRANSFERIN | Tokens recibidos |
TRANSFEROUT | Tokens enviados |
SWAP | Intercambio de tokens |
DEPOSIT | Depósito DeFi |
WITHDRAW | Retiro DeFi |
STAKE | Staking de tokens |
UNSTAKE | Retiro de staking |
CLAIM | Reclamo de recompensas |
ADDLIQUIDITY | Depósito de LP |
REMOVELIQUIDITY | Retiro de LP |
BORROW | Préstamo en protocolo de préstamos |
LEND | Suministro en protocolo de préstamos |
BRIDGEIN / BRIDGEOUT | Puente entre cadenas |
APPROVAL | Aprobación de tokens |
MINT | Acuñ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/faltante402: Créditos insuficientes403: El endpoint requiere suscripción PRO429: Límite de tasa excedido (esperar y reintentar)404: Dirección no indexada (>100k transacciones)
Optimización de Costos
- 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 - Usa endpoints gratuitos:
/v1/status,/v1/credits,/v1/chains, y/v1/chains/{chainKey}/protocolsno cuestan nada - Filtra en el servidor: Usa los parámetros
networks,txTypesen lugar de filtrar en el cliente - Cachea los resultados: La cartera se cachea 1 minuto, las transacciones 10 minutos
- 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
| Paquete | Créditos | Precio | Por Crédito |
|---|---|---|---|
| Starter | 4,000 | $100 | $0.025 |
| Small Team | 100,000 | $2,500 | $0.025 |
| Intensive | 1,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
- Portal para Desarrolladores: https://data.octav.fi
- Documentación de la API: https://docs.octav.fi
- Referencia completa de endpoints: http
…
[truncated for translation]