Widget

The widget is an enterprise/platform feature. It puts a live credit balance, optional recent transaction history, and an Add credits button in your product. The button opens a Locus-hosted Stripe Checkout, so end users top up their own balance and you never build billing UI. There are two builds with identical behavior: @withlocus/credits-react for React apps and @withlocus/credits-js for a plain script tag.

Your workspace needs secret and publishable keys. Evaluation workspaces can use the widget and customer top-ups; evaluation status does not enable payouts or Stripe Connect. Personal accounts use Credits in the dashboard instead and do not expose publishable keys or end-user balances.

How it authenticates

The widget runs in the browser, so it authenticates with your publishable key (lcrpk_…, safe to expose) plus a short-lived end-user token you mint server-side. The token is scoped to one user: it can read that user’s balance and ledger, open a top-up, and authenticate metered burns charged to that user’s balance. It is an end-user credential, not a tenant key or an lcac_… agent connection credential. Tokens expire after an hour at most, so mint one per page load or refresh as needed.

Mint a token on your server

Using your secret key, mint a token for the signed-in user:

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

// In your authenticated route handler:
const { token } = await locus.endUserToken(currentUser.id);
return { userToken: token };   // send to the browser

Render the widget with it

Pass the publishable key and that token to the widget (below). Never put the secret key in the browser.

React

npm install @withlocus/credits-react

import { CreditsBalance } from "@withlocus/credits-react";

function Billing({ userToken }: { userToken: string }) {
  return (
    <CreditsBalance
      publishableKey="lcrpk_..."
      userToken={userToken}
      baseUrl="https://api.paywithlocus.com"
      topupCredits="5000"
      showPerCallPricing
      onTopup={() => console.log("balance topped up")}
    />
  );
}

Prefer to build your own UI? The hook gives you the raw state:

import { useCreditsBalance } from "@withlocus/credits-react";

const { credits, loading, error, refresh } = useCreditsBalance({
  publishableKey: "lcrpk_...",
  userToken,
  baseUrl: "https://api.paywithlocus.com",
});

Plain HTML / script tag

No build step: drop a script tag and a target element on the page.

<script src="https://unpkg.com/@withlocus/credits-js"></script>
<div id="credits"></div>
<script>
  LocusCredits.balance("#credits", {
    publishableKey: "lcrpk_...",
    userToken: "END_USER_JWT",
    baseUrl: "https://api.paywithlocus.com",
    topupCredits: "5000",
    showPerCallPricing: true,
  });
</script>

balance() returns a handle with refresh() and destroy(). The ESM build (import { balance } from '@withlocus/credits-js') is available too.

Show transaction history

Set showPerCallPricing to show the five most recent entries from the signed-in user’s transaction history. The list includes metered charges, top-ups, allocations, and refunds. It refreshes with the balance and displays amounts in your credit denomination. Both React and plain JavaScript use the self-scoped GET /api/credits/me/ledger endpoint. The end-user token determines whose history is returned; a browser cannot select another externalUserId. Locus removes your base cost, markup, margin, tenant identifiers, and other internal pricing configuration from this response. For a custom React UI, call the exported helper with the same browser authentication:

import { fetchLedger } from "@withlocus/credits-react";

const entries = await fetchLedger(
  {
    baseUrl: "https://api.paywithlocus.com",
    publishableKey: "lcrpk_...",
    userToken,
  },
  20,
);

See Own transaction history for cursor pagination and the complete response.

Render the provider catalog

Both browser packages export fetchCatalog. It follows opaque cursors and returns policy-filtered providers keyed by stable IDs:

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

const catalog = await fetchCatalog(
  {
    baseUrl: "https://api.paywithlocus.com",
    publishableKey: "lcrpk_...",
    userToken,
  },
  { category: "AI / LLM", pageSize: 25 },
);

for (const provider of catalog.providers) {
  console.log(provider.displayName, provider.logoUrl);
  for (const endpoint of provider.endpoints) {
    console.log(endpoint.id, endpoint.displayName, endpoint.price);
  }
}

The response contains only the user’s final credit/USD price. It cannot reveal your base cost, markup, margin, credentials, tenant identifiers, or payout configuration.

Customization

Both builds share the same options:

Option	Default	Description
`publishableKey`	required	Your `lcrpk_…` key
`userToken`	required	End-user JWT from `locus.endUserToken(userId)`
`baseUrl`	`https://api.paywithlocus.com`	API origin, no trailing slash. Defaults to production; pass the stage origin explicitly only for isolated evaluation.
`showTopup`	`true`	`false` renders a balance-only display with no purchase button
`topupCredits`	none	Optional exact decimal string. When omitted, the widget requests the safe `$5.00` USD default.
`topupUsd`	`"5.00"`	USD amount used when `topupCredits` is not set
`topupLabel`	`"Add credits"`	Button label
`topupMetadata`	none	String fields (max 16) attached to the Stripe Checkout session
`pollIntervalMs`	`15000`	Balance and transaction-history refresh interval; `0` disables polling
`topupSuccessUrl` / `topupCancelUrl`	current page	Stripe Checkout return URLs
`sessionId`	none	Session-binding value the end-user token was minted with
`renewUserToken`	none	Async callback returning a fresh token; on a `401` the widget calls it once and retries
`onTopup`	none	Fires only when the closed checkout reports `completed`, after the balance refreshes
`onTopupSuccess` / `onTopupCancel` / `onTopupClose` / `onTopupFailure`	none	Granular checkout lifecycle callbacks
`style` / `className` (React only)	none	Container styling overrides
`showPerCallPricing`	`false`	Opt-in list of the five most recent charges, top-ups, allocations, and refunds

The widget shows the end-user only their balance and your credit prices. Base prices and your margin never reach the browser.

The end-user experience

Sees their balance

The widget renders the current balance in your credit denomination (e.g. 4,935 credits) and refreshes on a poll. When you enable showPerCallPricing, it also shows the five most recent transactions.

Clicks Add credits

A Locus-hosted Stripe Checkout opens in a popup for topupCredits worth of credits. Card data never touches your app.

Balance updates

On completion the popup closes, the balance refreshes, and onTopup fires. From then on their metered calls draw down this balance.

Funding & billing

The full money flow behind the button.

SDK reference

endUserToken, balance, and the rest.

Getting started

Funding & billing

Catalog

Agents

Developer tools

Testing

How it authenticates

React

Plain HTML / script tag

Show transaction history

Render the provider catalog

Customization

The end-user experience

Funding & billing

SDK reference

​How it authenticates

​React

​Plain HTML / script tag

​Show transaction history

​Render the provider catalog

​Customization

​The end-user experience

Funding & billing

SDK reference

How it authenticates

React

Plain HTML / script tag

Show transaction history

Render the provider catalog

Customization

The end-user experience