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 gateway_url switches on
Setting gateway_url in the AuthClient configuration 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.
gateway_url 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
AiClient(auth=auth, grants=grants) is bound to your client and your grant manager. for_user(grant_id) 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. Reading the property raisesCFG_001whengateway_urlis 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.topup_url() returns the Credit tab of the user's auth-service profile, because checkout needs the user's own session.
can_spend, which is true for an unlimited account or a strictly positive balance.Amounts are integer micro-euros
All wallet amounts are Python int values in micro-euros (MICRO_PER_EUR is 1_000_000). They travel as integer strings because a JSON number cannot carry them exactly; the SDK parses them to int, and to_json() serialises them back to strings.
from auth_ai import MICRO_PER_EUR, format_euros
print(format_euros(5_000_000)) # 5.00
print(format_euros(1_234_567, 4)) # 1.2345
print(format_euros(-1_500_000, 1)) # -1.5
print(MICRO_PER_EUR) # 1000000
format_euros(amount, fraction_digits=2) truncates toward zero (0 to 6 digits; any other value raises ValueError): 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.get_session_usage(session_id) 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 it is a non-negative number. |
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. |
A gateway that cannot be reached at all (a network error) also raises GW_004.