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
| Endpunkt | Methode | Kosten | Beschreibung |
|---|---|---|---|
/v1/portfolio | GET | 1 Guthabeneinheit | Portfolio-Bestände über Ketten/Protokolle hinweg |
/v1/portfolio/at-block | GET | Zusatz + 1 Guthabeneinheit | Portfolio bewertet zu einem historischen Block (Ethereum) |
/v1/virtual-users | GET | 1 Guthabeneinheit | Liste der virtuellen Benutzer (Pro) |
/v1/virtual-users/portfolio | GET | 1 Guthabeneinheit/Adresse | Bestände virtueller Benutzer (Pro) |
/v1/nav | GET | 1 Guthabeneinheit | Nettoinventarwert – {nav, currency, conversionPrice} |
/v1/wallet | GET | 1 Guthabeneinheit | Wallet-Token-Salden, ohne DeFi-Positionen |
/v1/transactions | GET | 1 Guthabeneinheit | Transaktionshistorie mit Filterung |
/v1/approvals/{chain} | GET | 1 Guthabeneinheit | ERC-20-Token-Genehmigungsdatensätze |
/v1/token-overview | GET | 1 Guthabeneinheit | Token-Aufschlüsselung nach Protokoll (nur PRO) |
/v1/airdrop | GET | 1 Guthabeneinheit | Einlösbare Airdrops (nur Solana) |
/v1/historical | GET | 1 Guthabeneinheit | Historische Portfolio-Schnappschüsse |
/v1/sync-transactions | POST | 1+ Guthabeneinheiten | Transaktionssynchronisierung auslösen |
/v1/contract-protocol | GET | 5 Guthabeneinheiten | Vertragsadresse in DeFi-Protokoll auflösen (bei 404 rückerstattet) |
/v1/beacon/validators/* | GET | Zusatz | ETH-Validator-Details, Belohnungen, Abhebungen, Einzahlungen |
/v1/chains | GET | Kostenlos | Liste der unterstützten Blockchain-Netzwerke |
/v1/chains/{chainKey}/protocols | GET | Kostenlos | Protokolle auf einer Chain auflisten |
/v1/status | GET | Kostenlos | Synchronisierungsstatus prüfen |
/v1/credits | GET | Kostenlos | Guthabensaldo 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)
| Endpunkt | Methode | Kosten | Beschreibung |
|---|---|---|---|
/v1/agent/portfolio | GET | 0,025 USDC | Wallet- und Protokollbestände |
/v1/agent/wallet | GET | 0,025 USDC | Nur Wallet-Bestände |
/v1/agent/nav | GET | 0,025 USDC | Nettoinventarwert – {nav, currency, conversionPrice} |
/v1/agent/status | GET | 0,025 USDC | Synchronisierungsstatus |
/v1/agent/chains | GET | 0,025 USDC | Unterstü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}¤cy=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-Adressecurrency: FiatUSD(Standard),EUR,CAD,AED,CHF,SGD; KryptoETH,SOL,cbBTC,EURC,BNBwaitForSync: 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) oderASC(ä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.endDaterundet auf das Ende des Kalendertages auf (23:59:59Z). Für einen einzelnen Tag beide auf dasselbe Datum setzen;endDateniemals auf Mitternacht des nächsten Tages setzen (verdoppelt die Grenztransaktion)interactingAddresses: Nach interagierenden Adressen filtern (durch Komma getrennt)tokenId: Nach NFT-Token-ID filterninitialSearchText: 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:
| Typ | Beschreibung |
|---|---|
TRANSFERIN | Token empfangen |
TRANSFEROUT | Token gesendet |
SWAP | Token-Tausch |
DEPOSIT | DeFi-Einzahlung |
WITHDRAW | DeFi-Auszahlung |
STAKE | Token staken |
UNSTAKE | Token unstaken |
CLAIM | Belohnungsansprüche |
ADDLIQUIDITY | LP-Einzahlung |
REMOVELIQUIDITY | LP-Auszahlung |
BORROW | Kreditaufnahme über Lending-Protokoll |
LEND | Kapitalbereitstellung über Lending-Protokoll |
BRIDGEIN / BRIDGEOUT | Cross-Chain-Brücke |
APPROVAL | Token-Genehmigung |
MINT | NFT-/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-Key402: Unzureichendes Guthaben403: Endpunkt erfordert PRO-Abonnement429: Rate-Limit überschritten (warten und wiederholen)404: Adresse nicht indexiert (> 100k Transaktionen)
Kostenoptimierung
- Adressen bündeln: durch Komma getrennt in einer Anfrage –
?addresses=0x123,0x456,0x789– um Guthaben im Vergleich zu einzelnen Aufrufen zu sparen - Kostenlose Endpunkte verwenden:
/v1/status,/v1/credits,/v1/chainsund/v1/chains/{chainKey}/protocolskosten nichts - Serverseitig filtern:
networks-,txTypes-Parameter verwenden statt clientseitigem Filtern - Ergebnisse cachen: Portfolio 1 Minute gecached, Transaktionen 10 Minuten
- 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
| Paket | Guthaben | Preis | Pro Guthabeneinheit |
|---|---|---|---|
| Starter | 4.000 | 100 $ | 0,025 $ |
| Kleines Team | 100.000 | 2.500 $ | 0,025 $ |
| Intensiv | 1.000.000 | 20.000 $ | 0,020 $ |
Guthaben verfällt nie. Erstmalige Adressindexierung: 1 Guthabeneinheit pro 250 Transaktionen.
Ressourcen
- Entwicklerportal: https://data.octav.fi
- API-Dokumentation: https://docs.octav.fi
- Vollständige Endpunktreferenz: http://…
[gekürzt für die Übersetzung]