Communitygithub.com

Octav-Labs/octav-api-skill

Integration mit der Octav-API für Krypto-Portfolio-Tracking, Transaktionshistorie und DeFi-Analysen über 50+ Blockchain-Netzwerke.

Was ist octav-api-skill?

Diese Fähigkeit ermöglicht KI-Agenten (z. B. Claude Code, Cursor, Codex) die Integration mit der Octav-API für umfassendes Kryptowährungs-Portfolio-Management. Sie unterstützt die Abfrage von Kontoständen, Transaktionshistorien, DeFi-Positionen (z. B. Aave, Uniswap) und historischen Portfolio-Schnappschüssen über 50 Blockchain-Netzwerke hinweg. Die API ist über einen REST-Endpunkt mit API-Key-Authentifizierung oder über das x402-Zahlungsprotokoll (Pay-per-Call, 0,025 USDC auf Base ohne API-Key) zugänglich. Die Fähigkeit enthält detaillierte Anleitungen, Codebeispiele (JavaScript/TypeScript), Parameter-Tabellen und Best Practices zur Kostenoptimierung und Fehlerbehandlung. Sie löst auf relevante Schlüsselwörter wie 'Octav API', 'Krypto-Portfolio-API' und 'DeFi-Analyse-API' aus und ist auf Deutsch lokalisiert.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Octav-API-Integration

API für Kryptowährungs-Portfolio-Tracking, Transaktionshistorie und DeFi-Analysen.

Kurzreferenz

Basis-URL: https://api.octav.fi
Authentifizierung: Bearer-Token im Authorization-Header
Rate-Limit: 360 Anfragen/Minute/Schlüssel
Preise: Guthabenbasiert (0,02–0,025 $/Guthabeneinheit)
Entwicklerportal: https://data.octav.fi

Authentifizierung

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

API-Schlüssel in der Umgebungsvariable OCTAV_API_KEY speichern. Niemals fest codieren.

Zugriffsmethoden

Standardmäßig die unten dokumentierte REST-API mit API-Key verwenden. Diese deckt alle 25 Endpunkte ab.

Octav bietet außerdem 5 Endpunkte über das x402-Zahlungsprotokoll unter /v1/agent/{portfolio,wallet,nav,status,chains} an — 0,025 USDC pro Aufruf auf Base, kein API-Key erforderlich. x402 nur verwenden, wenn:

  • der Benutzer explizit nach x402 oder Pay-per-Call-Zugriff gefragt hat, oder
  • der Agent über eine eigene finanzierte Wallet verfügt und kein API-Key verfügbar ist.

Andernfalls /v1/* mit einem Bearer-Token verwenden und auf x402 hinweisen, wenn einer dieser Fälle zutrifft. Nicht standardmäßig mit x402 beginnen.

Es gibt kein /v1/agent/transactions – die Transaktionshistorie erfordert einen API-Key.

Endpunktübersicht

EndpunktMethodeKostenBeschreibung
/v1/portfolioGET1 GuthabeneinheitPortfolio-Bestände über Ketten/Protokolle hinweg
/v1/portfolio/at-blockGETZusatz + 1 GuthabeneinheitPortfolio bewertet zu einem historischen Block (Ethereum)
/v1/virtual-usersGET1 GuthabeneinheitListe der virtuellen Benutzer (Pro)
/v1/virtual-users/portfolioGET1 Guthabeneinheit/AdresseBestände virtueller Benutzer (Pro)
/v1/navGET1 GuthabeneinheitNettoinventarwert – {nav, currency, conversionPrice}
/v1/walletGET1 GuthabeneinheitWallet-Token-Salden, ohne DeFi-Positionen
/v1/transactionsGET1 GuthabeneinheitTransaktionshistorie mit Filterung
/v1/approvals/{chain}GET1 GuthabeneinheitERC-20-Token-Genehmigungsdatensätze
/v1/token-overviewGET1 GuthabeneinheitToken-Aufschlüsselung nach Protokoll (nur PRO)
/v1/airdropGET1 GuthabeneinheitEinlösbare Airdrops (nur Solana)
/v1/historicalGET1 GuthabeneinheitHistorische Portfolio-Schnappschüsse
/v1/sync-transactionsPOST1+ GuthabeneinheitenTransaktionssynchronisierung auslösen
/v1/contract-protocolGET5 GuthabeneinheitenVertragsadresse in DeFi-Protokoll auflösen (bei 404 rückerstattet)
/v1/beacon/validators/*GETZusatzETH-Validator-Details, Belohnungen, Abhebungen, Einzahlungen
/v1/chainsGETKostenlosListe der unterstützten Blockchain-Netzwerke
/v1/chains/{chainKey}/protocolsGETKostenlosProtokolle auf einer Chain auflisten
/v1/statusGETKostenlosSynchronisierungsstatus prüfen
/v1/creditsGETKostenlosGuthabensaldo prüfen

Subscribe Snapshot (POST, 1200 Guthabeneinheiten) aktiviert tägliche Portfolio-Schnappschüsse für eine Adresse, die dann von /v1/historical gelesen werden.

x402-Endpunkte (kein API-Key – siehe Zugriffsmethoden oben)

EndpunktMethodeKostenBeschreibung
/v1/agent/portfolioGET0,025 USDCWallet- und Protokollbestände
/v1/agent/walletGET0,025 USDCNur Wallet-Bestände
/v1/agent/navGET0,025 USDCNettoinventarwert – {nav, currency, conversionPrice}
/v1/agent/statusGET0,025 USDCSynchronisierungsstatus
/v1/agent/chainsGET0,025 USDCUnterstützte Chains

Eine unbezahlte Anfrage gibt HTTP 402 mit einem base64-kodierten payment-required-Header zurück, der die Zahlungsaufforderung (USDC auf Base, eip155:8453) enthält. Ein x402-fähiger HTTP-Client begleicht diese und wiederholt den Vorgang automatisch.

Kernendpunkte

Portfolio

Bestände über Wallets und DeFi-Protokolle hinweg abrufen.

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

Parameter:

  • addresses (erforderlich): EVM- oder Solana-Adresse. Mehrere Adressen in einer Anfrage durch Komma getrennt, um Guthaben zu sparen.
  • includeImages: Asset-/Protokoll-Bild-URLs einbeziehen (Standard: false)
  • includeExplorerUrls: Block-Explorer-URLs einbeziehen (Standard: false)
  • waitForSync: Auf frische Daten warten, wenn veraltet (Standard: false)

Antwortstruktur:

{
  "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 (Nettoinventarwert)

Den Nettoinventarwert als einzelnen Wert abrufen, optional in eine andere Währung umgerechnet.

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 }

Parameter:

  • addresses (erforderlich): EVM- oder Solana-Adresse
  • currency: Fiat USD (Standard), EUR, CAD, AED, CHF, SGD; Krypto ETH, SOL, cbBTC, EURC, BNB
  • waitForSync: Auf frische Daten warten, wenn veraltet (Standard: false)

conversionPrice ist der verwendete Kurs – bei Fiat der Wechselkurs von USD; bei Krypto der gewichtete durchschnittliche USD-Preis über die abgefragten Wallets.

Transaktionen

Transaktionshistorie mit Filterung abfragen.

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

Erforderliche Parameter:

  • addresses: Wallet-Adresse(n)
  • limit: Ergebnisse pro Seite (1–250)
  • offset: Paginierungs-Offset

Optionale Filter:

  • sort: DESC (neueste) oder ASC (älteste)
  • networks: Chain-Filter (z. B. ethereum,arbitrum,base)
  • txTypes: Transaktionstyp-Filter (z. B. SWAP,DEPOSIT)
  • protocols: Protokoll-Filter (z. B. uniswap_v3,aave_v3)
  • hideSpam: Spam ausschließen (Standard: false)
  • hideDust: Staubtransaktionen ausschließen (Standard: false)
  • startDate/endDate: ISO 8601-Datumsbereich, UTC, beide inklusive. endDate rundet auf das Ende des Kalendertages auf (23:59:59Z). Für einen einzelnen Tag beide auf dasselbe Datum setzen; endDate niemals auf Mitternacht des nächsten Tages setzen (verdoppelt die Grenztransaktion)
  • interactingAddresses: Nach interagierenden Adressen filtern (durch Komma getrennt)
  • tokenId: Nach NFT-Token-ID filtern
  • initialSearchText: Volltextsuche in Assets

Antwort (Array von Transaktionen):

[{
  "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" }]
}]

Transaktionen synchronisieren

Manuelle Synchronisierung für frische Transaktionsdaten auslösen.

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...'] })
});
// Gibt zurück: "Address is syncing" oder "Address already syncing"

Kosten: 1 Guthabeneinheit + 1 Guthabeneinheit pro 250 indexierte Transaktionen (nur beim ersten Mal).

Status (Kostenlos)

Synchronisierungsstatus vor teuren Operationen prüfen.

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

Guthaben (Kostenlos)

Verbleibendes Guthaben prüfen.

const credits = await fetch('https://api.octav.fi/v1/credits', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// Gibt zurück: 19033 (Zahl)

Historisches Portfolio

Portfolio-Schnappschuss für ein bestimmtes Datum abrufen. Erfordert ein Abonnement.

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

Token-Übersicht (Nur PRO)

Detaillierte Token-Aufschlüsselung nach Protokoll.

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

Transaktionstypen

Häufige Typen zum Filtern:

TypBeschreibung
TRANSFERINToken empfangen
TRANSFEROUTToken gesendet
SWAPToken-Tausch
DEPOSITDeFi-Einzahlung
WITHDRAWDeFi-Auszahlung
STAKEToken staken
UNSTAKEToken unstaken
CLAIMBelohnungsansprüche
ADDLIQUIDITYLP-Einzahlung
REMOVELIQUIDITYLP-Auszahlung
BORROWKreditaufnahme über Lending-Protokoll
LENDKapitalbereitstellung über Lending-Protokoll
BRIDGEIN / BRIDGEOUTCross-Chain-Brücke
APPROVALToken-Genehmigung
MINTNFT-/Token-Minting

Unterstützte Chains

Vollständige Unterstützung (Portfolio + Transaktionen): ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain

Nur Portfolio: scroll, zksync (era), mantle, manta, fantom, cronos, celo und 40+ weitere

Chain-Keys im networks-Filter verwenden: ?networks=ethereum,arbitrum,base

Fehlerbehandlung

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-Fehler ${response.status}: ${error.message}`);
    }

    return response;
  }
  throw new Error('Maximale Anzahl von Wiederholungen überschritten');
}

Häufige Fehler:

  • 401: Ungültiger/fehlender API-Key
  • 402: Unzureichendes Guthaben
  • 403: Endpunkt erfordert PRO-Abonnement
  • 429: Rate-Limit überschritten (warten und wiederholen)
  • 404: Adresse nicht indexiert (> 100k Transaktionen)

Kostenoptimierung

  1. Adressen bündeln: durch Komma getrennt in einer Anfrage – ?addresses=0x123,0x456,0x789 – um Guthaben im Vergleich zu einzelnen Aufrufen zu sparen
  2. Kostenlose Endpunkte verwenden: /v1/status, /v1/credits, /v1/chains und /v1/chains/{chainKey}/protocols kosten nichts
  3. Serverseitig filtern: networks-, txTypes-Parameter verwenden statt clientseitigem Filtern
  4. Ergebnisse cachen: Portfolio 1 Minute gecached, Transaktionen 10 Minuten
  5. Zuerst Status prüfen: Unnötige Synchronisierungen vermeiden

Häufige Muster

Multi-Wallet-Portfolio

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

Paginierte Transaktionsabfrage

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

Intelligenter Synchronisierungs-Workflow

async function smartSync(address) {
  // Zuerst Status prüfen (kostenlos)
  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] })
    });
  }
}

TypeScript-Schnittstellen

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

Preise

PaketGuthabenPreisPro Guthabeneinheit
Starter4.000100 $0,025 $
Kleines Team100.0002.500 $0,025 $
Intensiv1.000.00020.000 $0,020 $

Guthaben verfällt nie. Erstmalige Adressindexierung: 1 Guthabeneinheit pro 250 Transaktionen.

Ressourcen

[gekürzt für die Übersetzung]

Verwandte Skills