AgentSkillsCN

league-sdk

使用 league-sdk TypeScript 库构建《英雄联盟》应用。适用于与 Riot API 合作、查询召唤师或玩家信息、获取比赛历史、掌握英雄精通度、查看排位数据、实时观战比赛,或构建 LoL Discord 机器人、网站或应用时使用。

SKILL.md
--- frontmatter
name: league-sdk
description: Build League of Legends apps using league-sdk TypeScript library. Use when working with Riot API, summoner/player lookups, match history, champion mastery, ranked stats, live game spectator, or building LoL Discord bots, websites, or apps.

League SDK

Typed TypeScript SDK for Riot LoL API. Handles routing, PUUID conversions, rate limiting.

LoL API Concepts

Scope: This SDK covers League of Legends only. TFT, Valorant, Wild Rift have separate APIs.

PUUID: Universal ID across Riot games. Preferred over SummonerId/AccountId (deprecated).

Platform: Use player's server (kr for Korean, euw1 for EU West). Wrong platform = 404.

Queue IDs: 420 Solo/Duo, 440 Flex, 450 ARAM, 400 Normal Draft, 430 Blind

Timestamps: Unix epoch milliseconds → new Date(match.gameCreation)

Match history: Riot retains ~2 years. Older matches may be unavailable.

Patterns

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

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

// Player lookup
const player = await client.players.getByRiotId('Name', 'Tag');

// Ranked stats
const soloQ = await player.getSoloQueueStats();
// soloQ.tier, soloQ.division, soloQ.winRate (0-1 decimal)

// Match history
const matches = await player.getMatches({ count: 10, queue: 420 }); // 420 = ranked
for (const match of matches) {
  const p = match.getParticipant(player.puuid)!;
  console.log(`${p.championName} ${p.kills}/${p.deaths}/${p.assists} - ${p.win ? 'W' : 'L'}`);
}

// Participant stats
const p = match.getParticipant(player.puuid)!;
p.kills; p.deaths; p.assists; p.kda;
p.championName; p.win;
p.items;          // { item0-5, trinket }
p.totalCs; p.csPerMinute;
p.damage.toChampions; p.damage.taken;
p.goldEarned; p.visionScore;

// Match stats
match.gameDurationFormatted;  // "32:15"
match.queueName;              // "Ranked Solo/Duo"
match.blueTeam; match.redTeam;
match.getWinner(); match.didPlayerWin(player.puuid);

// Team comparison
const { blueTeam, redTeam } = match;
console.log(`Blue: ${blueTeam.totalKills}K, ${blueTeam.totalGold}g`);

// Live game (null if not in game)
const game = await player.getLiveGame();

// Mastery
const top = await player.getTopMastery(3);
// m.championName, m.championPoints, m.championLevel

// Static data (no API key needed)
const champs = await client.dataDragon.getChampions();
const items = await client.dataDragon.getItems();
await client.dataDragon.getChampionIconUrl('Ahri');
await client.dataDragon.getItemIconUrl(3157);

Asset Downloads

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

Programmatic: import { downloadAllAssets } from 'league-sdk/scripts'

Platforms

na1 euw1 eun1 kr jp1 br1 la1 la2 oc1 tr1 ru sg2 ph2 th2 tw2 vn2

Troubleshooting

  • 401: API key expired (dev keys last 24h)
  • 404: Wrong platform or player doesn't exist
  • 429: Rate limited (SDK handles automatically)
  • NotFoundError: Player/match doesn't exist
  • RateLimitError: Has retryAfter property (seconds)
  • AuthenticationError: Invalid API key