Widget

Give customers a live balance and an Add credits button without building a billing screen. The Locus Pro Enterprise widget opens hosted Stripe Checkout, then refreshes the balance when payment completes. Use @withlocus/credits-react in React or @withlocus/credits-js in any web app. Customers see their balance and your prices; your costs and margins stay private.

Mint a token on your server

The widget needs your publishable key and a short-lived token for the signed-in user:

Authenticated server route

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

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

// Inside an authenticated route handler:
const { token } = await locus.endUserToken(currentUser.id);
return { userToken: token };

Derive currentUser.id from your server session. Never send the secret key to the browser.

Tokens last at most one hour; use renewUserToken to refresh them.

React
Plain JavaScript

Install the React package

npm install @withlocus/credits-react

Billing.tsx

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

function Billing({ userToken }: { userToken: string }) {
  return (
    <CreditsBalance
      publishableKey="lcrpk_..."
      userToken={userToken}
      showPerCallPricing
      onTopup={() => console.log("Balance updated")}
    />
  );
}

Mount the widget

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

Pass the token returned by your authenticated server route. The returned handle provides refresh() and destroy().

The default top-up is $5. Set topupUsd or topupCredits to change the amount.

Show transaction history

Set showPerCallPricing to display the five most recent charges, top-ups, allocations, and refunds. The history refreshes with the balance and shows only the signed-in user’s activity. For custom React UI, use fetchLedger:

Load transaction history

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

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

See Own transaction history for pagination and response fields.

Render the provider catalog

Show customers which tools they can use and what they cost:

Load the customer catalog

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

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

The helper loads the pages for you. Results include provider names, logos, allowed endpoints, and final credit prices. Variable-price tools are marked as dynamic.

Build your own balance UI

Custom balance hook

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

const { credits, loading, error, refresh } = useCreditsBalance({
  publishableKey: "lcrpk_...",
  userToken,
});

Render the loading and error states alongside the balance.

Customization

Widget options and defaults

Option	Default	Purpose
`publishableKey` / `userToken`	Required	Browser authentication
`baseUrl`	`https://api.paywithlocus.com`	API origin
`showTopup`	`true`	Show the purchase button
`topupUsd`	`"5.00"`	Purchase amount in USD
`topupCredits`	None	Purchase amount in credits; overrides `topupUsd`
`topupLabel`	`"Add credits"`	Button text
`showPerCallPricing`	`false`	Show recent transactions
`pollIntervalMs`	`15000`	Refresh interval; `0` disables polling
`renewUserToken`	None	Async callback for a fresh token after a `401`
`onTopup`	None	Callback after completed payment and balance refresh
`topupSuccessUrl` / `topupCancelUrl`	Current page	Checkout return destinations
`style` / `className`	None	React container styling

The widget also supports checkout lifecycle callbacks, top-up metadata, and session binding.

Next steps

Funding & billing: choose how customer balances are funded.
SDK reference: mint tokens and charge usage from your server.

Getting started

Build with Locus Pro

Connect agents

Funding & billing

Developer tools

Catalog directory

Testing

Mint a token on your server

Add the widget

Show transaction history

Render the provider catalog

Build your own balance UI

Customization

Next steps

​Mint a token on your server

​Add the widget

​Show transaction history

​Render the provider catalog

​Build your own balance UI

​Customization

​Next steps

Mint a token on your server

Add the widget

Show transaction history

Render the provider catalog

Build your own balance UI

Customization

Next steps