chaturbapi

chaturbapi

TypeScript library to interact with the Chaturbate Affiliate API.
Provides a secure and typed way to query clicks, signups, earnings, and tokens.

Installation

npm install chaturbapi
# or
yarn add chaturbapi

Requires Node.js ≥ 18.17.

Basic usage

import { ChaturbAPI } from "chaturbapi";

const api = new ChaturbAPI("your_username", "your_token", {
  timeoutMs: 10_000,
  retries: 2,
});

const stats = await api.getStats({
  range: "last_7_days",
  breakdown: "day",
});

console.log(stats.rows);

Expected response (AffiliateStatsResponse)

{
  "range": "last_7_days",
  "breakdown": "day",
  "program": "affiliate",
  "columns": ["date", "clicks", "signups", "revenue"],
  "rows": [
    { "date": "2025-10-01", "clicks": 123, "signups": 12, "revenue": 45.5 },
    { "date": "2025-10-02", "clicks": 110, "signups": 9, "revenue": 33.7 }
  ],
  "totals": { "clicks": 233, "signups": 21, "revenue": 79.2 }
}

Client options

new ChaturbAPI(username, token, {
  baseURL: "https://chaturbate.com", // optional
  timeoutMs: 12000,                  // request timeout
  retries: 2,                        // automatic retries
  headers: { "User-Agent": "chaturbapi/1.0" }, // custom headers
  beforeRequest: (url) => console.log("➡️", url),
  afterResponse: (url, status) => console.log("⬅️", status)
});

Available methods

getStats(query?: AffiliateStatsQuery)

Retrieves affiliate statistics.

Parameters

Name	Type	Description
range	"today" | "yesterday" | "last_7_days" | "last_30_days" | "this_month" | "last_month" | "this_year"	Date range.
breakdown	"none" | "day" | "month" | "program"	Level of breakdown.
program	"affiliate" | "revshare" | "ppv" | "tokens"	Program type.

Returns

Promise<AffiliateStatsResponse>

Real-time Events (EventsClient)

The EventsClient class provides a persistent connection to the Chaturbate Events API, allowing you to receive live notifications such as user entries, tips, chat messages, and more.

Basic usage

import { EventsClient } from "chaturbapi";

const events = new EventsClient("your_username", "your_events_token");

// Listen for specific events
events.on("broadcastStart", ({ broadcaster, user }) => {
  console.log(`📡 ${broadcaster} started streaming`);
});

events.on("tip", ({ user, tip }) => {
  console.log(`💰 ${user.username} sent ${tip.tokens} tokens`);
});

events.on("chatMessage", ({ user, message }) => {
  console.log(`💬 ${user.username}: ${message.message}`);
});

// Generic listener
events.on("event", (e) => console.log(`[Raw Event]`, e));

// Handle errors
events.on("error", (err) => console.error("Stream error:", err));

// Start listening
events.start();

Supported events

Event	Description	Payload Type
broadcastStart	Broadcaster started streaming	BroadcastEvent
broadcastStop	Broadcast ended	BroadcastEvent
userEnter	A user entered the room	BroadcastEvent
userLeave	A user left the room	BroadcastEvent
follow	User followed the broadcaster	BroadcastEvent
unfollow	User unfollowed the broadcaster	BroadcastEvent
fanclubJoin	User joined the fanclub	BroadcastEvent
chatMessage	Public chat message	ChatMessageEvent
privateMessage	Private message	PrivateMessageEvent
tip	User sent a tip	TipEvent
roomSubjectChange	Broadcaster updated room subject	RoomSubjectChangeEvent
mediaPurchase	Media (photo/video) purchased	MediaPurchaseEvent

Strongly typed payloads

Each event type has its own structure. Examples:

events.on("tip", ({ broadcaster, user, tip }) => {
  // user.username, tip.tokens, tip.isAnon, tip.message
});

events.on("chatMessage", ({ broadcaster, user, message }) => {
  // user.username, message.message, message.color
});

events.on("mediaPurchase", ({ broadcaster, user, media }) => {
  // media.name, media.tokens, media.type
});

These types are automatically inferred in TypeScript, so you get full IntelliSense support per event type.

Main types

AffiliateStatsResponse

interface AffiliateStatsResponse {
  range: string;
  breakdown: string;
  program?: string;
  columns: string[];
  rows: Record<string, any>[];
  totals?: Record<string, any>;
}

AffiliateStatsQuery

interface AffiliateStatsQuery {
  range?: string;
  breakdown?: string;
  program?: string;
}

Events

ChaturbAPI implements a simple typed EventEmitter.

api.on("statsUpdated", (data) => {
  console.log("Updated stats:", data);
});

api.on("error", (err) => {
  console.error("API error:", err);
});

Event	Description
statsUpdated	Triggered when a successful response is received.
error	Triggered when a network or HTTP error occurs.

Error handling

Network or API errors throw an HTTPError exception:

import { HTTPError } from "chaturbapi";

try {
  await api.getStats({ range: "today" });
} catch (err) {
  if (err instanceof HTTPError) {
    console.error("HTTP failure:", err.status, err.body);
  } else {
    console.error("Unexpected error:", err);
  }
}

Example use cases

1. Weekly summary

const stats = await api.getStats({ range: "last_7_days", breakdown: "day" });
console.table(stats.rows);

2. Log API errors

api.on("error", (e) => {
  // Send to your monitoring system
  console.error("[ALERT] Chaturbate API failure:", e);
});

3. Monthly dashboard totals

const { totals } = await api.getStats({ range: "this_month" });
console.log("Clicks:", totals?.clicks, "Revenue:", totals?.revenue);

4. Run multiple queries in parallel

const [today, month] = await Promise.all([
  api.getStats({ range: "today" }),
  api.getStats({ range: "this_month" }),
]);

Events summary

Event	Main Properties	Notes
broadcastStart	broadcaster, user	Triggered when stream starts
broadcastStop	broadcaster, user	Triggered when stream stops
userEnter	broadcaster, user	User enters room
userLeave	broadcaster, user	User leaves room
follow	broadcaster, user	User followed broadcaster
unfollow	broadcaster, user	User unfollowed broadcaster
fanclubJoin	broadcaster, user	User joined fanclub
chatMessage	broadcaster, user, message	Public chat message
privateMessage	broadcaster, user, message	Private message (to broadcaster)
tip	broadcaster, user, tip	User sent tokens
roomSubjectChange	broadcaster, user, subject	Room subject updated
mediaPurchase	broadcaster, user, media	Media (photo/video) purchased

All events contain at least broadcaster and user fields.

Example: Using ChaturbAPI and EventsClient together

import { ChaturbAPI, EventsClient } from "chaturbapi";

const api = new ChaturbAPI("user", "token");
const events = new EventsClient("user", "event_token");

const stats = await api.getStats({ range: "today" });
console.log("Current clicks:", stats.totals?.clicks);

events.on("tip", ({ user, tip }) => {
  console.log(`${user.username} tipped ${tip.tokens} tokens`);
});

events.start();

License

MIT © Nikita Contreras