Communitygithub.com

Octav Labs / Octav API 스킬

Octav API와 통합하여 50개 이상의 블록체인 네트워크에서 암호화폐 포트폴리오 추적, 거래 내역 조회, DeFi 분석을 수행합니다.

Octav API 스킬란 무엇인가요?

이 스킬은 Octav API를 기반으로 하여 개발자와 AI 에이전트가 여러 블록체인 네트워크에 분산된 암호화폐 포트폴리오의 자산, 순자산 가치(Nav), 거래 내역, DeFi 프로토콜 포지션 등을 손쉽게 조회하고 분석할 수 있도록 지원합니다. 50개 이상의 체인을 지원하며, REST API와 x402 프로토콜(요청당 지불) 두 가지 접근 방식을 제공합니다. REST API는 API 키를 통해 25개 엔드포인트를 모두 사용할 수 있고, x402는 API 키 없이 소액 USDC로 5개 핵심 엔드포인트를 호출할 수 있어 자율 에이전트에 적합합니다. 주요 기능으로는 포트폴리오 조회, 과거 스냅샷, 거래 내역 검색 및 필터링, 동기화 트리거 등이 있으며, 코드 예제와 최적화 팁을 함께 제공하여 실무에 바로 적용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add Octav-Labs/octav-api-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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/portfolioGET1 크레딧체인/프로토콜별 포트폴리오 보유 자산
/v1/portfolio/at-blockGET추가 + 1 크레딧특정 과거 블록(Ethereum) 기준 포트폴리오 가치 평가
/v1/virtual-usersGET1 크레딧가상 사용자 목록 (Pro)
/v1/virtual-users/portfolioGET주소당 1 크레딧가상 사용자 보유 자산 (Pro)
/v1/navGET1 크레딧순자산 가치 — {nav, currency, conversionPrice}
/v1/walletGET1 크레딧지갑 토큰 잔액 (DeFi 포지션 제외)
/v1/transactionsGET1 크레딧필터링 가능한 거래 내역
/v1/approvals/{chain}GET1 크레딧ERC-20 토큰 승인 기록
/v1/token-overviewGET1 크레딧프로토콜별 토큰 분류 (PRO 전용)
/v1/airdropGET1 크레딧클레임 가능한 에어드랍 (Solana 전용)
/v1/historicalGET1 크레딧과거 포트폴리오 스냅샷
/v1/sync-transactionsPOST1+ 크레딧거래 동기화 트리거
/v1/contract-protocolGET5 크레딧컨트랙트 주소를 DeFi 프로토콜로 확인 (404 시 환불)
/v1/beacon/validators/*GET추가ETH 검증인 상세 정보, 보상, 출금, 입금
/v1/chainsGET무료지원되는 블록체인 네트워크 목록
/v1/chains/{chainKey}/protocolsGET무료체인의 프로토콜 목록
/v1/statusGET무료동기화 상태 확인
/v1/creditsGET무료크레딧 잔액 확인

구독 스냅샷 (POST, 1200 크레딧)은 주소에 대한 일일 포트폴리오 스냅샷을 활성화하며, /v1/historical이 이를 읽습니다.

x402 엔드포인트 (API 키 불필요 — 위 접근 방법 참조)

엔드포인트메서드비용설명
/v1/agent/portfolioGET0.025 USDC지갑 및 프로토콜 자산
/v1/agent/walletGET0.025 USDC지갑 자산만
/v1/agent/navGET0.025 USDC순자산 가치 — {nav, currency, conversionPrice}
/v1/agent/statusGET0.025 USDC동기화 상태
/v1/agent/chainsGET0.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}&currency=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, BNB
  • waitForSync: 데이터가 오래된 경우 새 데이터를 기다림 (기본값: 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토큰 교환
DEPOSITDeFi 예치
WITHDRAWDeFi 인출
STAKE스테이킹
UNSTAKE언스테이킹
CLAIM보상 클레임
ADDLIQUIDITYLP 예치
REMOVELIQUIDITYLP 인출
BORROW대출 프로토콜 차입
LEND대출 프로토콜 공급
BRIDGEIN / BRIDGEOUT크로스체인 브리지
APPROVAL토큰 승인
MINTNFT/토큰 발행

지원 체인

전체 지원 (포트폴리오 + 거래): 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개 트랜잭션)

비용 최적화

  1. 주소 배치 처리: 한 요청에 쉼표로 구분하세요 — ?addresses=0x123,0x456,0x789 — 각각 호출하는 것보다 크레딧 절약
  2. 무료 엔드포인트 사용: /v1/status, /v1/credits, /v1/chains, /v1/chains/{chainKey}/protocols는 비용이 없습니다.
  3. 서버 측 필터링: 클라이언트 측 필터링보다 networks, txTypes 파라미터를 사용하세요.
  4. 결과 캐싱: 포트폴리오 1분, 트랜잭션 10분 캐시
  5. 먼저 상태 확인: 불필요한 동기화 방지

일반적인 패턴

다중 지갑 포트폴리오

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

가격

패키지크레딧가격크레딧당 가격
Starter4,000$100$0.025
Small Team100,000$2,500$0.025
Intensive1,000,000$20,000$0.020

크레딧은 만료되지 않습니다. 최초 주소 인덱싱: 250개 트랜잭션당 1 크레딧.

리소스

…

관련 스킬