Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mascot.bot/llms.txt

Use this file to discover all available pages before exploring further.

The SDK is published to npm.mascot.bot, a private registry — it is not on npmjs.com. You need a Mascotbot API key to install and to run.

​
1. Get an API key

Create a key at app.mascot.bot/api-keys. Keys are prefixed by environment:
PrefixWhere it worksMetering
mascot_dev_…localhost, *.localhost, 127.0.0.1, private networks onlyDevelopment meters — no billing, tamper-tolerant
mascot_pub_…Your registered public domainsProduction meters — tamper detection active
A mascot_dev_… key sent from a public origin is rejected by design, and a mascot_pub_… key from localhost is rejected too. Use the matching key for the environment. See Licensing & keys for the full model.

​
2. Point npm at the private registry

Add a .npmrc at the root of your project: 
@mascotbot:registry=https://npm.mascot.bot/
//npm.mascot.bot/:_authToken=mascot_xxx
Never commit .npmrc with the auth token. Add it to .gitignore and inject the token from a CI secret / environment variable instead.

​
3. Install the package

pnpm add @mascotbot/react
@rive-app/webgl2 (and @rive-app/react-webgl2 for React) is an optional peer dependency of the /rive subpaths. Install it only if you render an avatar; the audio pipeline alone does not need it. npm and yarn work the same way once the registry line is in .npmrc.

​
4. Configure the client

Pass configuration to <MascotProvider> (React) or LipsyncClient.init (vanilla):
OptionTypeDefaultNotes
apiKeystringrequiredmascot_dev_… (localhost) or mascot_pub_… (production)
userIdstringrandomStable per-user id for MAU billing attribution
licenseEndpointstringhttps://license.mascot.botOverride only if Mascotbot points you elsewhere
devModebooleanauto-detectForced on for localhost, *.localhost, 127.0.0.1, private IPs. Skips the Origin allow-list and routes events to dev meters.
fingerprintHashstringhashed UA + hardwareOverride to control session attribution
"use client";
import { MascotProvider } from "@mascotbot/react";

export default function Layout({ children }: { children: React.ReactNode }) {
  return <MascotProvider apiKey={process.env.NEXT_PUBLIC_MASCOT_KEY!}>{children}</MascotProvider>;
}
Production publishable keys (mascot_pub_…) are safe in client bundles — they are scoped to your allow-listed origins. Keep standing third-party keys (TTS, OpenAI, ElevenLabs) on the server.

​
TypeScript

All packages ship .d.ts. Public types are re-exported from each root entry point — you do not need to install lipsync-core separately just for types if you depend on lipsync-react.

​
Next

Quickstart

A working avatar in a few lines.

Licensing & keys

Dev vs production, session lifecycle, error codes.