Widget

The Locus Pro Enterprise widget gives customers a live balance and an Add credits button, so you don’t have to build a billing screen. Customers see their balance and your prices. Your costs and margins stay private.

How it works

Your server mints a short-lived token for the signed-in customer. The widget uses that token and your publishable key to load the customer’s balance. When the customer adds credits, hosted Stripe Checkout takes the payment, and the widget refreshes the balance once payment completes. Your secret key never reaches the browser. Use @withlocus/credits-react in React or @withlocus/credits-js in any web app.

Mint a token on your server

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. Pass a renewUserToken callback to fetch a fresh one.

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

Set userToken to the token from your authenticated server route. LocusCredits.balance() returns a handle with refresh() and destroy().

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

Show transaction history

In the plain JavaScript widget, set showPerCallPricing: true to show the customer’s five most recent charges, top-ups, allocations, and refunds. The history refreshes with the balance. The React package does not render history yet. For React or other custom UI, call Own transaction history with the same publishable key and user token.

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

fetchCatalog loads every page of results 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

Option	Default	Purpose
`publishableKey` / `userToken`	Required	Browser authentication
`baseUrl`	`https://api.paywithlocus.com`	API origin
`topupUsd`	`"5.00"`	Purchase amount in USD; `topupCredits` overrides it
`showPerCallPricing`	`false`	Show recent transactions (plain JavaScript only)
`pollIntervalMs`	`15000`	Refresh interval; `0` turns polling off
`onTopup`	None	Runs after payment completes and the balance refreshes

Other options hide the purchase button, change its label, set Checkout return pages, and style the React container. The widget also supports checkout lifecycle callbacks, top-up metadata, and session binding.

Getting started

Build with Locus Pro

Connect agents

Pricing & plans

Funding & billing

Developer tools

Catalog directory

Testing

How it works

Mint a token on your server

Add the widget

Show transaction history

Render the provider catalog

Build your own balance UI

Customization

Next steps

Node SDK

Funding & billing

​How it works

​Mint a token on your server

​Add the widget

​Show transaction history

​Render the provider catalog

​Build your own balance UI

​Customization

​Next steps

Node SDK

Funding & billing

How it works

Mint a token on your server

Add the widget

Show transaction history

Render the provider catalog

Build your own balance UI

Customization

Next steps