Skip to content
zkaozkaozkao docs
These docs describe staging.zkao.io and the @zksecurity/zkao-cli@next release. For production, see docs.zkao.io.

Credits and usage

View .md

zkao is pay as you go. You buy credits, and scans spend them. Credits are the only unit the API uses.

Where the balance lives

Section titled “Where the balance lives”

Every project belongs to an organization. The organization holds one prepaid balance. All of its projects share it.

A project token still sees one project. The billing endpoints report the organization’s balance as seen from that project. Usage and monthly spend cover only that project’s activity.

Credits are bought in the zkao app, not over the API.

What a scan reserves

Section titled “What a scan reserves”

A launch reserves the scan’s full budget from the balance. The scan then spends only what its analysis uses, never more than the budget. When it finishes, the unused part is released. A cancelled scan releases its reservation too.

So the balance has three numbers:

Field Meaning
balanceCredits The organization’s total prepaid balance.
reservedCredits Credits held by the organization’s queued and running scans.
availableCredits The balance minus reservations. This is what a new scan can reserve.

Active scans in other projects of the organization reduce availableCredits too.

Check the balance

Section titled “Check the balance”
Terminal window
zkao billing balance

The response names the organization that owns the balance. Check availableCredits before choosing a budget.

When credits run out

Section titled “When credits run out”

A launch whose budget the balance cannot cover fails with 402 insufficient_credits. Add credits in the app, or launch with a smaller budget. Reading the balance and usage keeps working with an empty balance.

A token can also carry its own spend limit, set when it was created. zkao whoami shows it as spendLimitCredits. A launch past that limit fails with 429 rate_limited.

Read the usage ledger

Section titled “Read the usage ledger”

The ledger lists every credit movement attributed to the project. Each event has a signed credits value. Negative means spent, positive means added or refunded.

Type Meaning
SCAN_DEDUCTION Credits a scan spent.
SCAN_REFUND Credits returned to the balance from a scan.
PURCHASE Credits bought.
STRIPE_REFUND A purchase refunded.
ADMIN_ADJUSTMENT A manual adjustment by zkao.
Terminal window
zkao billing usage
zkao billing usage --from 2026-09-01 --to 2026-10-01 --limit 200

The default range is the last 30 days. The response echoes the range it used. Events come newest first, up to 1,000. Movements made outside any project, such as an organization top-up, are not listed.

Monthly summary

Section titled “Monthly summary”

The summary gives net credits spent on scans and net credits purchased, per calendar month in UTC. Months come newest first, and quiet months show zeros. Ask for up to 24 months.

Terminal window
zkao billing summary --months 6