TypeScript / JavaScript SDK

Use the official @credits-dev/sdk for type-safe access to the Credits API. Works in Node.js (v18+) and the browser. Authenticate with your API key from the dashboard.

Install

npm install @credits-dev/sdk
# or
pnpm add @credits-dev/sdk
# or
yarn add @credits-dev/sdk

Initialize the client

Create a client with your API key. Get your key from the dashboard → API Keys. Use baseUrl only for a custom API host (e.g. local dev).

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

const client = new CreditsClient({
  apiKey: process.env.CREDITS_API_KEY!,
  baseUrl: "https://api.credits.dev", // optional, default
});

Accounts

List accounts, get one by accountId or externalId, create an account, and fetch balance.

// List all accounts
const { accounts } = await client.listAccounts();

// Get by internal ID or your external ID
const account = await client.getAccount({ accountId: "acc_abc123" });
const same = await client.getAccount({ externalId: "user_456" });

// Create account (e.g. on user signup)
const { account: newAccount } = await client.createAccount({
  name: "Alice",
  externalId: "user_456",
  email: "alice@example.com",
  metadata: { plan: "free" },
});

// Get balance (reserved + available)
const balance = await client.getBalance({ externalId: "user_456" });
console.log("Available credits:", balance.available);

Add and deduct credits

Add credits after a purchase or grant; deduct for simple spend (no reservation).

// Add credits (e.g. after payment)
const addRes = await client.addCredits({
  externalId: "user_456",
  amount: 1000,
  description: "Monthly plan purchase",
  paymentMethod: "stripe",
  metadata: { paymentId: "pay_xxx" },
});

// Deduct credits
const deductRes = await client.deductCredits({
  accountId: addRes.accountId,
  amount: 50,
  description: "API usage",
  metadata: { action: "chat" },
});

Reservations (recommended for LLM calls)

Reserve credits before an LLM call, then confirm with actual usage or cancel to release.

// 1. Reserve before the LLM call
const { reservation } = await client.createReservation({
  externalId: "user_456",
  amount: 500,
  metadata: { requestId: "req_123" },
});

// 2. Call your LLM...
// const tokensUsed = await callLLM();

// 3. Confirm with actual amount (or cancel)
await client.confirmReservation(reservation.id, 420);
// or release unused: await client.cancelReservation(reservation.id);

Usage tracking

Record usage for an account (e.g. after confirming a reservation). Use transactionId from confirm when recording customer usage.

// After confirming a reservation you get a transactionId
const confirmRes = await client.confirmReservation(reservation.id, 420);

// Record usage linked to that transaction (customer context)
await client.recordUsage({
  context: "customer",
  transactionId: confirmRes.transactionId,
  accountId: confirmRes.accountId, // or externalId
  modelId: "gpt-4o",
  usageType: "text",
  inputTokens: 1000,
  outputTokens: 420,
  description: "Chat completion",
});

// List usage or get summary
const usage = await client.getUsage({ externalId: "user_456", context: "customer" });
const summary = await client.getUsageSummary("customer");

Plans and transactions

List plans, assign a plan to an account, list transactions (paginated), and create manual transactions.

// Plans
const { plans } = await client.listPlans();
await client.assignPlanToAccount({
  externalId: "user_456",
  planId: plans[0].id,
  startMode: "immediate",
});

// Transactions (paginated: items + pagination)
const { items, pagination } = await client.listTransactions({
  accountId: "acc_abc123",
  limit: 20,
  offset: 0,
});

// Manual transaction (e.g. refund)
await client.createTransaction({
  externalId: "user_456",
  amount: 100,
  type: "credit",
  description: "Refund",
  metadata: { reason: "support" },
});

Types and exports

Import types for responses and request params. All types are exported from the main package.

import {
  CreditsClient,
  type Account,
  type BalanceResponse,
  type Transaction,
  type Reservation,
  type UsageRecord,
  type PaginatedResult,
} from "@credits-dev/sdk";

For full endpoint details and REST/Python examples, see the API reference. For a step-by-step integration, start with the Get Started guide.