Get Started

Integrate Credits in a few steps: create an account, add credits, check balance, and optionally use reservations and usage tracking. This guide uses the TypeScript SDK; the same flow works with the REST API.

Prerequisites

An API key from the dashboard (API Keys)
Node.js 18+ (for the SDK) or any HTTP client for REST

Install the SDK: npm install @credits-dev/sdk

Step 1: Create a client

Initialize the SDK with your API key. Prefer environment variables so the key never ships to the client.

import { CreditsClient } from "@credits-dev/sdk";

const client = new CreditsClient({
  apiKey: process.env.CREDITS_API_KEY!,
});

Step 2: Create an account

Create a Credits account when a user signs up. Use your own user ID as externalId so you can reference the account without storing Credits internal IDs.

const { account } = await client.createAccount({
  name: "Alice",
  externalId: "user_abc123",  // your app's user id
  email: "alice@example.com",
});

console.log("Account id:", account.id);

Step 3: Add credits

Add credits after a purchase, grant, or trial. You can use accountId or externalId.

const res = await client.addCredits({
  externalId: "user_abc123",
  amount: 1000,
  description: "Starter credits",
  metadata: { source: "onboarding" },
});

console.log("New balance:", res.balance);

Step 4: Check balance

Before charging for an action, check available (balance minus reserved credits).

const balance = await client.getBalance({ externalId: "user_abc123" });

console.log("Total:", balance.balance);
console.log("Reserved:", balance.reserved);
console.log("Available to use:", balance.available);

if (balance.available < 100) {
  console.log("Low balance — prompt user to top up");
}

Step 5 (optional): Reserve → confirm or cancel

For LLM or other variable-cost operations, reserve a max amount first. After the operation, confirm with the actual amount or cancel to release.

// Before LLM call
const { reservation } = await client.createReservation({
  externalId: "user_abc123",
  amount: 500,
});

// ... run your LLM call, get actual token usage ...

// Confirm with actual amount (e.g. 320 credits used)
const confirmed = await client.confirmReservation(reservation.id, 320);
console.log("Transaction id for usage:", confirmed.transactionId);

// Or cancel if the user aborted: await client.cancelReservation(reservation.id);

Step 6 (optional): Record usage

Link usage to the transaction from a confirmed reservation so you can report costs per account and model. See the Usage Tracking guide for details.

await client.recordUsage({
  context: "customer",
  transactionId: confirmed.transactionId,
  accountId: confirmed.accountId,
  modelId: "gpt-4o",
  usageType: "text",
  inputTokens: 1000,
  outputTokens: 320,
});

Next steps

Plans & Credits — recurring grants and subscriptions
Usage Tracking — full step-by-step for recording and querying usage
SDK reference — all methods and types
API reference — REST endpoints and examples