CIRCLE
Concepts

Credit wallet and LiteLLM gateway

How gateway_url, 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 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: 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. Reading the property raises CFG_001 when gateway_url 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.topup_url() 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 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:

StatusCodeMeaning
402GW_001The wallet cannot pay for this call.
429GW_002The gateway rate limit was reached. details["retryAfterSeconds"] carries the Retry-After value when it is a non-negative number.
401, 403GW_003The gateway refused the credentials or the resource.
503GW_004The gateway is temporarily unavailable.
otherGW_005Unexpected answer.

A gateway that cannot be reached at all (a network error) also raises GW_004.

Copyright © 2026