Getting started

Authentication

A bearer key against a prepaid USDC balance — or no key at all, if the caller has an Arc wallet.

API keys

Every request carries a bearer token in the Authorization header. Keys are created and rotated in the console.

shell

curl https://api.vacuumfi.com/v1/models \  -H "Authorization: Bearer $VACUUM_KEY"

Keys are scoped to one balance. Rotating a key does not touch the balance behind it.
A key is shown once, at creation. There is no way to recover it afterwards — rotate and replace.
Keys belong on a server. A key in a browser bundle is a key someone else can spend.

Prepaid balance

Vacuum does not invoice. You top up a balance in USDC and requests draw it down. Fund it from any chain CCTP supports and the transfer settles on Arc; the console shows the credited amount once the transfer finalises.

There is no overdraft and no grace period. When the balance cannot cover a request’s maximum cost, the request is refused before any node is asked to do work — so a drained balance costs you latency, never a partial charge.

How a request is billed

At the moment a request is accepted, the router reserves its maximum possible cost: the prompt tokens it can already count, plus max_tokens at the model’s output rate. That reservation is held, not spent.

When the response closes, the reservation is released and the actual cost is debited from the tokens the receipt commits to. A generation that stops early costs what it generated, not what it was allowed to generate.

Field	Type	Description
reserved	usdc	prompt_tokens × input rate + max_tokens × output rate, at request time.
debited	usdc	prompt_tokens × input rate + completion_tokens × output rate, from the signed receipt.
refunded	usdc	The difference, released the moment the response closes or the connection drops.

If a node fails mid-request and the router fails over, you are billed once, for the response you actually received. The node that dropped is not paid at all.

json

{  "error": {    "type": "insufficient_balance",    "message": "Reserving 0.0004 USDC would overdraw a balance of 0.0001 USDC.",    "balance_usdc": "0.0001",    "required_usdc": "0.0004"  }}

Paying without a key

An autonomous agent does not need an account. If the caller holds USDC on Arc, it can sign each request from its own wallet and settle per request, with no human-managed key anywhere in the loop. See Paying from an Arc wallet.