Node SDK

Use @withlocus/credits to call tools and build usage billing in Locus Pro Enterprise. The SDK handles idempotency, retries, and cost headers so your application can work with the result.

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;
}

Use a secret key for trusted server operations and a scoped Agent Connection for agent execution. This package runs on your server. For browser UI, use the widget.

`call()`

Pass a provider/endpoint slug and the provider’s request body.

Method	Result
`callJson()`	Parsed JSON in `data`
`callText()`	Text in `data`
`call()` / `callRaw()`	A raw `Response` in `response`, which you can read or stream

Every method returns cost.credits and cost.balance as exact decimal strings. Secret-key calls also include cost.baseUsd. To bill an end user and tag the call:

Charge a customer

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

Call option	Purpose
`user`	Charge this end-user account at your price; omit for the platform pool
`attribution`	Attach searchable metadata to the ledger entry
`idempotencyKey`	Reuse a key across process restarts or your own retries
`loopId`	Share a run budget across calls; required for per-loop limits
`signal`	Cancel the local request with an `AbortSignal`

The SDK generates one idempotency key per call and reuses it during retries. If your application retries after a restart, supply the original key.

Agent connections

Create an execution credential on your trusted backend using a secret key with 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 revealed only on creation or rotation. Use it in a separate runtime client:

Use the connection in your runtime

const agent = new LocusCredits(process.env.LOCUS_AGENT_CONNECTION!);

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

Use mode: "end_user" with externalUserId to bind a connection to one customer. Account and tool scope are fixed at creation. The API and dashboard also support per-connection pricing overrides, which the 0.5.2 typed helper does not expose. The lifecycle methods are list(), get(id), rotate(id), and revoke(id). Rotation needs both scopes above; listing, reading, and revoking need credentials:manage. See Connect an agent for setup 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);

Framework integrations covers OpenAI, Anthropic, Google, Vercel, LangChain, LlamaIndex, CrewAI, AutoGen, Mastra, and raw MCP.

`balance()`

Check pool and customer balances

const pool = await locus.balance();
const customer = await locus.balance("user_123");

console.log(pool.credits);
console.log(customer.credits);

`searchTools()`

Find enabled tools by describing a capability:

Search enabled tools

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

Results include the execution slug, input schema, example arguments, and pricing. Passing user also applies that customer’s tool policy.

`ledger()`

Read usage with customer and attribution filters:

Read customer usage

const page = await locus.ledger({
  user: "user_123",
  category: "burn",
  attribution: { project: "prospect-research" },
  limit: 50,
});

Read page.entries and pass page.nextCursor as cursor for the next page.

`allocate()` / `deallocate()`

Move credits between the platform pool and a customer:

Move credits

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

Transfers cannot overdraw the source account. Supply an idempotencyKey when retrying the same transfer.

`topup()`

Create a hosted Stripe Checkout session:

Create a top-up session

const session = await locus.topup({
  usd: "100.00",
  successUrl: "https://yourapp.com/billing?ok=1",
  cancelUrl: "https://yourapp.com/billing",
});

// Redirect the buyer to session.url.

Omit externalUserId to fund the platform pool; include it to fund a customer. Send either usd or credits as an exact decimal string. Use topupConstraints() for current limits and topupStatus(session.sessionId) to confirm that payment has completed. See Funding & billing for funding options.

`endUserToken()`

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. Send the token to that user’s browser and keep the secret key on the server.

End-user catalog

The browser packages @withlocus/credits-js and @withlocus/credits-react export fetchCatalog for customer-facing tool lists. It returns allowed tools and final prices without exposing your costs or margins. See Render the provider catalog.

Errors

Handle insufficient credits

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

try {
  await locus.callJson(
    "tavily/search",
    { query: "company funding news" },
    { user: "user_123" },
  );
} catch (error) {
  if (error instanceof LocusInsufficientCreditsError) {
    // Show your top-up flow; error.topupUrl may provide a hosted link.
    console.error("More credits needed", error.requiredCredits);
  } else {
    throw error;
  }
}

Error	Meaning
`LocusApiError`	A non-success response; inspect `status` and `body`
`LocusInsufficientCreditsError`	Insufficient balance (`402`)
`LocusRateLimitError`	Rate limit reached after retries (`429`)

Constructor

Client options and defaults

Configure the client

new LocusCredits(credential, options);

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
`retryBaseMs` / `retryMaxMs`	`250` / `4000`	Backoff timing
`fetch`	Global `fetch`	Custom transport

See the API reference for complete request and response contracts.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Make a call

`call()`

Agent connections

Framework MCP presets

`balance()`

`searchTools()`

`ledger()`

`allocate()` / `deallocate()`

`topup()`

`endUserToken()`

End-user catalog

Errors

Constructor

​Make a call

​call()

​Agent connections

​Framework MCP presets

​balance()

​searchTools()

​ledger()

​allocate() / deallocate()

​topup()

​endUserToken()

​End-user catalog

​Errors

​Constructor

Make a call

`call()`

Agent connections

Framework MCP presets

`balance()`

`searchTools()`

`ledger()`

`allocate()` / `deallocate()`

`topup()`

`endUserToken()`

End-user catalog

Errors

Constructor