npm package: @makebelieve21213-packages/defillama-client
Description: DeFiLlama API client for NestJS with TypeScript support
Author: Skryabin Aleksey
Latest version: 1.0.0

# @packages/defillama-client

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

## 📋 Содержание

- [Возможности](#-возможности)
- [Требования](#-требования)
- [Установка](#-установка)
- [Структура пакета](#-структура-пакета)
- [Быстрый старт](#-быстрый-старт)
- [API Reference](#-api-reference)
- [Примеры использования](#-примеры-использования)
- [Troubleshooting](#-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

## 📦 Установка

```bash
npm install @packages/defillama-client
```

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

```json
{
  "@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: Настройка переменных окружения

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

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

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

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

```typescript
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: Регистрация модуля

```typescript
// 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: Использование сервиса

```typescript
// 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):**

```typescript
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.

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

#### `getProtocol(slug)`

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

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

#### `getTotalTVL()`

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

```typescript
async getTotalTVL(): Promise<TVLData>
```

#### `getStablecoins()`

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

```typescript
async getStablecoins(): Promise<StablecoinData[]>
```

#### `getYieldPools()`

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

```typescript
async getYieldPools(): Promise<YieldPool[]>
```

#### `searchProtocols(query)`

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

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

#### `getBridges()`

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

```typescript
async getBridges(): Promise<BridgeData[]>
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```typescript
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% покрытие тестами**.

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

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

```typescript
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