faceit-elo-bot

FACEIT CS2 elo / peak elo for Twitch chat bots — Fossabot, Nightbot, StreamElements.

All routes respond with JSON, with one plain-text chat line when format=text is set, or in your own wording when format is a template. Every route accepts a FACEIT nickname or a player_id (the stable UUID that never changes).

GET /elo

Current elo/level + rolling-window stats.

querynickname or player_id (single token); falls back to default. Inline window supported: nick:24, :24, nick:
defaultfallback player for argument-less calls
hwindow in hours, 1–720 (default 12); an inline nick:h wins
gameFACEIT game id (default cs2)
formattext → one ready-to-print chat line instead of JSON; a value with {} is your own template

Example: /elo?query=chyna- · /elo?query=chyna-:24

GET /maxelo

All-time highest elo (via Faceit Analyser).

querynickname or player_id (single token); falls back to default
defaultfallback player for argument-less calls
gamegame id (default cs2): cs2, csgo, dota2, ow2, deadlock
formattext → one ready-to-print chat line instead of JSON; a value with {} is your own template

Example: /maxelo?query=chyna-

GET /playerid

Resolve a nickname to its stable FACEIT player_id.

querynickname (single token); falls back to default
defaultfallback player for argument-less calls
formattext → one ready-to-print chat line instead of JSON; a value with {} is your own template

Example: /playerid?query=chyna-

Ready-to-use commands

With format=text the endpoint returns the finished line, so the command is a plain fetch — no JSON parsing in the bot:

chyna- • ELO: 2270 • LVL: 10 • 720h: +140 [17W/12L] • K/D 1.1

Paste into chat, then replace YOUR_NICK with your FACEIT nickname. Bare !elo shows your stats; !elo someone looks up another player.

Tip: drop your player_id in place of the nickname so the command survives a rename — grab it from /playerid.

Fossabot

!addcom !elo $(customapi https://faceit.redins1de.xyz/elo?format=text&query=$(querystring)&default=YOUR_NICK&h=12)
!addcom !maxelo $(customapi https://faceit.redins1de.xyz/maxelo?format=text&query=$(querystring)&default=YOUR_NICK)

Nightbot

!addcom !elo $(urlfetch https://faceit.redins1de.xyz/elo?format=text&query=$(querystring)&default=YOUR_NICK&h=12)
!addcom !maxelo $(urlfetch https://faceit.redins1de.xyz/maxelo?format=text&query=$(querystring)&default=YOUR_NICK)

StreamElements

!command add !elo ${customapi.https://faceit.redins1de.xyz/elo?format=text&query=${queryescape ${1:}}&default=YOUR_NICK&h=12}

Your own wording

Any format value containing a { is a template over the JSON field names, so the wording is yours and the bot still parses nothing:

https://faceit.redins1de.xyz/elo?query=chyna-&h=720&format={nickname}:+{elo}+({eloStr}+in+{h}h)+{win}W/{lose}L
chyna-: 2270 (+140 in 720h) 17W/12L

{name} is that field's value (? when it could not be determined), {{ and }} print a brace, and an unknown name answers with the list of names that would have worked — so a typo shows up on the first call.

Names are exactly the JSON's: nested ones fully qualified, or bare when the top level does not claim them. {elo} is the current elo, the window swing is {window.elo} or {eloStr}, and {h} works for {window.hours}.

/elonickname, elo, level, window.hours (hours, h), window.elo, window.win (win), window.lose (lose), window.eloStr (eloStr), window.kd (kd), window.source (source)
/maxelonickname, maxelo
/playeridnickname, player_id
/versionversion

The template rides in a query string, so URL-encode it: + or %20 for a space, %26 for &. UTF-8 is fine — the answer is text/plain; charset=utf-8. Fossabot's $(customapi) takes one URL token, so use + rather than a raw space.

Fossabot can encode it for you, which keeps the template readable inside the command — $(urlencode <text>). Mind the two closing parens, one per variable — and note that a ( or ) inside the template would close the variable early, so a template with parens has to be pre-encoded (%28 / %29):

!addcom !elo $(customapi https://faceit.redins1de.xyz/elo?query=$(querystring)&default=$(touser)&format=$(urlencode {nickname} ELO {elo} ({eloStr} / {h}h) {win}W/{lose}L))

Don't wrap this in $(eval) on Fossabot

Fossabot allows 50 ms of JavaScript per command (docs), and parsing the JSON there overruns it most of the time — chat then shows [Error: JavaScript execution timed out on remote server.]. Fossabot has no $(urlfetch) either. The format=text commands above run no JavaScript at all, so there is nothing left to time out.

Need more than a template can say (conditionals, arithmetic)? Parse the JSON yourself — on Nightbot, whose $(eval) has a real time budget:

!addcom !elo $(eval const a = $(urlfetch json https://faceit.redins1de.xyz/elo?query=$(querystring)&default=YOUR_NICK&h=12); const w = a.window || {}; const q = function (v) { return v === null ? '?' : v; }; a.error ? a.error : a.nickname + ' • ELO: ' + a.elo + ' • LVL: ' + a.level + ' • ' + q(w.hours) + 'h: ' + w.eloStr + ' [' + q(w.win) + 'W/' + q(w.lose) + 'L]')

Unknown values

Every field inside window comes back null when it could not be determined — never 0, which would look like a real zero. window.eloStr is the display twin of window.elo and reads ? in that case.

window.source says where the numbers came from: stats (everything present), history (the undocumented endpoint was down, so W/L came from the official API and elo/kd are null), or null (nothing determined, or a non-cs2 game).

Caching

Successful responses are cached at the edge to spare the upstream APIs: /elo 30s · /maxelo 1h · /playerid 10m. Errors are never cached. The X-Cache response header shows HIT or MISS.