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.
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
- Open Team (you need to be a manager or the owner).
- 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.
- 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).
| Request | Answer |
|---|---|
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>" }:
| Status | code | Means |
|---|---|---|
| 404 | unknown_viewer | That viewer has no points here yet. They get some by chatting. |
| 409 | points_off | Points are switched off on this channel. |
| 409 | not_enough | That viewer doesn’t have enough points. |
| 409 | ref_reused | That ref was already used for a different change. |
| 400 | A bad platform, id, amount or ref | |
| 401 | The token is wrong, revoked or has no Points | |
| 403 | X-Layr: 1 is missing, or the request came from a web page | |
| 429 | Too 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.
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:
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:
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.