Skip to main content
Personal accounts pay the listed tool price from prepaid credits. Enterprise workspaces can additionally define a credit denomination and markup for their end users; everything an end user pays follows from the formula on this page.
Markup, end-user balances, fee mode, and margin are enterprise features. Personal users can inspect tool prices under Tools and their charges under Usage without configuring resale pricing.

​
Credit denomination

A credit is a fixed fraction of a US dollar. Personal accounts use the default ratio of 1,000 credits per dollar. An enterprise workspace chooses its credits per dollar ratio during setup, and that ratio never changes. credits=usd×creditsPerDollar\text{credits} = \text{usd} \times \text{creditsPerDollar} Balances, prices, and charges show in both credits and USD. A finer denomination (more credits per dollar) prices sub-cent calls cleanly: at 1000 credits/, a \0.0039 call is 3.9 credits.
Money is always exact. Locus computes every amount as a decimal to 6 places (USDC precision) and rounds up on the final step, so a nonzero markup can never round away to zero margin.

​
Markup

Every catalog endpoint has a base price: what Locus charges you for that call. Your markup is what you add on top. It has two parts, and you can set both globally or override them per endpoint. markupBps is capped at 10000 (2× the base price) and flatMarkupUsdc at $100 per call by default; both caps are adjustable per tenant by support.
Basis points, quickly: 100 bps = 1%, 1000 bps = 10%, 3000 bps = 30%, 10000 bps = 100% (you charge double the base).

​
The formula

your price=⌈ base×(1+markupBps10000)+flatMarkupUsdc ⌉6\text{your price} = \lceil\, \text{base} \times (1 + \tfrac{\text{markupBps}}{10000}) + \text{flatMarkupUsdc} \,\rceil_{6} your margin=your price−base\text{your margin} = \text{your price} - \text{base} Where ⌈  ⌉6\lceil\;\rceil_6 rounds up to 6 decimal places. The minimum base price for any call is $0.001.

​
Worked examples

1

Percentage markup

A basic-depth Tavily search costs a base of $0.09. (The endpoint is body-priced: advanced depth bills $0.16, and the catalog reports it as dynamic.) Your global markup is 3000 bps (30%).0.09 × (1 + 3000/10000) = 0.09 × 1.30 = 0.117
2

Sub-cent call, same 30%

A fal.ai status check costs a base of $0.003.0.003 × 1.30 = 0.0039
3

Flat fee instead of a percentage

A $0.010 base with 0 bps and a $0.005 flat fee:0.010 × 1.00 + 0.005 = 0.015
4

Percentage and flat together

Stack 2000 bps (20%) and a $0.002 flat fee on a $0.05 base:0.05 × 1.20 + 0.002 = 0.062 → $0.062 (62 credits), margin $0.012.

​
Global default, per-endpoint overrides

Set one markup for your whole catalog, then override where it matters. Resolution is most-specific-wins:
You can preview exactly what a change does before shipping it: GET /api/credits/catalog returns every endpoint’s baseUsdc, markupBps, flatMarkupUsdc, chargedUsdc, and marginUsdc. See The catalog.

​
Response-priced endpoints

Some endpoints know a safe maximum before execution but calculate the final price from the returned usage. Locus reserves the ceiling, captures the measured charge, and releases the unused amount. Enterprise markup applies to the measured base, not the ceiling. The exact charge appears in X-Locus-Credits-Charged and the ledger. Retrying the same idempotency key replays that result without another charge. If Locus delivers a response but cannot measure and durably record its usage, it retains the authorized maximum instead of undercharging after delivery.

​
Live-priced endpoints

External MPP and x402 services can set their price at execution time. For x402, call MCP estimate_cost with preflight_external_quote: true when you need a no-payment quote. Otherwise pass max_charge_credits as a hard ceiling. If the quote exceeds the ceiling, Locus declines the call before dispatch and charges nothing. See live-quoted endpoints.

​
The two modes

One thing decides how a call bills: whether it carries an end-user id. Without one, the call is pooled and draws the base price from your wholesale pool at zero markup. With X-Locus-End-User set, it charges your price to that user’s balance. You keep the margin.
Pooled calls bill at base price with no markup. Markup applies only when a call charges an end-user’s balance.
How you receive that margin depends on how the end-user balance was funded. If you allocated credits after billing the user yourself, Locus returns the markup portion to your wholesale pool at burn time; you already collected the cash through your own billing. If the user bought credits through Locus-hosted checkout, from the widget or a URL created by your server, eligible markup accrues as a Locus payable balance after each burn. Locus initiates payouts after review once the holdback has matured. See enterprise earnings and payouts. For the full money path in each mode, see the enterprise fund-flow diagrams on the overview.

​
Non-streaming failures auto-refund

For a non-streaming call, Locus reserves credits when the call starts and captures them only if the upstream provider returns success. If the provider errors or times out first, the reservation releases back to the balance automatically and leaves no charge in enterprise activity and ledger. If that release hits a transient failure, it is queued and retried until applied. Pre-dispatch failures (503) carry an X-Locus-Retry-Safe: true header; a 503 without that header arose after dispatch, and a same-key retry never redispatches upstream while the stored outcome settles. Streaming is different: Locus captures after the upstream accepts the stream and before the first response byte. A failure before upstream stream headers releases the reservation, but a client disconnect or stream failure after acceptance remains charged. See inference and streaming.

​
Other guarantees

  • Insufficient balance returns 402 with the required vs. available credits and a docs link; the call never runs and no charge posts.
  • Idempotent charges: every call carries an Idempotency-Key; a retry with the same key replays the stored outcome instead of charging again.
  • Base cost stays private: Locus returns the X-Locus-Cost-Usd header and base/markup figures only to your secret key. End-user tokens and the widget see only the final credit price, never your cost or margin.

Funding & billing

Top-ups, auto-recharge, refunds, and disputes.

The catalog

Browse base prices and set your markup.