Credit wallet and LiteLLM gateway
auth-service holds one prepaid euro wallet per user, shared by every application, and ships an optional LiteLLM gateway that bills it. The operator side (plans, access groups, top-ups) is documented in auth-service: LiteLLM gateway and LiteLLM gateway and credit wallet in an application. This page explains how the SDK uses it.
What gatewayUrl switches on
Setting gatewayUrl in createAuthClient is the SDK half of the LiteLLM support switch of the application in auth-service. The sign-in then also asks for:
- the scope
wallet:self:read, which lets a user token read the user's own wallet; - the gateway URL as an audience, for LLM and MCP calls;
- the auth-service URL (
issuer) as an audience, because auth-service serves the wallet.
gatewayUrl is compared verbatim to the token's aud, so it must not end with a slash and must be HTTPS (HTTP only on loopback).
Two clients per user
createAiClient({ auth, grants }) returns an AiClient. forUser(grantId) gives a UserAi bound to one user's grant, with:
wallet: aWalletClient, which reads the wallet with a token minted for the auth-service audience;gateway: aGatewayClient, which calls the gateway with a token minted for the gateway audience. It throwsCFG_001whengatewayUrlis not configured.
Each call mints (or reuses) a short-lived access token from the user's grant. The access token is the gateway's API key: it is never stored, and the gateway recognises the user from it.
Why there is no debit API
The gateway debits the wallet after each call. Debits are centralised there so that every application, and every kind of call (chat, embeddings, MCP tools), is billed the same way. An application only reads the wallet and, when the balance is too low, sends the user to refill it: wallet.topupUrl() returns the Credit tab of the user's auth-service profile, because checkout needs the user's own session.
canSpend, which is true for an unlimited account or a strictly positive balance.Amounts are bigint micro-euros
All wallet amounts are bigint values in micro-euros (MICRO_PER_EUR is 1_000_000n). They travel as integer strings because a JSON number cannot carry them exactly; the SDK parses them to bigint, and the web handlers serialise them back to strings.
import { MICRO_PER_EUR, formatEuros } from "@circle-rd/auth-ai";
formatEuros(5_000_000n); // "5.00"
formatEuros(1_234_567n, 4); // "1.2345"
formatEuros(-1_500_000n, 1); // "-1.5"
console.log(MICRO_PER_EUR); // 1000000n
formatEuros(amount, fractionDigits = 2) truncates toward zero (0 to 6 digits; other values throw a RangeError): rounding up could show a user more credit than they hold.
Attributing usage to a session
Pass metadata: { session_id: "<your id>" } in a gateway request and the spend is attributed to that session. wallet.getSessionUsage(sessionId) then returns what that session spent, for the calling application only. See Call the LiteLLM gateway.
Errors from the gateway
The gateway client maps a refusal to the SDK's error registry by HTTP status, because LiteLLM serialises the final body itself and only the status is a contract:
| Status | Code | Meaning |
|---|---|---|
402 | GW_001 | The wallet cannot pay for this call. |
429 | GW_002 | The gateway rate limit was reached. details.retryAfterSeconds carries the Retry-After value when present. |
401, 403 | GW_003 | The gateway refused the credentials or the resource. |
503 | GW_004 | The gateway is temporarily unavailable. |
| other | GW_005 | Unexpected answer. |