Guide

A leaderboard on your website, start to finish

Never written against an API before? This walks through the whole thing. You need Node.js 18 or newer, a server you own with nyx+ active, and the Progression plugin turned on there.

1. Get your key and your server id

Create a key on your nyx profile page. Your server id is in the dashboard address when you open the server, or ask the API itself:

Terminal

$ curl https://api.nyx.cool/v1/guilds \
    -H "Authorization: Bearer nyx_live_..."

2. Try it as a script

Save this as leaderboard.js and run it with node leaderboard.js. It prints your top ten.

leaderboard.js

// Paste your own values here.
const KEY = 'nyx_live_...';
const SERVER = '1467281625954914369';

const response = await fetch(
  `https://api.nyx.cool/v1/guilds/${SERVER}/progression/leaderboard?limit=10`,
  { headers: { authorization: `Bearer ${KEY}` } },
);

const { members } = await response.json();
for (const member of members) {
  console.log(`#${member.rank}  level ${member.level}  ${member.userId}`);
}

3. Put it on your site, without leaking your key

Never put the key in code that runs in visitors' browsers. Anyone can open the browser's developer tools and read it.

Instead, your own server fetches from nyx with the key and hands the result to your page. Any backend can do this; the one below is plain Node with no dependencies.

server.js

import { createServer } from 'node:http';

const KEY = process.env.NYX_API_KEY; // keep it out of the code
const SERVER = '1467281625954914369';

createServer(async (request, response) => {
  if (request.url !== '/leaderboard') {
    response.writeHead(404).end();
    return;
  }

  // The key stays here, server-side. Visitors never see it.
  const upstream = await fetch(
    `https://api.nyx.cool/v1/guilds/${SERVER}/progression/leaderboard?limit=10`,
    { headers: { authorization: `Bearer ${KEY}` } },
  );

  response.writeHead(upstream.status, { 'content-type': 'application/json' });
  response.end(await upstream.text());
}).listen(8787);

Start it with the key in the environment, then your webpage fetches your own endpoint:

Terminal

$ NYX_API_KEY=nyx_live_... node server.js

On your page

const { members } = await fetch('/leaderboard').then((r) => r.json());
// render however you like - it is your site

Cache the result

Responses barely change between requests, so keep them for a minute on your side. A cached minute costs one API call however many people visit, which keeps you well under the rate limit.