Communitygithub.com

Octav-Labs/octav-api-skill

Intégrer l'API Octav pour le suivi de portefeuille de cryptomonnaies, l'historique des transactions et l'analyse DeFi sur plus de 50 réseaux blockchain.

Qu'est-ce que octav-api-skill ?

Cette compétence permet aux agents IA et aux développeurs d'intégrer facilement l'API Octav pour accéder à des fonctionnalités complètes de suivi de portefeuille crypto, d'historique de transactions et d'analytique DeFi. Elle couvre plus de 50 réseaux blockchain, dont Ethereum, Arbitrum, Base, Solana et bien d'autres. Les utilisateurs peuvent récupérer les soldes de portefeuille, la valeur nette, les positions DeFi (Aave, Uniswap, etc.), les instantanés historiques et les détails des transactions avec filtrage avancé. La compétence prend en charge deux méthodes d'accès : l'API REST standard avec clé API Bearer et les points de terminaison x402 pour un modèle de paiement à la requête utilisant USDC sur Base, permettant aux agents autonomes de payer par appel sans clé API. Elle inclut également des conseils d'optimisation des coûts, comme le regroupement des adresses, l'utilisation des points de terminaison gratuits et la mise en cache des réponses pour minimiser la consommation de crédits.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 terminaisonMéthodeCoûtDescription
/v1/portfolioGET1 créditHoldings du portefeuille sur plusieurs chaînes/protocoles
/v1/portfolio/at-blockGETAjout + 1 créditPortefeuille évalué à un bloc historique (Ethereum)
/v1/virtual-usersGET1 créditListe des utilisateurs virtuels (Pro)
/v1/virtual-users/portfolioGET1 crédit/adresseHoldings des utilisateurs virtuels (Pro)
/v1/navGET1 créditValeur nette d'actif — {nav, currency, conversionPrice}
/v1/walletGET1 créditSoldes des jetons du portefeuille, exclut les positions DeFi
/v1/transactionsGET1 créditHistorique des transactions avec filtrage
/v1/approvals/{chain}GET1 créditEnregistrements d'approbation de jetons ERC-20
/v1/token-overviewGET1 créditRépartition des jetons par protocole (PRO uniquement)
/v1/airdropGET1 créditAirdrops réclamables (Solana uniquement)
/v1/historicalGET1 créditInstantanés historiques du portefeuille
/v1/sync-transactionsPOST1+ créditsDéclencher la synchronisation des transactions
/v1/contract-protocolGET5 créditsRésoudre l'adresse du contrat en protocole DeFi (remboursé en cas de 404)
/v1/beacon/validators/*GETAjoutDétails, récompenses, retraits, dépôts des validateurs ETH
/v1/chainsGETGratuitListe des réseaux blockchain pris en charge
/v1/chains/{chainKey}/protocolsGETGratuitLister les protocoles sur une chaîne
/v1/statusGETGratuitVérifier l'état de synchronisation
/v1/creditsGETGratuitVé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 terminaisonMéthodeCoûtDescription
/v1/agent/portfolioGET0,025 USDCHoldings du portefeuille et des protocoles
/v1/agent/walletGET0,025 USDCHoldings du portefeuille uniquement
/v1/agent/navGET0,025 USDCValeur nette d'actif — {nav, currency, conversionPrice}
/v1/agent/statusGET0,025 USDCÉtat de synchronisation
/v1/agent/chainsGET0,025 USDCChaî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}&currency=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 Solana
  • currency : Monnaie fiduciaire USD (par défaut), EUR, CAD, AED, CHF, SGD ; crypto ETH, SOL, cbBTC, EURC, BNB
  • waitForSync : 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 portefeuille
  • limit : Résultats par page (1-250)
  • offset : Décalage de pagination

Filtres optionnels :

  • sort : DESC (plus récent) ou ASC (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. endDate arrondit à 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 jamais endDate à 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 NFT
  • initialSearchText : 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 :

TypeDescription
TRANSFERINJetons reçus
TRANSFEROUTJetons envoyés
SWAPÉchange de jetons
DEPOSITDépôt DeFi
WITHDRAWRetrait DeFi
STAKEJalonnement de jetons
UNSTAKEDésengagement de jetons
CLAIMRéclamations de récompenses
ADDLIQUIDITYDépôt de liquidité LP
REMOVELIQUIDITYRetrait de liquidité LP
BORROWEmprunt sur protocole de prêt
LENDApprovisionnement sur protocole de prêt
BRIDGEIN / BRIDGEOUTPont inter-chaînes
APPROVALApprobation de jetons
MINTFrappe 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/manquante
  • 402 : Crédits insuffisants
  • 403 : Le point de terminaison nécessite un abonnement PRO
  • 429 : Limite de débit dépassée (attendez et réessayez)
  • 404 : Adresse non indexée (>100 000 transactions)

Optimisation des coûts

  1. 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
  2. Utilisez les points de terminaison gratuits : /v1/status, /v1/credits, /v1/chains et /v1/chains/{chainKey}/protocols ne coûtent rien
  3. Filtrez côté serveur : utilisez les paramètres networks, txTypes plutôt que le filtrage côté client
  4. Mettez en cache les résultats : Le portefeuille est mis en cache 1 minute, les transactions 10 minutes
  5. 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

ForfaitCréditsPrixPar crédit
Starter4 000100 $0,025 $
Small Team100 0002 500 $0,025 $
Intensive1 000 00020 000 $0,020 $

Les crédits n'expirent jamais. Indexation d'adresse pour la première fois : 1 crédit pour 250 transactions.

Ressources

…

[tronqué pour la traduction]

Skills associés