Docs
Custom code

Points API

Read, spend and add viewers’ points from your own app, server to server.

The Points API lets your own app use your channel’s points: a points casino, a minigame on your website, a Discord bot. Viewers earn points by chatting in your Twitch or Kick chat (set that up under Chat bot → Points). Your app can read a viewer’s balance, take points for a bet and pay out a win.

Use it from a server only: your backend, a serverless function, a bot. Anyone who has the token can give any viewer as many points as they like. Never put it in a web page, a widget or an app that viewers download. Layrs answers no requests from other websites here, so a browser can’t call it anyway.

Points have no money value, in Layrs or in your app: they can’t be bought, sold, paid out or traded for anything of value, and you must not give real-money prizes for them.

Create a token

  1. Open Team (you need to be a manager or the owner).
  2. Under Stream Deck, Companion and your apps, name the token (for example “Casino”), tick Points and untick Live controls if the app doesn’t need them, then press Create token.
  3. Copy the secret into your server’s settings (an environment variable). You won’t see it again. If it leaks, revoke it on Team and create another.

The token works on your channel only. It stops when you revoke it, or when the manager who made it leaves the team or stops being a manager.

Who is who

Viewers are named by their Twitch or Kick user id, not their name: names change, ids don’t. Your app gets the id when the viewer signs in with Twitch or Kick. A Twitch and a Kick account never share points.

A viewer exists here once they chatted (or followed, subbed, cheered or raided) while points were on. The API never creates viewers, so a viewer who typed !forgetme stays forgotten until they chat again. Ask a viewer who isn’t found to say hi in chat first.

The requests

Base address https://layrs.tv/api/points. Every request needs Authorization: Bearer <token>; every POST also Content-Type: application/json and X-Layr: 1. <platform> is twitch or kick, <id> the user id (digits only).

RequestAnswer
GET /api/points{ "currency": "Points", "enabled": true }
GET /api/points/viewers/<platform>/<id>the viewer
POST /api/points/viewers/<platform>/<id>/spend with { "amount": 100, "ref": "bet-42" }the viewer after paying
POST /api/points/viewers/<platform>/<id>/add with { "amount": 250, "ref": "win-42" }the viewer after winning

A viewer looks like { "platform": "twitch", "id": "12826", "login": "nico", "displayName": "Nico", "points": 1250 }. amount is a whole number from 1 to 1,000,000,000; a balance never goes above that.

Spend is all or nothing. It takes the points only if the viewer has them all, in one step, so two bets at once can never spend the same points. Not enough → 409 with code: "not_enough" and nothing changes.

Retries and ref

Every spend and add carries a ref: your own id for that change, up to 64 letters, digits, _, ., : or - (your bet id works). If the network fails and you send it again, Layrs sees the same ref and answers what it answered the first time, without changing the points twice. The same ref for a different change gets 409 ref_reused. A change that failed isn’t remembered, so you can retry it later. Layrs keeps refs for 7 days.

When points are off

If you switch points off, spend answers 409 points_off, so no new bets start. add still works, so a bet already placed can pay out. A viewer who types !forgetme in the middle of a bet is gone: their payout gets 404 and is lost, which is what they asked for.

Errors

Errors are { "error": "<a sentence for people>", "code": "<for your code>" }:

StatuscodeMeans
404unknown_viewerThat viewer has no points here yet. They get some by chatting.
409points_offPoints are switched off on this channel.
409not_enoughThat viewer doesn’t have enough points.
409ref_reusedThat ref was already used for a different change.
400A bad platform, id, amount or ref
401The token is wrong, revoked or has no Points
403X-Layr: 1 is missing, or the request came from a web page
429Too many requests: wait for Retry-After seconds (20 a second per token, after a burst of 60)

Example

A coin flip in Node 18 or newer. LAYRS_TOKEN is the token; viewerId comes from your Twitch sign-in.

JavaScript
const LAYRS = 'https://layrs.tv/api/points';
const headers = { Authorization: `Bearer ${process.env.LAYRS_TOKEN}`, 'Content-Type': 'application/json', 'X-Layr': '1' };

async function points(viewerId, kind, amount, ref) {
  const res = await fetch(`${LAYRS}/viewers/twitch/${viewerId}/${kind}`, { method: 'POST', headers, body: JSON.stringify({ amount, ref }) });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error), { code: body.code });
  return body; // { platform, id, login, displayName, points }
}

export async function coinFlip(viewerId, stake) {
  const bet = crypto.randomUUID();
  await points(viewerId, 'spend', stake, `bet-${bet}`); // throws not_enough
  const won = Math.random() < 0.5;
  const viewer = won ? await points(viewerId, 'add', stake * 2, `win-${bet}`) : null;
  return { won, viewer };
}

If the payout fails on the network, send the same win-… ref again: it pays once.

Show the win on stream and in chat

The same token can do more if you tick more when you create it. With Live controls, your app sends a custom event to your overlays with emit; a custom widget shows it with layr.on('custom'). With Chat, the Layrs chat bot says a line in your chat (where the bot is on). Both go through the control request with the id of one of your overlays:

JavaScript
const OVERLAY = process.env.LAYRS_OVERLAY_ID; // the last part of the editor address

async function control(action) {
  const res = await fetch(`https://layrs.tv/api/control/${OVERLAY}`, { method: 'POST', headers, body: JSON.stringify({ action }) });
  if (!res.ok) console.warn('Layrs:', (await res.json()).error); // a missed shout-out isn't worth failing the bet
}

async function announce(viewer, amount) {
  await control({ a: 'emit', name: 'casino:win', data: { name: viewer.displayName, amount } });
  await control({ a: 'say', text: `🎰 ${viewer.displayName} won ${amount} points!` });
}

And in the custom widget:

JavaScript
layr.on('custom', ({ name, data }) => {
  if (name === 'casino:win') show(`${data.name} won ${data.amount.toLocaleString()}!`);
});

The bot says at most a few lines a minute for your tokens together, so announce big wins, not every spin.