CIRCLE
Concepts

Credit wallet and LiteLLM gateway

How gatewayUrl, the wallet scope and the per-audience tokens let users call LLMs against their prepaid credit, and why the SDK has no debit API.

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: a WalletClient, which reads the wallet with a token minted for the auth-service audience;
  • gateway: a GatewayClient, which calls the gateway with a token minted for the gateway audience. It throws CFG_001 when gatewayUrl is 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.

Balances can be negative: usage or a refund that exceeded the credit leaves a debt. Do not recompute whether a user may spend from the balance: read 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:

StatusCodeMeaning
402GW_001The wallet cannot pay for this call.
429GW_002The gateway rate limit was reached. details.retryAfterSeconds carries the Retry-After value when present.
401, 403GW_003The gateway refused the credentials or the resource.
503GW_004The gateway is temporarily unavailable.
otherGW_005Unexpected answer.
Copyright © 2026