---
slug: "league-sdk"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/adrianmg/league-sdk@main/README.md"
repo: "https://github.com/adrianmg/league-sdk"
source_file: "README.md"
branch: "main"
---
<p align="center">
  <img src="https://raw.githubusercontent.com/adrianmg/league-sdk/main/logo.png" alt="League SDK" width="600">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/league-sdk"><img src="https://img.shields.io/npm/v/league-sdk.svg" alt="npm version"></a>
  <img src="https://img.shields.io/npm/dw/league-sdk.svg" alt="npm downloads">
  <img src="https://img.shields.io/badge/coverage-92%25-brightgreen" alt="coverage">
</p>

# league-sdk

A fully typed TypeScript SDK for the Riot League of Legends API.

## Why This SDK?

Working with the raw Riot API requires multiple endpoints, complex routing, and manual data transformation. This SDK simplifies everything:

**Raw API (multiple calls, manual work):**
```typescript
// 1. Get account by Riot ID (regional endpoint)
const account = await fetch(`https://asia.api.riotgames.com/riot/account/v1/accounts/by-riot-id/Hide%20on%20bush/KR1?api_key=${key}`);
const { puuid } = await account.json();

// 2. Get summoner data (platform endpoint)
const summoner = await fetch(`https://kr.api.riotgames.com/lol/summoner/v4/summoners/by-puuid/${puuid}?api_key=${key}`);
const { id: summonerId } = await summoner.json();

// 3. Get ranked stats (platform endpoint, different ID)
const leagues = await fetch(`https://kr.api.riotgames.com/lol/league/v4/entries/by-puuid/${puuid}?api_key=${key}`);
const ranked = await leagues.json();
const soloQ = ranked.find(q => q.queueType === 'RANKED_SOLO_5x5');

// 4. Calculate win rate manually
const winRate = soloQ.wins / (soloQ.wins + soloQ.losses);
```

**With league-sdk:**
```typescript
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();
console.log(`${soloQ.tier} ${soloQ.division} - ${(soloQ.winRate * 100).toFixed(1)}% WR`);
```

## Getting Started

### Installation

```bash
npm install league-sdk
# or
bun add league-sdk
```

### API Key

Get your key at [developer.riotgames.com](https://developer.riotgames.com/). Dev keys last 24h (20/s, 100/2min). Register a product for permanent keys.

### Quick Start

```typescript
import { LolClient } from 'league-sdk';

const client = new LolClient({
  apiKey: process.env.RIOT_API_KEY!,
  platform: 'kr'
});

// Get player and their ranked stats
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
const soloQ = await player.getSoloQueueStats();

// Get recent matches
const matches = await client.matches.getForPlayer(player.puuid, { count: 5 });
for (const match of matches) {
  const p = match.getParticipant(player.puuid)!;
  console.log(`${p.championName}: ${p.kills}/${p.deaths}/${p.assists}`);
}
```

### Development

```bash
bun install && bun test
```

```bash
# Skill for AI Agents
npx skills add https://github.com/adrianmg/league-sdk --skill league-sdk
```

## Features

| Service | Description | Example |
|---------|-------------|---------|
| **Players** | Lookup by Riot ID or PUUID | `client.players.getByRiotId('Name', 'Tag')` |
| **Matches** | Match history and details | `client.matches.getForPlayer(puuid)` |
| **Mastery** | Champion mastery stats | `client.mastery.getForPlayer(puuid)` |
| **Live Game** | Current game spectator | `client.liveGame.getForPlayer(puuid)` |
| **Status** | Server health | `client.status.get('euw1')` |
| **Challenges** | Challenge progress | `client.challenges.getPlayerProfile(puuid)` |
| **Clash** | Tournament info | `client.clash.getPlayer(puuid)` |
| **Data Dragon** | Static data (no key needed) | `client.dataDragon.getChampions()` |

## Entities

```typescript
// Player
const player = await client.players.getByRiotId('Hide on bush', 'KR1');
player.puuid; player.riotId; player.level;
await player.getSoloQueueStats();

// Match
const match = await client.matches.getById('EUW1_1234567890');
match.gameMode; match.gameDurationFormatted; match.winner;
const p = match.getParticipant(puuid)!;
p.kills; p.deaths; p.assists; p.kda; p.csPerMinute;
```

## Constants & Helpers

```typescript
import { PLATFORMS, QUEUES, isRankedQueue, formatRank, compareRanks } from 'league-sdk';

PLATFORMS.EUW1           // 'euw1'
isRankedQueue(420)       // true (Solo/Duo)
formatRank('DIAMOND', 'II')  // "Diamond II"
compareRanks('DIAMOND', 'II', 'PLATINUM', 'I')  // 1 (Diamond > Plat)
```

## Error Handling

Typed errors: `NotFoundError`, `RateLimitError` (has `retryAfter`), `AuthenticationError`.

## Asset Downloads

```bash
npx league-sdk-assets --output ./assets --all
```

Programmatic API also available via `league-sdk/scripts`.

## Rate Limiting

Built-in rate limiter (20/s, 100/2min). Configure via `rateLimiter` option or check status with `client.getRateLimitStatus()`.

## Example Server

```bash
RIOT_API_KEY=your-key bun run example/server.ts
```

## Platforms

| Platform | Region | Location |
|----------|--------|----------|
| `na1` | americas | North America |
| `br1` | americas | Brazil |
| `la1` | americas | Latin America North |
| `la2` | americas | Latin America South |
| `euw1` | europe | EU West |
| `eun1` | europe | EU Nordic & East |
| `tr1` | europe | Turkey |
| `ru` | europe | Russia |
| `kr` | asia | Korea |
| `jp1` | asia | Japan |
| `oc1` | sea | Oceania |
| `ph2` | sea | Philippines |
| `sg2` | sea | Singapore |
| `th2` | sea | Thailand |
| `tw2` | sea | Taiwan |
| `vn2` | sea | Vietnam |

## License

MIT

## Acknowledgments

This project was developed with assistance from AI coding tools including GitHub Copilot and Claude.