Credits & Billing
One prepaid balance per workspace, one denomination everywhere, and an exact receipt on every billable tool call.
Denomination: credits-v1
Every amount in every tool response is in microcredits. Displayed credits are microcredits divided by 1,000,000. Callers never supply credits, microcredits, or a denomination — only Cubeshell converts and rounds.
credit_denomination
{
"version": "credits-v1",
"microcredits_per_display_credit": 1000000,
"displayed_credits_per_usd": 100
}Pricing
Each tool has one flat price, set in whole or half credits, and it never changes mid-call. You are quoted that price before execution and charged the same amount, or nothing if the result comes back unknown. There are no per-provider surcharges and no separate line items to reconcile.
Receipt fields
Every succeeded, failed, or unknown-status result includes a billing object recording exactly what was quoted, held, charged, and left:
| Parameter | Type | Description |
|---|---|---|
quoted_microcredits | integer | The price shown before execution. |
reserved_microcredits | integer | Held from the workspace balance while the call runs. |
charged_microcredits | integer | Actually captured. 0 when the result is unknown. |
released_microcredits | integer | Returned to the balance (reserved − charged). |
available_after_microcredits | integer | Workspace balance immediately after this call. |
price_version_id | string | The immutable price version this charge was quoted from. |
receipt_id | string | Immutable receipt identifier for this exact charge. |
*
Unknown results are never billed
If a tool cannot reach a confident result, it returns
charged_microcredits: 0 and releases the full reservation. This is enforced by a database constraint, not just application logic.