Money

Balance, then the usage that moved it.

/v1/billing/usage takes start and end, and both operations carry a typed 2xx body, so an SDK reads a struct rather than decoding by hand. Those are cloud's own declarations, from the handlers' In/Out types — not a shape anybody wrote here on their behalf.

Prepaid credit the caller's org can still spend

GET /v1/billing/balance · reference →

Answers the spendable prepaid balance of the wallet this caller bills from — the same wallet the AI prepaid gate reads before admitting a paid request, the edge meter debits, and a top-up credits.

The wallet is an ADDRESS, not an org: account echoes the key resolved within the ledger — the org's shared pool for a tenant org, a personal account for a member of the shared signup org. The echo is the point. A browser could only GUESS its own payer by decoding its own token, and a guess that disagrees with the server is how money lands in an account the gate never reads.

balance, holds and available are whole USD cents, ROUNDED from the ledger's exact 18-decimal value. On the co-resident ledger holds is 0 and available equals balance: the gate's reservations live in its own pod and are never posted, so the settled balance IS the spendable one.

The ledger is the caller's own org, taken from the VALIDATED IAM owner claim and never from a client header. No validated principal is 401 — with one exception, the trusted in-process service token the AI gate itself presents, which reads the gateway-pinned org and nothing it could name. A balance that cannot be READ is 502, never 0: unknown is not broke.

hanzo billing balance

import { Configuration, BillingApi } from 'hanzoai';

const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBillingBalance();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).get_billing_balance()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.BillingAPI.GetBillingBalance(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, billing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = billing_api::get_billing_balance(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new BillingApi(client).getBillingBalance();

curl https://api.hanzo.ai/v1/billing/balance \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "billing",
         "arguments": {
           "op": "get_billing_balance",
           "input": {}
         }
       }
     }'

Every billed call the caller's org made, attributed to a product

GET /v1/billing/usage · reference →

Answers one row per BILLED call against the caller's org — transaction id, amount, timestamp and the metered unit. This is the raw charged ledger, not a rollup.

Each row is stamped with a canonical metadata.product derived from what the meter persisted: agent becomes agents, provisioning becomes the provisioned kind, a token-metered row becomes inference, anything else keeps its metering surface. The ledger has no product field of its own, so this read is where that dimension is made real — from the SAME charged rows, never a second meter. A row that already carries its own product WINS, so the derivation stops the day the meter records one.

product=<id> filters to one product server-side. groupBy=product reduces to {product,requests,amountCents} rollups instead of rows.

amount is whole USD cents, ROUNDED; decimal beside it is the SAME debit exact, as an 18-decimal USD string. Sum decimal. A page of sub-cent token calls totals correctly there and totals ZERO in amount — that difference is real money.

Scoped to the caller's own org's books, where the org's ledger file IS the tenant boundary; no client-supplied subject is ever forwarded. 401 without a validated principal. The co-resident read returns the 2000 most recent debits, newest first; start and end narrow the window only on the split-deploy upstream.

hanzo billing usage get

import { Configuration, BillingApi } from 'hanzoai';

const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBillingUsage();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).get_billing_usage()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.BillingAPI.GetBillingUsage(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, billing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = billing_api::get_billing_usage(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new BillingApi(client).getBillingUsage();

curl https://api.hanzo.ai/v1/billing/usage \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "billing",
         "arguments": {
           "op": "get_billing_usage",
           "input": {}
         }
       }
     }'

Every command, call and tool above is generated from the same OpenAPI document that generates the SDKs themselves — the four surfaces are projections of one doc comment, so they cannot disagree.