@windowsed1225/valorant-api

Unofficial Node.js library for the VALORANT APIs used in-game.

Installation

npm install @windowsed1225/valorant-api
# or
bun add @windowsed1225/valorant-api

Quick Start

import { API } from "@windowsed1225/valorant-api";

const api = new API();

// Authenticate with existing Riot session cookies
await api.cookiesReAuth("ssid=...; clid=...; ...other cookies");

console.log("Logged in as:", api.data.puuid);

// Get player rank
const mmr = await api.getPlayerMMR(api.data.puuid);
console.log("Current rank:", mmr.LatestCompetitiveUpdate.TierAfterUpdate);

Authentication

Cookie Re-auth (recommended)

Fastest method — reuse an existing Riot session without logging in again.

const api = new API();
await api.cookiesReAuth("ssid=...; sub=...; csid=...");

QR Code Auth

Authenticate by scanning a QR code with the Riot Mobile app. No password required.

import qrcode from "qrcode";
import axios from "axios";
import { API, QRCodeAuth, utils } from "@windowsed1225/valorant-api";

const qr = new QRCodeAuth();
const api = new API();

const { login_url, session_cookies, sdk_sid } = await qr.create();

console.log(await qrcode.toString(login_url, { type: "terminal", small: true }));
console.log("Scan with the Riot Mobile app...");

while (true) {
  await new Promise(r => setTimeout(r, 2000));
  const session = axios.create();
  const raw = await qr.get_login_token(session, sdk_sid, session_cookies, "HK"); // your country code
  if (!raw) continue;

  if (raw.type === "success") {
    const cookies = await qr.get_access_token(raw.success.login_token);
    if (Array.isArray(cookies)) {
      const parsed = utils.parseSetCookie(cookies);
      await api.cookiesReAuth(`ssid=${parsed["ssid"]}`);
      console.log("Logged in as:", api.data.userinfo?.acct.game_name);
    }
    break;
  }
}

Features

✅ Can fetch with another player's PUUID    ❌ Authenticated player only

Matches

| Method | Access | | --- | --- | | getMatchHistory(puuid, start, end, queue?) | ✅ | | getCurrentMatch(matchId) | ✅ | | getCurrentPlayer(puuid) | ✅ | | getPlayerCompetitiveHistory(puuid, start, end) | ✅ |

Player

| Method | Access | | --- | --- | | getPlayerMMR(puuid) | ✅ | | getPlayerWallet(puuid) | ✅ | | getPlayerAccountXp(puuid) | ✅ | | getRegion() | ✅ | | getPlayerLoadout(puuid) | ❌ | | setPlayerLoadout(puuid, loadout) | ❌ | | getFavorites(puuid) | ✅ | | getEntitlements(puuid) | ✅ | | getContract(puuid) | ✅ | | getBattlepassPurchase(puuid) | ✅ | | getPlayerSettings() | ❌ | | savePreference(body) | ❌ |

Party

| Method | Access | | --- | --- | | getPartyByPlayer(puuid) | ✅ | | getParty(partyId) | ✅ | | getSession(puuid) | ✅ |

Store

| Method | Access | | --- | --- | | getStoreOffers(puuid) | ✅ | | getPurchaseHistory(cookies) | ❌ |

Leaderboard

| Method | Access | | --- | --- | | getCompetitiveLeaderboard(seasonId, start, size) | ✅ |

Alias / Player Search

| Method | Access | | --- | --- | | findRiotAlias(gameName, tagLine) | ✅ | | getPlayersName(puuids) | ✅ |

Misc

| Method | Access | | --- | --- | | getContent() | ✅ | | getConfig(region) | ✅ | | getPenalties() | ✅ |

API Reference

API class

Properties

| Property | Type | Description | | --- | --- | --- | | data | object | Contains access_token, id_token, entitlements_token, puuid, userinfo | | region | region | Player's region (na, eu, ap, br, kr, latam) | | client_version | string | Current VALORANT client version |

ItemType enum

Use these constants wherever an item type ID is required.

import { ItemType } from "@windowsed1225/valorant-api";

console.log(ItemType.Skins);
// "e7c63390-eda7-46e0-bb7a-a6abdacd2433"

| Key | UUID | | --- | --- | | Agents | 01bb38e1-da47-4e6a-9b3d-945fe4655707 | | Skins | e7c63390-eda7-46e0-bb7a-a6abdacd2433 | | SkinVariants | 3ad1b2b2-acdb-4524-852f-954a76ddae0a | | Sprays | d5f120f8-ff8c-4aac-92ea-f2b5acbe9475 | | GunBuddies | dd3bf334-87f3-40bd-b043-682a57a8dc3a | | Cards | 3f296c07-64c3-494c-923b-fe692a4fa1bd | | Titles | de7caa6b-adf7-4588-bbd1-143831e786c6 | | Contracts | f85cb6f7-33e5-4dc8-b609-ec7212301948 | | Flex | 03a572de-4234-31ed-d344-ababa488f981 |

ValError class

Thrown when an API call fails. Includes the raw response data for debugging.

import { ValError } from "@windowsed1225/valorant-api";

try {
  await api.getPlayerMMR(puuid);
} catch (err) {
  if (err instanceof ValError) {
    console.error(err.name, err.message, err.data);
  }
}

utils namespace

Low-level helpers for cookie and token manipulation.

import { utils } from "@windowsed1225/valorant-api";

utils.parseSetCookie(setCookieHeaders);   // string[] → cookie object
utils.extractTokensFromUri(redirectUri); // URI → { access_token, id_token }
utils.stringifyCookies(cookieObject);    // cookie object → header string

Regions

| Value | Region | | --- | --- | | na | North America | | eu | Europe | | ap | Asia Pacific | | br | Brazil | | kr | Korea | | latam | Latin America |

XMPP (Friends & Presence)

The xmpp namespace provides Valorant's social layer — friends list, presence, and in-game status via the Riot XMPP protocol.

Connect with Cookie Auth

import { xmpp } from "@windowsed1225/valorant-api";

const client = new xmpp.ValorantXmppClient({ autoReconnect: true });

client.on("ready", () => console.log("Connected! PUUID:", client.tokenStorage.puuid));
client.on("presence", (p) => console.log("Presence:", p.jid));
client.on("error", (err) => console.error(err));

await client.login({ ssidCookie: "ssid=...;" });

Connect with QR Code

import qrcode from "qrcode";
import { xmpp } from "@windowsed1225/valorant-api";

const client = new xmpp.ValorantXmppClient({ autoReconnect: false });

client.on("ready", () => console.log("Connected!", client.tokenStorage.puuid));

await client.login({
  onQrCode: async (url) => {
    console.log(await qrcode.toString(url, { type: "terminal", small: true }));
  },
  countryCode: "HK", // set your ISO country code
  pollInterval: 2000,
});

Events

| Event | Payload | Description | | --- | --- | --- | | ready | — | Connected and authenticated | | presence | PresenceOutput | Friend's presence updated | | message | messageOutput | Incoming chat message | | roster | RosterOutput | Friends list loaded | | incomingRequest | — | Friend request received | | error | Error | Connection error |

Friends

const friends = await client.fetchFriends();
await client.sendFriendRequest("PlayerName", "TAG");
await client.acceptFriendRequest(puuid);
await client.sendMessage("gg", jid, domain);

Presence

const presence = new xmpp.Builders.PresenceBuilder()
  .addKeystonePresence(new xmpp.Builders.KeystonePresenceBuilder())
  .addValorantPresence(
    new xmpp.Builders.ValorantPresenceBuilder().setPresence({ /* payload */ })
  );

await client.sendPresence(presence);

Game Data Constants

xmpp.Maps.Ascent         // "/Game/Maps/Ascent/Ascent"
xmpp.Queues.Competitive  // "competitive"
xmpp.Ranks.RADIANT       // 27

Disconnect

client.end();

Disclaimer

This library uses Riot Games' internal (private) API endpoints. It is not affiliated with or endorsed by Riot Games. Use at your own risk — your account may be subject to restrictions if Riot's terms of service are violated.

License

MIT