# Money

URL: https://docs.hanzo.ai/docs/guides/money

> Balance, then the usage that moved it.

**Balance, then the usage that moved it.**

> Neither takes an org: both derive the tenant server-side from the JWT `owner` claim, so a key can only read its own money. Both ids are cloud's cloud's, and so is the prose: it comes out of the handler's doc comment.

/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 →](https://docs.hanzo.ai/docs/openapi/billing)

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.

`cash`, `line` and `credit` say where `available` came from, and add up to it. `cash` is money the customer paid — a settled card payment or a recorded wire. `credit` is money Hanzo minted: signup and promotional credit, admin grants. `line` is what is left of the org's postpaid credit line (`creditLimit`), and `due` what the account owes on it: usage the line paid for, invoiced, and paid down first by the next payment. A debit draws cash, then the line, then credit; granted credit never pays what is due. The three line fields are absent when the ledger did not report them.

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. A balance that cannot be READ is 502, never 0: unknown is not broke.

**CLI**

```bash
hanzo billing balance
```

**SDK**

**.ts**

```ts
import { Configuration, BillingApi } from 'hanzoai';

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

**.py**

```python
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()
```

**.go**

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

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

**.rs**

```rust
use hanzo_client::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?;
```

**.java**

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

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

**HTTP**

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

**MCP**

MCP reaches **billing** through the `billing` tool, which names its 39 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_billing_accounts"
         }
       }
     }'
```

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

`GET /v1/billing/usage` · [reference →](https://docs.hanzo.ai/docs/openapi/billing)

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.

**CLI**

```bash
hanzo billing usage get
```

**SDK**

**.ts**

```ts
import { Configuration, BillingApi } from 'hanzoai';

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

**.py**

```python
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()
```

**.go**

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

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

**.rs**

```rust
use hanzo_client::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?;
```

**.java**

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

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

**HTTP**

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

**MCP**

MCP reaches **billing** through the `billing` tool, which names its 39 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_billing_accounts"
         }
       }
     }'
```

---

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.