Docs · Balance

Balance: dollars, exact to the nano-dollar

Balance is prepaid US dollars, one for one: $1 of Balance is $1. It pays for metered and professional usage — the AI API, the Exchange, compute, developer tools and team plans. Vibes are for tips and consumer products; the Vibes guide is separate.

Preview. These surfaces open when OpenVibe enables Billing's money settings. The sandbox works now and never touches real money.

Who holds one

  • A person. Your own playground runs and your own API calls with your personal token use your personal Balance.
  • A project. Usage by a project's apps and keys uses the project's Balance: the developer pays for the app's usage. A project's admins add money to it directly, or move money in from their personal Balance.

In Billing's ledger a person's Balance is a USD account owned by user:<usr_id>; a project's is owned by project:<prj_id>. A project's page on OpenVibe.Services shows its Balance at /projects/<prj_id>/balance.

How usage bills a project's Balance

A request is priced before it starts. The most it can cost is held from the project's available Balance; when it ends, only what was used is charged and the rest is released at once. A request that would exceed the balance, or its own cap, is refused before it runs (402 billing.insufficient_funds). If a provider fails mid-stream, only the tokens produced until then are charged; the cap is never the charge.

The arithmetic is integer nano-USD ($0.000000001), never a float. A model prices four token classes per million tokens — input, cached read, cache write and output — plus an optional per-request fee. Each class is rounded up once per request, then added:

charge = ceil(input_tokens    × rate_in / 1e6)
       + ceil(cached_tokens   × rate_cached / 1e6)
       + ceil(cache_write     × rate_cache / 1e6)
       + ceil(output_tokens   × rate_out / 1e6)
       + per_request_nano_usd

For example, 1,200 input at $0.04/M, 8,000 cached at $0.01/M and 400 output at $0.12/M costs $0.0001136 — the exact integer Billing stores. A statement shows every charge with the key or app that made it. Set max_cost_usd on a request to cap it.

Read it

With the person's Network user token, Billing answers their Balance and the projects they administer:

GET /api/me/balance
GET https://billing.openvibe.network/api/me/balance
Authorization: Bearer <the person's token>

→ 200 {
  "personal": { "balance_nano_usd": "12400000000", "held_nano_usd": "0", "available_nano_usd": "12400000000" },
  "projects": [ { "owner": { "type": "project", "id": "prj_…" }, "balance_nano_usd": "…", … } ]
}

A project's statement (its Balance, held and available, and its recent charges) is the same read scoped to the project, with project_id; only an admin or owner of the project may see it. Everything is a decimal string of integer nano-USD: parse it as a BigInt, never as a float.

Add money

Add money in the wallet opens a top-up through any of the platform's payment providers: PowerChat, Stripe, PayPal, CCBill or NOWPayments. The provider handles the card or the wallet; OpenVibe never stores a card number. A project's admins add money to the project directly, or move their own Balance in. A top-up is not enabled until the owner turns on the platform's top-up switch.

Move money to a project

Your Balance → a project's Balance is a transfer. It is atomic and idempotent, and it can never spend money a running request is holding. Use Move to a project in the wallet, or the API:

POST /api/me/balance/transfers
POST https://billing.openvibe.network/api/me/balance/transfers
Authorization: Bearer <the person's token>
Content-Type: application/json

{
  "to_project_id": "prj_…",
  "amount_nano_usd": "5000000000",
  "idempotency_key": "move-2026-11-04-1"
}

→ 201 { "transfer": { … }, "from": { … }, "to": { … } }

amount_nano_usd is a positive integer string: 5,000,000,000 is $5.00. The same idempotency key with the same request replays the first answer; the same key with a different request is refused. Moving money the other way — a project's Balance to a person — is not a top-up or a withdrawal; it is a refund or a payout under Billing's rules.

Sandbox

A sandbox app spends only its project's sandbox Balance, never the paid one. Test freely: no card, no real money, and nothing a production request could spend. The project page shows the sandbox Balance apart from the real Balance.

The words

  • Balance is dollars, added with Add money and used by metered and professional products.
  • Vibes are the social currency, bought with Get Vibes and spent; never earned.
  • OpenCoins are the reward currency, earned by watching and chatting.

A product never asks a person to choose between Balance and Vibes for the same thing. Use Balance for exact, metered usage; use Vibes for tips, cheers and consumer items.