Octav API 통합
암호화폐 포트폴리오 추적, 거래 내역 조회, DeFi 분석을 위한 API입니다.
빠른 참조
기본 URL: https://api.octav.fi
인증: Authorization 헤더의 Bearer 토큰
속도 제한: 360회 요청/분/키
가격: 크레딧 기반 ($0.02-0.025/크레딧)
개발자 포털: https://data.octav.fi
인증
curl -X GET "https://api.octav.fi/v1/credits" \
-H "Authorization: Bearer YOUR_API_KEY"
API 키는 환경 변수 OCTAV_API_KEY에 저장하세요. 하드코딩하지 마십시오.
접근 방법
기본적으로 아래 문서화된 API 키 기반 REST API를 사용하세요. 모든 25개 엔드포인트를 다룹니다.
Octav는 또한 /v1/agent/{portfolio,wallet,nav,status,chains} 에서 x402 결제 프로토콜을 통해 5개의 엔드포인트를 제공합니다. — Base 네트워크에서 호출당 0.025 USDC, API 키 불필요. x402는 다음 경우에만 사용하세요:
- 사용자가 명시적으로 x402 또는 요청당 지불 접근을 요청한 경우, 또는
- 에이전트가 자체 자금 지갑을 보유하고 API 키를 사용할 수 없는 경우.
그 외에는 Bearer 토큰과 함께 /v1/*를 사용하고, 위 경우 중 하나에 해당하면 x402가 존재한다고 언급하세요. 기본적으로 x402부터 시작하지 마십시오.
/v1/agent/transactions는 존재하지 않습니다. — 거래 내역 조회에는 API 키가 필요합니다.
엔드포인트 개요
| 엔드포인트 | 메서드 | 비용 | 설명 |
|---|---|---|---|
/v1/portfolio | GET | 1 크레딧 | 체인/프로토콜별 포트폴리오 보유 자산 |
/v1/portfolio/at-block | GET | 추가 + 1 크레딧 | 특정 과거 블록(Ethereum) 기준 포트폴리오 가치 평가 |
/v1/virtual-users | GET | 1 크레딧 | 가상 사용자 목록 (Pro) |
/v1/virtual-users/portfolio | GET | 주소당 1 크레딧 | 가상 사용자 보유 자산 (Pro) |
/v1/nav | GET | 1 크레딧 | 순자산 가치 — {nav, currency, conversionPrice} |
/v1/wallet | GET | 1 크레딧 | 지갑 토큰 잔액 (DeFi 포지션 제외) |
/v1/transactions | GET | 1 크레딧 | 필터링 가능한 거래 내역 |
/v1/approvals/{chain} | GET | 1 크레딧 | ERC-20 토큰 승인 기록 |
/v1/token-overview | GET | 1 크레딧 | 프로토콜별 토큰 분류 (PRO 전용) |
/v1/airdrop | GET | 1 크레딧 | 클레임 가능한 에어드랍 (Solana 전용) |
/v1/historical | GET | 1 크레딧 | 과거 포트폴리오 스냅샷 |
/v1/sync-transactions | POST | 1+ 크레딧 | 거래 동기화 트리거 |
/v1/contract-protocol | GET | 5 크레딧 | 컨트랙트 주소를 DeFi 프로토콜로 확인 (404 시 환불) |
/v1/beacon/validators/* | GET | 추가 | ETH 검증인 상세 정보, 보상, 출금, 입금 |
/v1/chains | GET | 무료 | 지원되는 블록체인 네트워크 목록 |
/v1/chains/{chainKey}/protocols | GET | 무료 | 체인의 프로토콜 목록 |
/v1/status | GET | 무료 | 동기화 상태 확인 |
/v1/credits | GET | 무료 | 크레딧 잔액 확인 |
구독 스냅샷 (POST, 1200 크레딧)은 주소에 대한 일일 포트폴리오 스냅샷을 활성화하며, /v1/historical이 이를 읽습니다.
x402 엔드포인트 (API 키 불필요 — 위 접근 방법 참조)
| 엔드포인트 | 메서드 | 비용 | 설명 |
|---|---|---|---|
/v1/agent/portfolio | GET | 0.025 USDC | 지갑 및 프로토콜 자산 |
/v1/agent/wallet | GET | 0.025 USDC | 지갑 자산만 |
/v1/agent/nav | GET | 0.025 USDC | 순자산 가치 — {nav, currency, conversionPrice} |
/v1/agent/status | GET | 0.025 USDC | 동기화 상태 |
/v1/agent/chains | GET | 0.025 USDC | 지원 체인 |
미결제 요청은 HTTP 402와 함께 결제 챌린지(USDC on Base, eip155:8453)를 포함하는 base64 인코딩 payment-required 헤더를 반환합니다. x402를 지원하는 HTTP 클라이언트는 이를 처리하고 자동으로 재시도합니다.
핵심 엔드포인트
포트폴리오 (Portfolio)
지갑 및 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
파라미터:
addresses(필수): EVM 또는 Solana 주소. 크레딧을 절약하려면 여러 주소를 쉼표로 구분하여 한 요청에 포함할 수 있습니다.includeImages: 자산/프로토콜 이미지 URL 포함 (기본값: false)includeExplorerUrls: 블록 익스플로러 URL 포함 (기본값: false)waitForSync: 데이터가 오래된 경우 새 데이터를 기다림 (기본값: false)
응답 구조:
{
"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 (순자산 가치)
순자산 가치를 단일 값(선택적으로 다른 통화로 변환)으로 조회합니다.
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 }
파라미터:
addresses(필수): EVM 또는 Solana 주소currency: 법정화폐USD(기본값),EUR,CAD,AED,CHF,SGD; 암호화폐ETH,SOL,cbBTC,EURC,BNBwaitForSync: 데이터가 오래된 경우 새 데이터를 기다림 (기본값: false)
conversionPrice는 사용된 환율입니다. — 법정화폐의 경우 USD 기준 환율, 암호화폐의 경우 조회된 지갑의 가중 평균 USD 가격입니다.
거래 (Transactions)
필터링 기능과 함께 거래 내역을 조회합니다.
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}` } }
);
필수 파라미터:
addresses: 지갑 주소(들)limit: 페이지당 결과 수 (1-250)offset: 페이지네이션 오프셋
선택적 필터:
sort:DESC(최신순) 또는ASC(오래된순)networks: 체인 필터 (예:ethereum,arbitrum,base)txTypes: 거래 유형 필터 (예:SWAP,DEPOSIT)protocols: 프로토콜 필터 (예:uniswap_v3,aave_v3)hideSpam: 스팸 제외 (기본값: false)hideDust: 먼지 거래 제외 (기본값: false)startDate/endDate: ISO 8601 날짜 범위, UTC, 모두 포함.endDate는 해당 달력일의 종료 시간(23:59:59Z)으로 반올림되므로, 단일 날짜의 경우 두 값을 동일하게 설정하세요.endDate를 다음 날 자정으로 설정하지 마십시오(경계 트랜잭션이 중복됨).interactingAddresses: 상호작용 주소로 필터 (쉼표 구분)tokenId: NFT 토큰 ID로 필터initialSearchText: 자산의 전체 텍스트 검색
응답 (트랜잭션 배열):
[{
"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" }]
}]
거래 동기화 (Sync Transactions)
수동 동기화를 트리거하여 최신 거래 데이터를 가져옵니다.
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...'] })
});
// 반환: "Address is syncing" 또는 "Address already syncing"
비용: 1 크레딧 + 초기 인덱싱 시 250개 트랜잭션당 1 크레딧 (최초 1회).
상태 (Status, 무료)
비용이 큰 작업 전에 동기화 상태를 확인합니다.
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
크레딧 (Credits, 무료)
남은 크레딧 잔액을 확인합니다.
const credits = await fetch('https://api.octav.fi/v1/credits', {
headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());
// 반환: 19033 (숫자)
과거 포트폴리오 (Historical Portfolio)
특정 날짜의 포트폴리오 스냅샷을 가져옵니다. 구독이 필요합니다.
const response = await fetch(
`https://api.octav.fi/v1/historical?addresses=${address}&date=2024-11-01`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
토큰 개요 (Token Overview, PRO 전용)
프로토콜별 상세 토큰 분류.
const response = await fetch(
`https://api.octav.fi/v1/token-overview?addresses=${address}&date=2024-11-01`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
거래 유형
필터링에 사용되는 일반적인 유형:
| 유형 | 설명 |
|---|---|
TRANSFERIN | 토큰 수신 |
TRANSFEROUT | 토큰 전송 |
SWAP | 토큰 교환 |
DEPOSIT | DeFi 예치 |
WITHDRAW | DeFi 인출 |
STAKE | 스테이킹 |
UNSTAKE | 언스테이킹 |
CLAIM | 보상 클레임 |
ADDLIQUIDITY | LP 예치 |
REMOVELIQUIDITY | LP 인출 |
BORROW | 대출 프로토콜 차입 |
LEND | 대출 프로토콜 공급 |
BRIDGEIN / BRIDGEOUT | 크로스체인 브리지 |
APPROVAL | 토큰 승인 |
MINT | NFT/토큰 발행 |
지원 체인
전체 지원 (포트폴리오 + 거래): ethereum, arbitrum, base, polygon, optimism, avalanche, binance, solana, blast, linea, gnosis, sonic, starknet, fraxtal, unichain
포트폴리오 전용: scroll, zksync (era), mantle, manta, fantom, cronos, celo, 외 40+개
networks 필터에 체인 키를 사용하세요: ?networks=ethereum,arbitrum,base
오류 처리
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');
}
일반적인 오류:
401: API 키가 유효하지 않거나 누락됨402: 크레딧 부족403: 엔드포인트에 PRO 구독 필요429: 속도 제한 초과 (대기 후 재시도)404: 주소가 인덱싱되지 않음 (>100,000개 트랜잭션)
비용 최적화
- 주소 배치 처리: 한 요청에 쉼표로 구분하세요 —
?addresses=0x123,0x456,0x789— 각각 호출하는 것보다 크레딧 절약 - 무료 엔드포인트 사용:
/v1/status,/v1/credits,/v1/chains,/v1/chains/{chainKey}/protocols는 비용이 없습니다. - 서버 측 필터링: 클라이언트 측 필터링보다
networks,txTypes파라미터를 사용하세요. - 결과 캐싱: 포트폴리오 1분, 트랜잭션 10분 캐시
- 먼저 상태 확인: 불필요한 동기화 방지
일반적인 패턴
다중 지갑 포트폴리오
const addresses = ['0x123...', '0x456...', '0x789...'];
const response = await fetch(
`https://api.octav.fi/v1/portfolio?addresses=${addresses.join(',')}`,
{ headers: { 'Authorization': `Bearer ${apiKey}` } }
);
페이지네이션된 거래 가져오기
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;
}
스마트 동기화 워크플로우
async function smartSync(address) {
// 먼저 상태 확인 (무료)
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 인터페이스
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;
}
가격
| 패키지 | 크레딧 | 가격 | 크레딧당 가격 |
|---|---|---|---|
| Starter | 4,000 | $100 | $0.025 |
| Small Team | 100,000 | $2,500 | $0.025 |
| Intensive | 1,000,000 | $20,000 | $0.020 |
크레딧은 만료되지 않습니다. 최초 주소 인덱싱: 250개 트랜잭션당 1 크레딧.
리소스
- 개발자 포털: https://data.octav.fi
- API 문서: https://docs.octav.fi
- 전체 엔드포인트 참조: http
…