Skip to main content

Funding and grants overview

Funding and grants are the account-level value layer and accounting surface.

Budgets sit beside funding as spend boundaries. They cap what a runtime flow can consume but do not hold value and are not charged by authorize.

Prereqs​

Core endpoints (authoritative)​

See OpenAPI for request and response shapes:

Common endpoints include:

  • GET /api/v1/wallet/balance

available_balance is the authoritative amount for display and authorization. It is the active non-fallback grant availability minus outstanding_balance, clamped to zero. outstanding_balance is committed fallback-funded usage that has not yet been paid or offset, including both pending reservations and settled consumption.

Preferred ways to add value to an account​

In most products, treat balance increases as the result of explicit commercial flows:

  • Plan-issued credits (for example, periodic credits as part of a billing plan).
  • Grant programs (trials, promotions, enterprise credits).
  • Checkout purchases (for example, one-time credit topups).

Trusted operators can issue an explicit one-time grant when a commercial flow does not apply. Wallet balance itself is read-only.

Integration patterns​

  • Display and preflight against available_balance, not an individual grant total.
  • Record consumption through Gate commit or the events-and-ratings pipeline.
  • Treat estimates as advisory. Actual committed usage can create a small outstanding balance in prepaid as well as postpaid billing.

Amount-map response keys​

Money maps such as CurrencyAmounts always contain xusd. Other keys are server-configured currency codes and are therefore dynamic; usd may be present, but clients must not assume it is a required named property. Read the desired currency key from the map and handle its absence explicitly.

Verify​

  • Balance responds for a known account context.

Next​