SDK reference

npm install @withlocus/credits

new LocusCredits(credential: string, options?: LocusCreditsOptions)

import { LocusCredits } from "@withlocus/credits";

const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!, {
  baseUrl: "https://api.paywithlocus.com",
});

call(slug: string, body: unknown, options?: CallOptions): Promise<CallResult>
callRaw(slug: string, body: unknown, options?: CallOptions): Promise<CallResult>
callJson<T = unknown>(slug: string, body: unknown, options?: CallOptions): Promise<ParsedCallResult<T>>
callText(slug: string, body: unknown, options?: CallOptions): Promise<ParsedCallResult<string>>

const res = await locus.callJson(
  "tavily/search",
  { query: "agent payments" },
  { user: "user_123", attribution: { customerId: "cus_42" } },
);

res.data; // upstream provider response (verbatim)
res.cost.credits; // exact decimal string: credits charged
res.cost.balance; // exact decimal string: balance remaining
res.cost.baseUsd; // exact decimal string, secret-key calls only

const connection = await locus.agentConnections.create({
  name: "research-agent-prod",
  mode: "platform",
  tools: { enable: ["tavily/search", "firecrawl/scrape"] },
  maxCreditsPerCall: "250",
  maxCreditsPerLoop: "1500",
  expiresIn: "30d",
});

connection.credential; // full lcac_ value, returned only now
connection.mcp.url;
connection.mcp.headers.Authorization;

agentConnections.create(input: CreateAgentConnectionInput): Promise<AgentConnectionWithCredential>
agentConnections.list(): Promise<AgentConnection[]>
agentConnections.get(id: string): Promise<AgentConnection>
agentConnections.rotate(id: string): Promise<AgentConnectionWithCredential>
agentConnections.revoke(id: string): Promise<AgentConnection>

const agent = new LocusCredits(process.env.LOCUS_AGENT_CONNECTION!, {
  baseUrl: "https://api.paywithlocus.com",
});

const result = await agent.callJson(
  "tavily/search",
  { query: "agent payment infrastructure" },
  { loopId: "run_42" },
);

import {
  openAIResponsesMcpTool,
  vercelAIMcpTransport,
  langChainMcpServer,
} from "@withlocus/credits";

openAIResponsesMcpTool(connection); // OpenAI Responses tools[]
vercelAIMcpTransport(connection); // createMCPClient({ transport })
langChainMcpServer(connection); // MultiServerMCPClient server entry

balance(user?: string): Promise<BalanceResult>

const pool = await locus.balance(); // your wholesale pool
const user = await locus.balance("user_123"); // one end-user

pool.credits; // exact decimal string, in your denomination
pool.usd; // exact USD decimal string (secret-key calls only)

searchTools(query: string, options?: { limit?: number; user?: string }): Promise<ToolSearchResult>

const tools = await locus.searchTools("current web evidence", {
  limit: 5,
  user: "user_123",
});

tools.results[0].slug; // for example, "router/web-search"
tools.results[0].inputSchema;
tools.results[0].exampleArguments;

ledger(params?: LedgerParams): Promise<LedgerPage>

const page = await locus.ledger({
  user: "user_123",
  category: "burn",
  attribution: { customerId: "cus_42" },
  limit: 50,
});

page.entries; // ledger rows
page.nextCursor; // pass back as { cursor } for the next page

allocate(user: string, args: { credits: string; promo?: boolean; idempotencyKey?: string }): Promise<{ raw: unknown }>
deallocate(user: string, args: { credits: string; idempotencyKey?: string }): Promise<{ raw: unknown }>

await locus.allocate("user_123", { credits: "5000" }); // pool → user
await locus.deallocate("user_123", { credits: "1000" }); // user → pool

topup(args: {
  usd?: string;            // exactly one of usd | credits, as a decimal string
  credits?: string;
  successUrl: string;      // required, absolute HTTP(S) URL
  cancelUrl: string;       // required, absolute HTTP(S) URL
  externalUserId?: string; // omit to fund the platform pool
  metadata?: Record<string, string>; // up to 16 string fields, persisted with the top-up
  idempotencyKey?: string;
}): Promise<TopupResult>

const session = await locus.topup({
  usd: "100.00", // usd is the denomination-safe choice; credit amounts vary in USD value by tenant
  successUrl: "https://yourapp.com/billing?ok=1",
  cancelUrl: "https://yourapp.com/billing",
});
// redirect the buyer to:
session.url; // Locus-hosted Stripe Checkout URL
session.sessionId; // Stripe session id
session.quote; // { feeMode, creditsUsd, credits, feeUsd, totalUsd }
session.bonus; // present when this pool top-up earns volume-bonus credits

const constraints = await locus.topupConstraints();
// { currency, minUsd, maxUsd, incrementUsd, creditsPerDollar, bonusTiers? }

const status = await locus.topupStatus(session.sessionId);
// { sessionId, state: "pending" | "completed" | "expired", paymentStatus }

endUserToken(user: string, options?: EndUserTokenOptions): Promise<EndUserTokenResult>

const { token, expiresAt } = await locus.endUserToken("user_123");

import { fetchCatalog } from "@withlocus/credits-js";

// token minted server-side with locus.endUserToken("user_123")
const catalog = await fetchCatalog(
  {
    baseUrl: "https://api.paywithlocus.com",
    publishableKey: PUBLISHABLE_KEY,
    userToken: token,
  },
  { pageSize: 25 },
);

catalog.version; // "2026-08-14"
catalog.providers[0].id; // stable across branding/price changes
catalog.providers[0].endpoints[0].price; // exact | dynamic | unavailable

import { LocusInsufficientCreditsError } from "@withlocus/credits";

try {
  await locus.call("tavily/search", { query: "hello" }, { user: "user_123" });
} catch (err) {
  if (err instanceof LocusInsufficientCreditsError) {
    // err.topupUrl, when present, is a ready-made hosted top-up link — no need
    // to build one. Fall back to your own flow (widget or Checkout) without it.
    promptTopup(err.requiredCredits, err.availableCredits, err.topupUrl);
  } else {
    throw err;
  }
}