Node SDK

Use @withlocus/credits on your server to call tools and bill for usage in Locus Pro Enterprise. The SDK handles idempotency, retries, and cost headers, so your code can focus on the result.

How it works

The SDK holds your secret key and stays on your server. It gives browsers and agents their own limited credentials: a short-lived user token for the widget, and a scoped agent key for an agent.

Credential	Lives in	Use it for
Secret key (`lcr_…`)	Your server	Everything on this page
User token	Your customer’s browser	The billing widget
Agent key (`lcac_…`)	Your agent runtime	Tool calls within set limits

Make a call

Install the SDK

The current release of @withlocus/credits is 0.5.2.

Terminal

npm install @withlocus/credits

Call an enabled tool

Enable tavily/search in your workspace and fund the balance, then:

Search and read the cost

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

const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!);

try {
  const result = await locus.callJson("tavily/search", {
    query: "latest developments in agent payments",
  });

  console.log(result.data);
  console.log(result.cost.credits);
  console.log(result.cost.balance);
} catch (error) {
  console.error("Locus call failed", error);
  throw error;
}

What the SDK does

You want to	Use
Call a tool	`callJson()`, `callText()`, or `call()` for a raw, streamable response
Charge a customer for a call	The `user` call option
Check pool and customer balances	`balance()`
Read usage	`ledger()`, filtered by customer and attribution
Move credits to or from a customer	`allocate()` and `deallocate()`
Sell credits through Stripe Checkout	`topup()`
Give the widget a user token	`endUserToken()`
Create and manage agent keys	`agentConnections`
Connect a model framework	Framework MCP presets

Call a tool

Pass a provider/endpoint slug and the provider’s request body. To find a slug by capability, use MCP search_apis or the tool search API; version 0.5.2 has no search helper.

Every call returns cost.credits and cost.balance as exact decimal strings.
The SDK makes one idempotency key per call and reuses it during retries. If your application retries after a restart, pass the original idempotencyKey.
A streamed model response is charged after it finishes, so 0.5.2 reports its cost as "0". Read the real charge from the stream’s closing event or the call status. See Inference and streaming.
Errors are typed: LocusInsufficientCreditsError for a 402, LocusRateLimitError when rate limits persist after retries, and LocusApiError for other failures.

Bill your customers

Each customer can have their own balance. You fund it by selling credits through Stripe Checkout or by moving credits from your platform pool. Calls with the user option charge that balance at your price.

Charge a customer

const result = await locus.callJson(
  "tavily/search",
  { query: "agent payments" },
  { user: "user_123", attribution: { project: "prospect-research" } },
);

attribution tags the ledger entry so you can filter usage later with ledger().
Transfers cannot overdraw the source account.
topup() funds the platform pool, or a customer when you pass externalUserId. See Funding & billing.

Agent keys

The SDK calls agent keys Agent Connections. Create one on your trusted backend with a secret key that has both credentials:manage and credits:move:

Create a scoped connection

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

Save connection.credential securely; it is shown only on creation or rotation. Your agent runtime passes it to its own LocusCredits client. Use mode: "end_user" with externalUserId to bind a key to one customer. Manage keys with list(), get(id), rotate(id), and revoke(id). Tool sets and per-key pricing overrides are available in the API and dashboard, but not in the 0.5.2 typed helper. See Agent keys for scope and budgets.

Framework MCP presets

Presets turn a connection into the configuration your framework expects:

Framework presets

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

openAIResponsesMcpTool(connection);
vercelAIMcpTransport(connection);
langChainMcpServer(connection);

See Framework integrations for every supported framework. Mint a short-lived token for the widget from an authenticated server route:

Mint a browser token

const { token, expiresAt } = await locus.endUserToken(currentUser.id);

Derive the user ID from your server session. The browser packages also export fetchCatalog to show customers their allowed tools and final prices. See Render the provider catalog.

Client options

Most applications only need the credential. These options change the defaults:

Option	Default	Purpose
`baseUrl`	`https://api.paywithlocus.com`	API origin
`maxRetries`	`2`	Retries for rate limits, server errors, and network failures
`timeoutMs`	`120000`	Timeout per attempt

See the API reference for complete request and response contracts.

Next steps

Widget

Show customers their balance and let them add credits.

Agent keys

Give an agent a scoped key and budget.

Model inference

Pay for model calls from the same balance.

Funding & billing

Choose how customer balances are funded.

Getting started

Build with Locus Pro

Connect agents

Pricing & plans

Funding & billing

Developer tools

Catalog directory

Testing

How it works

Make a call

What the SDK does

Call a tool

Bill your customers

Agent keys

Framework MCP presets

Power the widget

Client options

Next steps

Widget

Agent keys

Model inference

Funding & billing

​How it works

​Make a call

​What the SDK does

​Call a tool

​Bill your customers

​Agent keys

​Framework MCP presets

​Power the widget

​Client options

​Next steps

Widget

Agent keys

Model inference

Funding & billing

How it works

Make a call

What the SDK does

Call a tool

Bill your customers

Agent keys

Framework MCP presets

Power the widget

Client options

Next steps