Intégration de l'API Octav
API pour le suivi de portefeuille de cryptomonnaies, l'historique des transactions et l'analyse DeFi.
Référence rapide
URL de base : https://api.octav.fi
Auth : Jeton Bearer dans l'en-tête Authorization
Limite de débit : 360 requêtes/minute/clé
Tarification : Basée sur les crédits (0,02-0,025 $/crédit)
Portail développeur : https://data.octav.fi
Authentification
curl -X GET "https://api.octav.fi/v1/credits" \
-H "Authorization: Bearer VOTRE_CLE_API"
Stockez la clé API dans la variable d'environnement OCTAV_API_KEY. Ne la codez jamais en dur.
Méthodes d'accès
Par défaut, utilisez l'API REST avec clé API décrite ci-dessous. Elle couvre les 25 points de terminaison.
Octav expose également 5 points de terminaison via le protocole de paiement x402 à /v1/agent/{portfolio,wallet,nav,status,chains} — 0,025 USDC par appel sur Base, sans clé API. Utilisez x402 uniquement lorsque :
- l'utilisateur a explicitement demandé l'accès x402 ou le paiement par appel, ou
- l'agent dispose de son propre portefeuille financé et qu'aucune clé API n'est disponible.
Sinon, utilisez /v1/* avec un jeton Bearer, et mentionnez l'existence de x402 si l'un de ces cas s'applique. Ne commencez pas par x402 par défaut.
Il n'y a pas de /v1/agent/transactions — l'historique des transactions nécessite une clé API.
Aperçu des points de terminaison
| Point de terminaison | Méthode | Coût | Description |
|---|---|---|---|
/v1/portfolio | GET | 1 crédit | Holdings du portefeuille sur plusieurs chaînes/protocoles |
/v1/portfolio/at-block | GET | Ajout + 1 crédit | Portefeuille évalué à un bloc historique (Ethereum) |
/v1/virtual-users | GET | 1 crédit | Liste des utilisateurs virtuels (Pro) |
/v1/virtual-users/portfolio | GET | 1 crédit/adresse | Holdings des utilisateurs virtuels (Pro) |
/v1/nav | GET | 1 crédit | Valeur nette d'actif — {nav, currency, conversionPrice} |
/v1/wallet | GET | 1 crédit | Soldes des jetons du portefeuille, exclut les positions DeFi |
/v1/transactions | GET | 1 crédit | Historique des transactions avec filtrage |
/v1/approvals/{chain} | GET | 1 crédit | Enregistrements d'approbation de jetons ERC-20 |
/v1/token-overview | GET | 1 crédit | Répartition des jetons par protocole (PRO uniquement) |
/v1/airdrop | GET | 1 crédit | Airdrops réclamables (Solana uniquement) |
/v1/historical | GET | 1 crédit | Instantanés historiques du portefeuille |
/v1/sync-transactions | POST | 1+ crédits | Déclencher la synchronisation des transactions |
/v1/contract-protocol | GET | 5 crédits | Résoudre l'adresse du contrat en protocole DeFi (remboursé en cas de 404) |
/v1/beacon/validators/* | GET | Ajout | Détails, récompenses, retraits, dépôts des validateurs ETH |
/v1/chains | GET | Gratuit | Liste des réseaux blockchain pris en charge |
/v1/chains/{chainKey}/protocols | GET | Gratuit | Lister les protocoles sur une chaîne |
/v1/status | GET | Gratuit | Vérifier l'état de synchronisation |
/v1/credits | GET | Gratuit | Vérifier le solde de crédits |
L'abonnement Snapshot (POST, 1200 crédits) active les instantanés quotidiens du portefeuille pour une adresse, que /v1/historical lit ensuite.
Points de terminaison x402 (pas de clé API — voir Méthodes d'accès ci-dessus)
| Point de terminaison | Méthode | Coût | Description |
|---|---|---|---|
/v1/agent/portfolio | GET | 0,025 USDC | Holdings du portefeuille et des protocoles |
/v1/agent/wallet | GET | 0,025 USDC | Holdings du portefeuille uniquement |
/v1/agent/nav | GET | 0,025 USDC | Valeur nette d'actif — {nav, currency, conversionPrice} |
/v1/agent/status | GET | 0,025 USDC | État de synchronisation |
/v1/agent/chains | GET | 0,025 USDC | Chaînes prises en charge |
Une requête non payée renvoie le statut HTTP 402 avec un en-tête payment-required encodé en base64 contenant le défi de paiement (USDC sur Base, eip155:8453). Un client HTTP compatible x402 le règle et réessaie automatiquement.
Points de terminaison principaux
Portefeuille
Obtenez les holdings sur plusieurs portefeuilles et protocoles 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
Paramètres :
addresses(obligatoire) : Adresse EVM ou Solana. Séparez plusieurs adresses par des virgules dans une seule requête pour économiser des crédits.includeImages: Inclure les URL des images des actifs/protocoles (par défaut : false)includeExplorerUrls: Inclure les URL des explorateurs de blocs (par défaut : false)waitForSync: Attendre des données fraîches si obsolètes (par défaut : false)
Structure de la réponse :
{
"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 (Valeur Nette d'Actif)
Obtenez la valeur nette sous forme d'une valeur unique, éventuellement convertie dans une autre devise.
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 }
Paramètres :
addresses(obligatoire) : Adresse EVM ou Solanacurrency: Monnaie fiduciaireUSD(par défaut),EUR,CAD,AED,CHF,SGD; cryptoETH,SOL,cbBTC,EURC,BNBwaitForSync: Attendre des données fraîches si obsolètes (par défaut : false)
conversionPrice est le taux utilisé — pour le fiduciaire, le taux de change par rapport au dollar ; pour la crypto, le prix moyen pondéré en USD sur les portefeuilles interrogés.
Transactions
Interrogez l'historique des transactions avec filtrage.
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}` } }
);
Paramètres obligatoires :
addresses: Adresse(s) de portefeuillelimit: Résultats par page (1-250)offset: Décalage de pagination
Filtres optionnels :
sort:DESC(plus récent) ouASC(plus ancien)networks: Filtre de chaîne (ex.ethereum,arbitrum,base)txTypes: Filtre de type de transaction (ex.SWAP,DEPOSIT)protocols: Filtre de protocole (ex.uniswap_v3,aave_v3)hideSpam: Exclure le spam (par défaut : false)hideDust: Exclure les transactions de poussière (par défaut : false)startDate/endDate: Plage de dates ISO 8601, UTC, toutes deux inclusives.endDatearrondit à la fin de son jour calendaire (23:59:59Z), donc pour un seul jour, définissez les deux à la même date ; ne définissez jamaisendDateà minuit le lendemain (cela duplique la transaction limite)interactingAddresses: Filtrer par adresses en interaction (séparées par des virgules)tokenId: Filtrer par ID de jeton NFTinitialSearchText: Recherche en texte intégral dans les actifs
Réponse (tableau de transactions) :
[{
"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" }]
}]
Synchronisation des transactions
Déclenchez une synchronisation manuelle pour obtenir des données de transactions fraîches.
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...'] })
});
// Retourne : "Address is syncing" ou "Address already syncing"
Coût : 1 crédit + 1 crédit par 250 transactions indexées (première fois uniquement).
Statut (Gratuit)
Vérifiez l'état de synchronisation avant des opérations coûteuses.
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édits (Gratuit)
Vérifiez le solde de crédits restant.
const credits = await fetch('https://api.octav.fi/v1/credits', {
headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// Retourne : 19033 (nombre)
Portefeuille historique
Obtenez un instantané du portefeuille pour une date spécifique. Nécessite un abonnement.
const response = await fetch(
`https://api.octav.fi/v1/historical?addresses=${address}&date=2024-11-01`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
Aperçu des jetons (PRO uniquement)
Répartition détaillée des jetons par protocole.
const response = await fetch(
`https://api.octav.fi/v1/token-overview?addresses=${address}&date=2024-11-01`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
Types de transactions
Types courants pour le filtrage :
| Type | Description |
|---|---|
TRANSFERIN | Jetons reçus |
TRANSFEROUT | Jetons envoyés |
SWAP | Échange de jetons |
DEPOSIT | Dépôt DeFi |
WITHDRAW | Retrait DeFi |
STAKE | Jalonnement de jetons |
UNSTAKE | Désengagement de jetons |
CLAIM | Réclamations de récompenses |
ADDLIQUIDITY | Dépôt de liquidité LP |
REMOVELIQUIDITY | Retrait de liquidité LP |
BORROW | Emprunt sur protocole de prêt |
LEND | Approvisionnement sur protocole de prêt |
BRIDGEIN / BRIDGEOUT | Pont inter-chaînes |
APPROVAL | Approbation de jetons |
MINT | Frappe de NFT/jeton |
Chaînes prises en charge
Support complet (portefeuille + transactions) : ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain
Portefeuille uniquement : scroll, zksync (era), mantle, manta, fantom, cronos, celo, et 40+ autres
Utilisez les clés de chaîne dans le filtre networks : ?networks=ethereum,arbitrum,base
Gestion des erreurs
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');
}
Erreurs courantes :
401: Clé API invalide/manquante402: Crédits insuffisants403: Le point de terminaison nécessite un abonnement PRO429: Limite de débit dépassée (attendez et réessayez)404: Adresse non indexée (>100 000 transactions)
Optimisation des coûts
- Regroupez les adresses : séparez-les par des virgules dans une seule requête —
?addresses=0x123,0x456,0x789— pour économiser des crédits par rapport à un appel par adresse - Utilisez les points de terminaison gratuits :
/v1/status,/v1/credits,/v1/chainset/v1/chains/{chainKey}/protocolsne coûtent rien - Filtrez côté serveur : utilisez les paramètres
networks,txTypesplutôt que le filtrage côté client - Mettez en cache les résultats : Le portefeuille est mis en cache 1 minute, les transactions 10 minutes
- Vérifiez d'abord le statut : Évitez les synchronisations inutiles
Schémas courants
Portefeuille multi-adresses
const addresses = ['0x123...', '0x456...', '0x789...'];
const response = await fetch(
`https://api.octav.fi/v1/portfolio?addresses=${addresses.join(',')}`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
Récupération paginée des transactions
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;
}
Flux de travail de synchronisation intelligent
async function smartSync(address) {
// Vérifiez d'abord le statut (gratuit)
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;
}
Tarification
| Forfait | Crédits | Prix | Par crédit |
|---|---|---|---|
| Starter | 4 000 | 100 $ | 0,025 $ |
| Small Team | 100 000 | 2 500 $ | 0,025 $ |
| Intensive | 1 000 000 | 20 000 $ | 0,020 $ |
Les crédits n'expirent jamais. Indexation d'adresse pour la première fois : 1 crédit pour 250 transactions.
Ressources
- Portail développeur : https://data.octav.fi
- Documentation API : https://docs.octav.fi
- Référence complète des points de terminaison : http
…
[tronqué pour la traduction]