Personal accounts do not expose secret or publishable keys, end-user balances,
volume bonuses, markup earnings, or payouts. They do include auto-reload,
monthly spend controls, low-balance alerts, and payment history. A Plus or
Unlimited connection subscription changes only active-client capacity; it
does not include tool-usage credits.
Personal credits
Open Credits, choose an amount, and continue to Stripe Checkout. Each top-up adds exactly the amount in the quote; Personal accounts do not receive volume bonus credits. Tool calls draw down this balance as your connected agents use them. Set an auto-reload threshold and amount to charge your saved card when the balance drops below the threshold. You can also set a monthly hard cap, monthly-spend email threshold, and low-balance email threshold. These changes require a recent owner sign-in, not enterprise MFA or an API key. Open Credits → Payment history to review card top-ups. Usage separately shows the tool calls that consume your balance.Enterprise money flow
1
Someone buys credits
You (pool) or an end-user starts a top-up. Locus creates a Stripe Checkout
session and returns a hosted URL.
2
Stripe charges the card
The buyer pays on Stripe’s hosted page. Locus never touches card data.
3
The webhook mints credits
On Stripe’s
checkout.session.completed webhook, Locus writes the credits
to the balance as an append-only ledger entry. The webhook is the source of
truth; the client redirect is informational only.4
Calls burn credits
Each API call burns credits at your effective price. For allocated balances,
Locus returns the markup portion to your wholesale pool. For balances funded
through Locus-hosted checkout, the markup accrues as payable earnings.
Enterprise wholesale top-ups
Fund your wholesale pool so pooled calls and end-user allocations have credits to draw on.successUrl, cancelUrl, and exactly one of usd or credits (credits convert at your denomination). Preview the total (including any fee) without creating a session; the quote endpoint takes the same usd-or-credits choice:
Enterprise pool top-up volume bonuses
Enterprise pool top-ups can mint additional Locus-funded promotional credits. The default schedule applies the highest threshold reached to the full credited amount:
The live schedule can change, so read
GET /api/credits/topups/config or locus.topupConstraints() before displaying it. POST /api/credits/topups/quote returns quote.bonus for the selected amount and quote.nextBonusTier for the next threshold. The created session returns the promised bonus, and the webhook mints it as a separate promotional ledger entry after payment completes. Auto-recharges use the same pool schedule.
Personal and end-user top-ups never earn a volume bonus. Include
externalUserId when quoting an end-user purchase so the response reflects that
rule. The Personal quote and funding UI omit the bonus schedule entirely.
Enterprise card-fee mode
A per-tenantfeeMode decides who bears the card processing fee on every Stripe top-up (yours and your end-users’):
For example, a call with a $0.09 base cost and 30% markup has a $0.117 final price. On a $20 card top-up at the 2.9% + $0.30 card rate,
pass_through means the end-user pays the processor gross-up (about $0.91 in this example); absorb means the buyer pays $20 and the tenant pays the fee (about $0.88) from earnings. Locus does not absorb processor fees. Always render the exact quote returned by the API rather than reproducing this illustrative math.
After each charge the quoted fee is reconciled against Stripe’s actual processor fee and any difference is ledgered to whoever bore the fee.
Limits
The minimum top-up is $5; there is no per-transaction maximum. Locus tracks top-up velocity per account for fraud review but does not enforce rolling dollar caps.Auto-reload and enterprise auto-recharge
Set a threshold and refill amount. When the balance dips below the threshold, Locus charges your saved card and refills it. The personal dashboard calls this auto-reload; the API and enterprise dashboard use auto-recharge. Configure it from the dashboard. Personal accounts require a recent owner sign-in. Enterprise workspaces require the workspace owner’s signed-in session with fresh MFA step-up andpayouts:manage. An API key cannot change it. The body is { "thresholdUsd": "20.00", "amountUsd": "100.00" }; send both fields as null to disable it.
If the saved card fails, you see a dashboard banner, and burns keep working until the balance is actually empty. Enterprise workspaces additionally receive a credits.balance.low webhook (reason: "auto_recharge_failed") against the wholesale pool.
Spend controls and balance alerts
Auto-reload keeps a balance funded. Spend controls add a monthly ceiling and monthly email threshold, evaluated on the UTC calendar month. A separate low-balance threshold sends an email when the balance crosses below it and re-arms after the balance rises above it.committedUsd — captured spend plus everything currently in flight — not spentUsd. Read it before raising a limit, or you will size the new ceiling against the wrong number.
Personal owners change these controls after a recent sign-in. Enterprise changes require the workspace owner with MFA step-up completed in the last ten minutes, so an API key cannot raise its own ceiling:
null to remove it. Amounts are positive dollars with at most 6 decimal places. alertThresholdUsd cannot exceed monthlyLimitUsd. Lowering the monthly alert below captured spend triggers it immediately; changing the balance threshold re-arms it and evaluates the current balance right away.
What your agents see when the ceiling is hit
OncecommittedUsd reaches the ceiling, further calls are refused before the provider is dispatched, so no credits move and nothing is charged:
403. Treat it as terminal, not transient: retrying before resetsAt cannot succeed, because the limit is a setting rather than a load condition. The two ways out are waiting for the window to roll over or raising monthlyLimitUsd, which clears the denial immediately.
Enterprise end-user top-ups
Fund an end-user’s own balance; credits then burn from that user at your price. You can fund a user two ways: a card top-up they pay for themselves, or an allocation out of your wholesale pool.- From the widget (recommended)
- From your server
Drop the balance + top-up widget into your app. It authenticates with your publishable key plus a short-lived end-user token you mint server-side, shows the user’s balance, and opens Stripe Checkout on click. You never write top-up code.
Allocation moves existing credits within your tenant (pool ↔ user). Stripe
top-ups add purchased credits. Locus-funded evaluation grants and contracted
subscriptions separately add promotional credits to the workspace pool.
Promo or comp allocations use the same allocation operation with
"promo": true and ledger separately under a PROMO category.Enterprise earnings and payouts
Whenever an end user funds their balance through Locus-hosted checkout, whether from the widget or a URL created by your server, margin accrues as payable earnings when they burn credits. Margin matures after a holdback window (30 days by default). Locus processes eligible payouts after the required reviews; the first payout is manually reviewed before it goes out. Choose the destination under Funding & billing → Payouts. Connect a Stripe account to receive fiat in your bank, or configure a USDC payout address to receive matured margin on Base. The dashboard shows the payable balance and manages the destination. Locus handles payout initiation after review rather than exposing a self-service withdrawal control. Check what’s accrued with your secret key; the money follows whichever destination you picked:payableUsdc is matured margin net of prior payouts and chargebacks. It is the
amount currently eligible for the payout process, not a promise of immediate
transfer. Locus initiates and processes the payout after review.
Payout settings (connecting Stripe, changing the USDC address) live in the
dashboard only. No API key can change them, so a leaked key can’t redirect
your money. A USDC address change also starts a 24-hour hold before the next
payout.
If you bill users on your own Stripe and allocate credits from your
wholesale pool, only the base cost is consumed from that pool. Locus returns
the markup portion to the pool, and you have already collected the cash margin
through your own Stripe account. Stripe can pay your balance to your bank as
usual, but there is no Locus margin payout to claim. Locus payouts only apply
to end-user top-ups collected through Locus-hosted checkout.
Refunds & disputes
Enterprise webhooks
Configure a webhook URL from the dashboard and Locus signs every event to it. Locus mints the signing secret (whsec_…) when you first set the URL. Each delivery carries four headers — X-Locus-Webhook-Id, X-Locus-Webhook-Timestamp, X-Locus-Webhook-Signature, and X-Locus-Webhook-Version — and the signature value is v1=<hex>: HMAC-SHA256 over <unix-timestamp>.<raw JSON body>. Verify against the raw body, and reject timestamps older than five minutes.
The payload envelope is { "id", "type", "api_version", "created_at", "sequence", "tenant_id", "data" }. Deduplicate by id and order by sequence. An event is delivered up to 7 times in total — the initial attempt plus 6 retries at 60 s / 5 m / 30 m / 2 h / 8 h / 24 h — with a 10-second response timeout; undelivered events are retained for 30 days and can be replayed manually. Signed test fixtures for your verifier live in webhook-fixtures.json.
Enterprise activity and ledger
Completed movements of value use append-only ledger entries, including top-ups, burns, allocations, payouts, clawbacks, and fee adjustments. A burn entry carries its base cost and margin split; Locus does not create a separate margin-accrual entry. In-flight reservations are tracked separately, and a refundable failure releases its reservation without leaving a ledger charge. Accepted streams remain charged even if delivery later fails. Locus never edits or deletes a ledger entry, so a balance always equals the sum of its posted history.GET /api/credits/ledger/summary with the same filters when you need the
total row count, counts by category, and amountUsdcByCategory without paging
through every entry:
category, sourceKey, externalUserId, initiator,
provider, endpoint, account=platform, createdAfter, createdBefore, and
attribution.<key>=<value>. An endpoint filter requires provider. Use these
filters to answer questions such as “how many credits did customer X’s agent
spend on enrichment this month?” The SDK exposes paged entries through
locus.ledger({ user, category, attribution }).
The widget
The fastest path to end-user top-ups.
SDK reference
topup, allocate, ledger, and more.