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
| Endpoint | Método | Custo | Descrição |
|---|---|---|---|
/v1/portfolio | GET | 1 crédito | Holdings do portfólio entre cadeias/protocolos |
/v1/portfolio/at-block | GET | Adicional + 1 crédito | Portfólio avaliado em um bloco histórico (Ethereum) |
/v1/virtual-users | GET | 1 crédito | Listar usuários virtuais (Pro) |
/v1/virtual-users/portfolio | GET | 1 crédito/endereço | Holdings de usuário virtual (Pro) |
/v1/nav | GET | 1 crédito | Valor Patrimonial Líquido — {nav, currency, conversionPrice} |
/v1/wallet | GET | 1 crédito | Saldos de tokens da carteira, exclui posições DeFi |
/v1/transactions | GET | 1 crédito | Histórico de transações com filtragem |
/v1/approvals/{chain} | GET | 1 crédito | Registros de aprovação de tokens ERC-20 |
/v1/token-overview | GET | 1 crédito | Detalhamento de tokens por protocolo (apenas PRO) |
/v1/airdrop | GET | 1 crédito | Airdrops resgatáveis (apenas Solana) |
/v1/historical | GET | 1 crédito | Snapshots históricos do portfólio |
/v1/sync-transactions | POST | 1+ créditos | Gatilho para sincronização de transações |
/v1/contract-protocol | GET | 5 créditos | Resolver endereço de contrato para protocolo DeFi (reembolsado em 404) |
/v1/beacon/validators/* | GET | Adicional | Detalhes de validadores ETH, recompensas, saques, depósitos |
/v1/chains | GET | Gratuito | Listar redes blockchain suportadas |
/v1/chains/{chainKey}/protocols | GET | Gratuito | Listar protocolos em uma cadeia |
/v1/status | GET | Gratuito | Verificar status de sincronização |
/v1/credits | GET | Gratuito | Verificar 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)
| Endpoint | Método | Custo | Descrição |
|---|---|---|---|
/v1/agent/portfolio | GET | 0,025 USDC | Holdings de carteira e protocolos |
/v1/agent/wallet | GET | 0,025 USDC | Apenas holdings da carteira |
/v1/agent/nav | GET | 0,025 USDC | Valor Patrimonial Líquido — {nav, currency, conversionPrice} |
/v1/agent/status | GET | 0,025 USDC | Status de sincronização |
/v1/agent/chains | GET | 0,025 USDC | Cadeias 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}¤cy=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 Solanacurrency: Moeda fiduciáriaUSD(padrão),EUR,CAD,AED,CHF,SGD; criptoETH,SOL,cbBTC,EURC,BNBwaitForSync: 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) ouASC(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.endDatearredonda para o final do dia calendário (23:59:59Z), então para um único dia defina ambos para a mesma data; nunca definaendDatepara 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 NFTinitialSearchText: 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:
| Tipo | Descrição |
|---|---|
TRANSFERIN | Tokens recebidos |
TRANSFEROUT | Tokens enviados |
SWAP | Troca de tokens |
DEPOSIT | Depósito DeFi |
WITHDRAW | Saque DeFi |
STAKE | Staking de tokens |
UNSTAKE | Retirada de staking |
CLAIM | Reivindicação de recompensas |
ADDLIQUIDITY | Depósito de LP |
REMOVELIQUIDITY | Retirada de LP |
BORROW | Empréstimo em protocolo de lending |
LEND | Fornecimento em protocolo de lending |
BRIDGEIN / BRIDGEOUT | Ponte cross-chain |
APPROVAL | Aprovação de token |
MINT | Mint 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/ausente402: Créditos insuficientes403: Endpoint requer assinatura PRO429: Limite de taxa excedido (aguarde e tente novamente)404: Endereço não indexado (>100k transações)
Otimização de Custos
- 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 - Use endpoints gratuitos:
/v1/status,/v1/credits,/v1/chainse/v1/chains/{chainKey}/protocolsnão custam nada - Filtre no servidor: Use parâmetros
networks,txTypesem vez de filtrar no cliente - Armazene em cache: Portfólio em cache por 1 minuto, transações por 10 minutos
- 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
| Pacote | Créditos | Preço | 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 |
Os créditos nunca expiram. Indexação de endereço pela primeira vez: 1 crédito por 250 transações.
Recursos
- Portal do Desenvolvedor: https://data.octav.fi
- Documentação da API: https://docs.octav.fi
- Referência completa de endpoints: http
...
[truncado para tradução]