@phxgg/kick.js

A JavaScript/TypeScript client for the Kick.com public API.

[!WARNING] This project is in early development. The API may change significantly between releases.

Installation

npm install @phxgg/kick.js

Table of contents

• Setup
• OAuth
• Users
• Channels
• Livestreams
• Categories
• Chat
• Channel Rewards
• Moderation
• KICKs
• Event Subscriptions
• Webhooks
• Error handling

Setup

import { KickClient } from '@phxgg/kick.js';

const client = new KickClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'https://yourapp.com/oauth/callback', // required for OAuth flows
});

Once you have a user token (obtained via OAuth), attach it to the client:

client.setToken({
  access_token: 'USER_ACCESS_TOKEN',
  refresh_token: 'USER_REFRESH_TOKEN',
  token_type: 'bearer',
  expires_in: 3600,
  scope: 'user:read channel:read',
});

After setToken is called, the client automatically fetches the authenticated user in the background and registers itself in the global event manager so that webhook events can be routed to it.

OAuth

Generate authorization URL

Redirect your user to this URL to begin the authorization flow. Store the codeVerifier in the session — you'll need it in the next step.

const { url, codeVerifier } = await client.oauth.generateAuthorizeURL();
// redirect user to `url`

Exchange code for token

const token = await client.oauth.exchangeToken(code, codeVerifier);
client.setToken(token);

Generate an app token (client credentials)

Use this for API calls that don't require a user context.

const appToken = await client.oauth.generateAppToken();
client.appToken = appToken;

Refresh a token

const refreshed = await client.oauth.refreshToken(token.refresh_token);
client.setToken(refreshed);

Revoke a token

import { TokenHintType } from '@phxgg/kick.js';

await client.oauth.revokeToken(token.access_token, TokenHintType.ACCESS_TOKEN);

Introspect a token

const info = await client.oauth.introspect();
console.log(info.active, info.scope);

Users

Required scope: user:read

// Fetch the authenticated user
const me = await client.users.me();
console.log(me.name, me.email, me.userId);

// Fetch specific users by ID
const users = await client.users.fetch([123, 456]);

Channels

Required scope: channel:read (read), channel:write (update)

// Fetch by slug
const channel = await client.channels.fetchBySlug('monstercat');

// Fetch by broadcaster user ID
const channel = await client.channels.fetchById(123);

// Fetch multiple at once
const channels = await client.channels.fetch({ slug: ['monstercat', 'kick'] });
// or: client.channels.fetch({ broadcasterUserId: [123, 456] })

// Update the authenticated user's channel
await client.channels.update({
  streamTitle: 'My new stream title',
  categoryId: 15,
  customTags: ['gaming', 'chill'],
});

Livestreams

// Fetch live streams (no scope required)
const streams = await client.livestreams.fetch({
  broadcasterUserId: [123, 456],
  categoryId: 15,
  language: 'en',
  limit: 20,
  sort: 'viewer_count', // or 'started_at'
});

// Total live stream count
const stats = await client.livestreams.fetchStats();
console.log(stats.total_count);

Categories

// v1: fetch all categories
const categories = await client.categories.fetch();

// v2: search with pagination
const results = await client.categoriesV2.search({ query: 'gaming', limit: 10 });

// v2: fetch a single category by ID
const category = await client.categoriesV2.fetch(15);

Chat

Required scope: chat:write (send), moderation:chat_message:manage (delete)

import { ChatMessageType } from '@phxgg/kick.js';

// Send a bot message (default)
const message = await client.chat.send({
  content: 'Hello from kick.js!',
});

// Send a message as the authenticated user to a specific channel
const message = await client.chat.send({
  content: 'Hello!',
  broadcasterUserId: 123,
  type: ChatMessageType.USER,
});

// Reply to a message
const reply = await client.chat.send({
  content: 'Nice catch!',
  replyToMessageId: 'some-message-id',
});

// Delete a message
await client.chat.delete('some-message-id');

Channel Rewards

Required scope: channel:rewards:read (read), channel:rewards:write (create / update / delete)

// Fetch all rewards for the authenticated broadcaster
const rewards = await client.channelRewards.fetch();

// Create a reward
const reward = await client.channelRewards.create({
  title: 'Hydrate!',
  cost: 500,
  description: 'Make the streamer drink water.',
  isEnabled: true,
  isUserInputRequired: false,
});

// Update a reward
await client.channelRewards.update(reward.id, {
  cost: 1000,
  isPaused: false,
});

// Delete a reward
await client.channelRewards.delete(reward.id);

// Fetch redemptions (defaults to pending)
const redemptions = await client.channelRewards.getRedemptions({
  rewardId: reward.id,
  status: 'pending',
});

// Accept / reject redemptions (up to 25 per call)
await client.channelRewards.acceptRedemptions({ ids: [redemptions[0].id] });
await client.channelRewards.rejectRedemptions({ ids: [redemptions[1].id] });

Moderation

Required scope: moderation:ban

// Ban a user permanently
await client.moderation.banUser({
  broadcasterUserId: 123,
  userId: 456,
  reason: 'Spamming',
});

// Timeout a user (duration in minutes, max 10080 = 7 days)
await client.moderation.timeoutUser({
  broadcasterUserId: 123,
  userId: 456,
  duration: 10,
  reason: 'Cool off.',
});

// Remove a ban or timeout
await client.moderation.removeBan({
  broadcasterUserId: 123,
  userId: 456,
});

KICKs

Required scope: kicks:read

// Fetch the KICKs leaderboard for the authenticated broadcaster
const leaderboard = await client.kicks.fetchLeaderboard({ top: 10 });

Event subscriptions

Required scope: events:subscribe

Subscribe your app to receive webhook events for a broadcaster.

import { WebhookEvents } from '@phxgg/kick.js';

// Subscribe to a single event
await client.events.subscribe({
  broadcasterUserId: 123,
  event: { name: WebhookEvents.CHAT_MESSAGE_SENT, version: 1 },
});

// Subscribe to multiple events at once
await client.events.subscribeMultiple({
  broadcasterUserId: 123,
  events: [
    { name: WebhookEvents.CHANNEL_FOLLOWED, version: 1 },
    { name: WebhookEvents.LIVESTREAM_STATUS_UPDATED, version: 1 },
  ],
});

// List active subscriptions
const subs = await client.events.fetch();

// Unsubscribe
await client.events.unsubscribe(subs[0].id);
await client.events.unsubscribeMultiple(subs.map((s) => s.id));

Webhooks

kick.js provides framework-agnostic primitives so you can handle Kick webhook deliveries in any HTTP server.

Verify & dispatch

import { verifyKickSignature, dispatchWebhookEvent, getKickPublicKey } from '@phxgg/kick.js';

// Inside your POST /webhooks/kick handler:
const publicKey = await getKickPublicKey(); // cached, refreshes every hour

const valid = verifyKickSignature({
  messageId: req.headers['kick-event-message-id'],
  messageTimestamp: req.headers['kick-event-message-timestamp'],
  rawBody: rawBody, // Buffer or string — must be read before JSON.parse
  signature: req.headers['kick-event-signature'],
  publicKey,
});

if (!valid) return res.sendStatus(403);

const eventType = req.headers['kick-event-type'];
const payload = JSON.parse(rawBody);

// Route to whichever KickClient is registered for this broadcaster
dispatchWebhookEvent(eventType, payload);

res.sendStatus(200);

Per-client listeners

After calling client.setToken(), the client registers itself so that dispatchWebhookEvent can route events to the correct instance. Use client.on() to react to events:

import { WebhookEvents } from '@phxgg/kick.js';

client.on(WebhookEvents.CHAT_MESSAGE_SENT, (payload) => {
  console.log(`${payload.sender.username}: ${payload.content}`);
});

client.on(WebhookEvents.CHANNEL_FOLLOWED, (payload) => {
  console.log(`${payload.follower.username} followed the channel!`);
});

client.on(WebhookEvents.LIVESTREAM_STATUS_UPDATED, (payload) => {
  console.log('Stream is now', payload.is_live ? 'live' : 'offline');
});

// Remove a listener
client.off(WebhookEvents.CHAT_MESSAGE_SENT, myListener);

// Remove all listeners
client.removeAllListeners();

// Clean up the client and deregister it from the event manager
client.destroy();

Supported webhook events

| Event | Constant | | ----------------------------------- | ------------------------------------------------- | | chat.message.sent | WebhookEvents.CHAT_MESSAGE_SENT | | channel.followed | WebhookEvents.CHANNEL_FOLLOWED | | channel.subscription.new | WebhookEvents.CHANNEL_SUBSCRIPTION_NEW | | channel.subscription.renewal | WebhookEvents.CHANNEL_SUBSCRIPTION_RENEWAL | | channel.subscription.gifts | WebhookEvents.CHANNEL_SUBSCRIPTION_GIFTS | | channel.reward.redemption.updated | WebhookEvents.CHANNEL_REWARD_REDEMPTION_UPDATED | | livestream.status.updated | WebhookEvents.LIVESTREAM_STATUS_UPDATED | | livestream.metadata.updated | WebhookEvents.LIVESTREAM_METADATA_UPDATED | | moderation.banned | WebhookEvents.MODERATION_BANNED | | kicks.gifted | WebhookEvents.KICKS_GIFTED |

Error handling

All methods throw typed errors on non-2xx responses:

import {
  UnauthorizedError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
  BadRequestError,
  MissingScopeError,
  NoTokenSetError,
} from '@phxgg/kick.js';

try {
  const me = await client.users.me();
} catch (err) {
  if (err instanceof UnauthorizedError) {
    // token expired — refresh and retry
  } else if (err instanceof MissingScopeError) {
    // the token is missing a required scope
  } else if (err instanceof RateLimitError) {
    // back off and retry
  } else {
    throw err;
  }
}

Example app

A full Express + MongoDB reference implementation is available in examples/express-app.

License

MIT