DefiLlama Service

Integration service for fetching live TVL and APY data from DefiLlama API

Overview

The DefiLlama service integrates with DefiLlama’s API to fetch real-time Total Value Locked (TVL) and Annual Percentage Yield (APY) data for Stacks DeFi protocols.

Location: src/services/defiLlamaService.js

API Strategy

Data Sources

• TVL: api.llama.fi/protocol/{slug} - Works for all Stacks protocols
• APY: Fetched from medianApy field in protocol endpoint
• Logos: icons.llama.fi/{slug}.png

Protocol Metadata

The PROTOCOL_META array defines all supported Stacks DeFi protocols with their metadata and fallback values:

PROTOCOL_META · array

Array of protocol configuration objects

Show Protocol Object Properties

id · string · required

Unique protocol identifier (e.g., stackingdao, zest, alex)

name · string · required

Display name of the protocol

slug · string · required

DefiLlama protocol slug for API calls

type · string · required

Protocol category: Stacking, Lending, DEX, Yield, or Borrowing

asset · string · required

Primary asset type (e.g., STX, sBTC, sBTC/STX)

risk · string · required

Risk level: Low, Medium, or High

audited · boolean · required

Whether the protocol has been security audited

minDeposit · string · required

Minimum deposit requirement

url · string · required

Protocol website URL

logo · string · required

Logo URL (local or DefiLlama CDN)

color · string · required

Brand color hex code for UI theming

fallbackApy · number · required

Fallback APY when API returns null (percentage)

fallbackTvlRaw · number

Fallback TVL in USD (optional, for protocols with inconsistent API data)

fallbackTvl · string

Formatted fallback TVL string (optional)

Example Protocol Entry

{
  id: 'stackingdao',
  name: 'StackingDAO',
  slug: 'stackingdao',
  type: 'Stacking',
  asset: 'STX',
  risk: 'Low',
  audited: true,
  minDeposit: '100 STX',
  url: 'https://stackingdao.com',
  logo: '/logos/stackingdao.png',
  color: '#3B82F6',
  fallbackApy: 9.5,
}

Main Function

fetchAllProtocolData()

Fetches live TVL and APY data for all protocols in parallel.

fetchAllProtocolData · function

Returns enriched protocol data with live or fallback values

Returns: Promise<Array<ProtocolData>>

ProtocolData · object

Extended protocol object with live data

Show Additional Fields

tvlRaw · number

Raw TVL in USD (null if unavailable)

tvl · string

Formatted TVL string (e.g., $45.2M, $1.2B)

apy · number

APY percentage (live or fallback)

apyDisplay · string

Formatted APY string (e.g., 9.5%)

apySource · string

Data source: live or fallback

Usage Example

Basic Usage

import { fetchAllProtocolData } from './services/defiLlamaService';

async function loadProtocols() {
  try {
    const protocols = await fetchAllProtocolData();
    
    protocols.forEach(protocol => {
      console.log(`${protocol.name}:`);
      console.log(`  TVL: ${protocol.tvl}`);
      console.log(`  APY: ${protocol.apyDisplay}`);
      console.log(`  Data: ${protocol.apySource}`);
    });
  } catch (error) {
    console.error('Failed to fetch protocol data:', error);
  }
}

Implementation Details

TVL Fetching

The service prioritizes Stacks-specific chain TVL over total protocol TVL:

const tvlRaw =
  data?.currentChainTvls?.Stacks ??
  data?.currentChainTvls?.stacks ??
  data?.tvl ??
  null;

APY Resolution

APY is sourced from DefiLlama’s medianApy field with fallback:

const apyRaw =
  data?.medianApy ??
  data?.apy ??
  null;

const apy = fetched.apy ?? meta.fallbackApy ?? null;

Error Handling

Uses Promise.allSettled() to ensure partial failures don’t break entire data fetch:

const results = await Promise.allSettled(
  PROTOCOL_META.map(async (meta) => {
    // Individual protocol fetch with try/catch
  })
);

TVL Formatting

The service includes a formatTVL() helper that converts raw USD values to readable strings:

Raw Value	Formatted
1,234,567,890	$1.23B
45,600,000	$45.60M
431,000	$431.0K
850	$850

Supported Protocols

StackingDAO

Liquid stacking protocol for STX

Zest Protocol

Bitcoin-backed lending with sBTC

ALEX Lab

Decentralized exchange and AMM

Bitflow

Liquidity pools and swaps

Hermetica

Yield optimization strategies

Velar

DEX with advanced trading features

Granite

Bitcoin-collateralized borrowing

Related

useProtocolData Hook

React hook wrapper with auto-refresh

Portfolio Protocols

Detect user positions in protocols