@packages/defillama-client

DeFiLlama API клиент для NestJS с поддержкой TypeScript и полной типобезопасностью.

📋 Содержание

• Возможности
• Требования
• Установка
• Структура пакета
• Быстрый старт
• API Reference
• Примеры использования
• Troubleshooting
• Тестирование

🚀 Возможности

• ✅ NestJS интеграция - глобальный модуль с forRootAsync для простой интеграции
• ✅ Type-safe API - полная типобезопасность TypeScript с экспортируемыми типами
• ✅ HTTP клиент - использование нативного fetch API с поддержкой таймаутов
• ✅ Конфигурация - поддержка базового URL через ConfigModule (API ключ не требуется)
• ✅ Трансформация данных - автоматическое преобразование snake_case → camelCase
• ✅ Обработка ошибок - детальная обработка ошибок API с логированием
• ✅ 100% покрытие тестами - надежность и качество кода

📋 Требования

• Node.js: >= 22.11.0
• NestJS: >= 11.0.0

📦 Установка

npm install @packages/defillama-client

Зависимости

{
  "@nestjs/common": "^11.0.0",
  "@nestjs/config": "^11.0.0",
  "@makebelieve21213-packages/logger": "^1.0.0",
  "reflect-metadata": "^0.1.13 || ^0.2.0"
}

📁 Структура пакета

src/
├── main/                    # NestJS модуль
├── types/                   # TypeScript типы
├── utils/                   # Утилиты
└── index.ts                 # Экспорты

🏗️ Архитектура

Пакет предоставляет NestJS глобальный модуль DeFiLlamaModule для работы с DeFiLlama API через HTTP запросы.

Основные компоненты:

• DeFiLlamaModule - NestJS глобальный модуль
• DeFiLlamaService - сервис для работы с API
• DeFiLlamaModuleOptions - конфигурация клиента
• Типы: DeFiProtocol, DeFiProtocolDetails, TVLData, StablecoinData, YieldPool, BridgeData

🔧 Быстрый старт

Шаг 1: Настройка переменных окружения

DEFILLAMA_BASE_URL=https://api.llama.fi  # Опционально
DEFILLAMA_TIMEOUT=30000  # Опционально

Примечание: DeFiLlama API не требует API ключа, это бесплатный публичный API.

Шаг 2: Создание конфигурации

Создайте файл defillama.config.ts в вашем сервисе:

import { registerAs } from "@nestjs/config";
import type { DeFiLlamaModuleOptions } from "@packages/defillama-client";
import { EnvVariable } from "src/types/enums";

export type DeFiLlamaConfiguration = DeFiLlamaModuleOptions;

const defillamaConfig = registerAs<DeFiLlamaConfiguration>(
  "defillama",
  (): DeFiLlamaConfiguration => ({
    baseUrl: process.env[EnvVariable.DEFILLAMA_BASE_URL] || "https://api.llama.fi",
    timeout: Number(process.env[EnvVariable.DEFILLAMA_TIMEOUT]) || 30000,
  }),
);

export default defillamaConfig;

Шаг 3: Регистрация модуля

// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { DeFiLlamaModule } from '@packages/defillama-client';
import defillamaConfig from 'src/configs/defillama.config';
import type { DeFiLlamaConfiguration } from 'src/configs/defillama.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [defillamaConfig],
    }),
    DeFiLlamaModule.forRootAsync<[DeFiLlamaConfiguration]>({
      useFactory: (config: DeFiLlamaConfiguration) => config,
      inject: [defillamaConfig.KEY],
      imports: [ConfigModule],
    }),
  ],
})
export class AppModule {}

Шаг 4: Использование сервиса

// defi-data.service.ts
import { Injectable } from '@nestjs/common';
import { DeFiLlamaService } from '@packages/defillama-client';
import type { DeFiProtocol } from '@packages/defillama-client';

@Injectable()
export class DeFiDataService {
  constructor(private readonly defillama: DeFiLlamaService) {}

  async getTopProtocols(limit: number = 100): Promise<DeFiProtocol[]> {
    return await this.defillama.getTopProtocols(limit);
  }
}

📚 API Reference

DeFiLlamaModule

forRootAsync(options):

DeFiLlamaModule.forRootAsync<[DeFiLlamaConfiguration]>({
  useFactory: (config: DeFiLlamaConfiguration) => config,
  inject: [defillamaConfig.KEY],
  imports: [ConfigModule],
})

Экспортирует: DeFiLlamaService (глобально)

DeFiLlamaService

Конфигурация:

• baseUrl?: string - базовый URL (по умолчанию: https://api.llama.fi)
• timeout?: number - таймаут запросов в мс (по умолчанию: 30000)

Методы:

getTopProtocols(limit?)

Получает список топ DeFi протоколов с ограничением по количеству. Автоматически преобразует данные из snake_case в camelCase.

async getTopProtocols(limit?: number): Promise<DeFiProtocol[]>

getProtocol(slug)

Получает детальную информацию о DeFi протоколе по его slug.

async getProtocol(slug: string): Promise<DeFiProtocolDetails>

getTotalTVL()

Получает общий TVL всех блокчейнов и разбивку по цепочкам.

async getTotalTVL(): Promise<TVLData>

getStablecoins()

Получает список стейблкоинов с их метриками и данными по эмиссии. Использует отдельный домен stablecoins.llama.fi.

async getStablecoins(): Promise<StablecoinData[]>

getYieldPools()

Получает список пулов доходности с информацией об APY и TVL. Использует отдельный домен yields.llama.fi.

async getYieldPools(): Promise<YieldPool[]>

searchProtocols(query)

Выполняет поиск DeFi протоколов по имени, символу или категории.

async searchProtocols(query: string): Promise<DeFiProtocol[]>

getBridges()

Получает список мостов с информацией об объемах трансферов. Использует отдельный домен bridges.llama.fi.

async getBridges(): Promise<BridgeData[]>

🧪 Примеры использования

Получение топ DeFi протоколов

const topProtocols = await this.defillama.getTopProtocols(50);
topProtocols.forEach(protocol => {
  console.log(`${protocol.name} (${protocol.symbol}): $${protocol.tvl}`);
  console.log(`Category: ${protocol.category}`);
});

Получение детальной информации о протоколе

const uniswap = await this.defillama.getProtocol('uniswap');
console.log(`Name: ${uniswap.name}`);
console.log(`TVL: $${uniswap.tvl}`);

Получение общего TVL

const tvlData = await this.defillama.getTotalTVL();
console.log(`Total TVL: $${tvlData.tvl}`);

Получение данных о стейблкоинах

const stablecoins = await this.defillama.getStablecoins();
stablecoins.forEach(coin => {
  console.log(`${coin.name} (${coin.symbol}): $${coin.marketCap}`);
});

Получение пулов доходности

const pools = await this.defillama.getYieldPools();
pools.forEach(pool => {
  console.log(`${pool.project} - ${pool.symbol} on ${pool.chain}`);
  console.log(`APY: ${pool.apy}%`);
});

Поиск протоколов

const protocols = await this.defillama.searchProtocols('lending');
protocols.forEach(protocol => {
  console.log(`${protocol.name} - ${protocol.category}`);
});

Получение данных о мостах

const bridges = await this.defillama.getBridges();
bridges.forEach(bridge => {
  console.log(`${bridge.name}`);
  console.log(`24h Volume: $${bridge.lastDailyVolume}`);
});

🚨 Troubleshooting

Request timeout

Решение: Увеличить DEFILLAMA_TIMEOUT, проверить интернет-соединение, проверить доступность API DeFiLlama.

Protocol not found

Решение: Проверить правильность slug (нижний регистр), использовать searchProtocols() для поиска.

Трансформация данных не работает

Решение: Убедиться, что используется правильный метод (все методы автоматически трансформируют данные).

Stablecoins/Yields/Bridges API недоступен

Решение: Проверить доступность соответствующих доменов (stablecoins.llama.fi, yields.llama.fi, bridges.llama.fi).

🧪 Тестирование

Пакет имеет 100% покрытие тестами.

pnpm test                # Все тесты
pnpm test:coverage       # С покрытием
pnpm test:watch          # Watch режим

🔧 Конфигурация

interface DeFiLlamaModuleOptions {
  baseUrl?: string;       // Базовый URL (опционально)
  timeout?: number;       // Таймаут в мс (опционально)
}

Примечание: Конфигурация должна создаваться в сервисе, который использует пакет.

🌐 Особенности DeFiLlama API

DeFiLlama использует разные домены для разных эндпоинтов:

• Основной API: https://api.llama.fi - протоколы, TVL
• Stablecoins API: https://stablecoins.llama.fi - стейблкоины
• Yields API: https://yields.llama.fi - пулы доходности
• Bridges API: https://bridges.llama.fi - мосты

Пакет автоматически использует правильные домены для каждого метода.

📦 Зависимости

• @nestjs/common - NestJS core
• @nestjs/config - NestJS config
• @makebelieve21213-packages/logger - Логирование
• reflect-metadata - TypeScript decorators

📄 Лицензия

UNLICENSED (private package)

👥 Автор

Skryabin Aleksey