HostAgentics Docs

HostAgentics AI Credit System

Last updated: 2026-08-06

HostAgentics agent runtimes (OpenClaw, Hermes Agent) need model access to do useful work. HostAgentics provides model access in two ways: **HostAgentics AI credit** (prepaid usage through our managed model routing) and **BYOK** (bring your own model-provider keys). This document describes the credit accounting rules, wallet invariants, zero-balance behavior, and key handling. It is an internal engineering reference; customer-facing behavior is summarized in `docs/pricing.md`.

1. Two kinds of credit

  • **Included monthly credit**: granted per billing period — €5 for n8n Cloud, OpenClaw Cloud, and Hermes Cloud; €12 shared across the plan's runtimes for Complete. It is a grant, not a charge. **It does not roll over**: at the end of the billing period, unused included credit expires (recorded as an `expiry` transaction).
  • **Prepaid top-ups**: one-time purchases of €10 / €25 / €50 / €100. Top-ups are added to the wallet as `topup` transactions. **They roll over**: prepaid credit stays in the wallet across billing periods until consumed (or refunded per the refund policy).

    • Both kinds live in the same wallet (`ai_credit_wallets`), and consumption draws from the combined balance. The dashboard shows the split (included vs. prepaid) so customers can see what will expire at period end.

    2. Wallet accounting (never negative)

  • One wallet per organization (`ai_credit_wallets`, unique per org). Balances are integer EUR cents.
  • Every movement is an append-only transaction in `ai_credit_transactions`: `included_grant`, `topup`, `consumption`, `expiry`, `refund`. Each transaction records `deltaCents`, `balanceAfterCents`, kind, provider, model, external spend ID, and a unique idempotency key.
  • **The wallet balance is never negative.** A consumption transaction is only written if the balance covers it; if it does not, the request is rejected at the accounting layer. This is a database-level invariant, not just a UI rule.
  • Consumption is debited based on model usage reported by the model provider (via the restricted per-runtime key's usage), matched to an external spend ID so a usage report is applied at most once.

    • 3. Zero-balance behavior

    When the wallet balance reaches zero (or cannot cover the next request):

  • New model calls from the runtime stop — the runtime receives a clear "no credit / zero balance" response and the customer is notified.
  • The runtime itself keeps running; only model access through HostAgentics credit is blocked.
  • The customer can top up (€10–€100, immediate settlement via Stripe, see `docs/billing.md`), add a BYOK key, or wait for the next period's included grant.
  • There is no negative balance, no "credit line", and no surprise charge. Nothing is billed automatically when credit runs out.

    • 4. HostAgentics credit routing

    When a runtime uses HostAgentics credit, model traffic is routed through OpenRouter using a **restricted, per-runtime key** created from the platform's OpenRouter management key (`OPENROUTER_MANAGEMENT_API_KEY`). The management key is never injected into any runtime; only the restricted per-runtime key is (`ai_provider_keys` with kind `managed`). Per-runtime keys carry a hard monthly spend limit (`limitCents`) aligned with the wallet balance so a runaway runtime cannot exceed available credit. Spend is tracked per key (`spentCents`) and reconciled into the wallet as consumption.

    5. BYOK

    Customers can supply their own model-provider keys (OpenAI, Anthropic, Google, OpenRouter, or any OpenAI-compatible endpoint via `baseUrl`):

  • Keys are submitted through the dashboard or API **once**, encrypted immediately into a `SecretEnvelope`, and **never displayed again in plaintext**. Only a masked hint (e.g. `sk-…abcd`) is ever shown (`key_hint`).
  • A BYOK key can be attached to one or more runtimes; when attached, the runtime uses the customer's key and its provider directly instead of HostAgentics credit routing.
  • BYOK keys have a monthly spend limit the customer sets, a rotation version, and can be revoked at any time. When revoked, the runtime falls back to wallet credit if the wallet has a balance.
  • BYOK material is never logged, never sent to third parties, and is decrypted only at the moment it must be injected into the runtime environment (see `docs/secret-rotation.md`).

    • 6. Related documents

  • `docs/pricing.md`, `docs/fixed-pricing.md` — credit amounts and policy
  • `docs/billing.md` — how top-ups are purchased and settled
  • `docs/secret-rotation.md` — key envelopes and rotation
  • `docs/database.md` — ai_credit_wallets / ai_credit_transactions / ai_provider_keys schema