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):

// 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:

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`);

Installation

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

Quick Start

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

API Key Setup

Get your API key at developer.riotgames.com:

1. Sign in with your Riot account
2. Go to Dashboard and copy your Development API Key
3. For permanent keys, register a product under Register Product

| Key Type | Rate Limits | Duration | Use Case | |----------|-------------|----------|----------| | Development | 20 req/s, 100 req/2min | 24 hours | Testing | | Personal | 20 req/s, 100 req/2min | Permanent | Personal apps | | Production | Higher limits | Permanent | Public apps |

Create a .env file:

RIOT_API_KEY=RGAPI-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

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() |

Player Entity

const player = await client.players.getByRiotId('Hide on bush', 'KR1');

player.puuid          // Unique ID
player.riotId         // "Hide on bush#KR1"
player.level          // Summoner level

await player.getRankedStats();     // All ranked queues
await player.getSoloQueueStats();  // Solo/Duo only
await player.getFlexQueueStats();  // Flex only
await player.getMatchIds({ count: 10, queue: 420 });

Match Entity

const match = await client.matches.getById('EUW1_1234567890');

match.gameMode            // "CLASSIC"
match.gameDurationFormatted // "32:15"
match.blueTeam / match.redTeam
match.winner              // Winning team

const p = match.getParticipant(puuid)!;
p.kills / p.deaths / p.assists
p.kda                     // Calculated KDA
p.totalCs / p.csPerMinute
p.damage.toChampions

Constants & Helpers

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

import { NotFoundError, RateLimitError, AuthenticationError } from 'league-sdk';

try {
  const player = await client.players.getByRiotId('Unknown', 'Player');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Player not found');
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  }
}

Asset Downloads

Download game assets (no API key needed).

CLI:

npx league-sdk-assets --output ./assets
npx league-sdk-assets --output ./assets --champions --items
npx league-sdk-assets --output ./assets --all

Programmatic:

import { downloadChampionIcons, downloadAllAssets } from 'league-sdk/scripts';

await downloadChampionIcons({ outputDir: './assets' });
await downloadAllAssets({ outputDir: './assets', champions: true, items: true });

Rate Limiting

Built-in token bucket rate limiter (enabled by default):

const client = new LolClient({
  apiKey: 'your-key',
  rateLimiter: {
    requestsPerSecond: 20,    // Default
    requestsPerWindow: 100,   // Default (2-min window)
    enabled: true
  }
});

// Check status
const status = client.getRateLimitStatus();

Example Server

A complete REST API example using Hono is included in example/server.ts:

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

Endpoints: /player/:name/:tag, /player/:name/:tag/matches, /match/:id, /status

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 |

Development

# Install dependencies
bun install

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Type check
bun run lint

# Build
bun run build

# Run real API integration tests
ALLOW_NETWORK=true RIOT_API_KEY=your-key bun test tests/real-api.test.ts

License

MIT

Acknowledgments

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