Guides

Accounts & billing

The account API is at https://tessera.storage/api/v1. It is a different surface from the storage API at index.tessera.storage. Storage requests are signed (see Authentication). Account requests use an agent API key.

Accounts are prepaid USD. Usage is metered: storage per 40 MiB block per day, a small upload fee per block, and downloads per block. There is no plan to choose. tessera signup creates the account.

Technical validation

Every new account starts at $0.00 with one upload of up to 40 MiB and one download. Tessera covers the hosts for that single validation. The balance stays $0.00. After that upload and download, top up to continue.

Agent accounts

curl -X POST https://tessera.storage/api/v1/agents \
  -H 'content-type: application/json' \
  -d '{"name":"build-box","contact_email":"[email protected]"}'

{ "account_id": "…", "api_key": "tsk_…_…" }

Keys are tsk_<prefix>_<secret>, returned once, stored only as an HMAC digest. Send one as an Authorization bearer header (tsk_…) on every account request.

Endpoint	Purpose
`POST /agents`	Create an account and its first key. Needs `X-Altcha`.
`GET /auth/altcha-challenge`	A single-use proof-of-work challenge.
`GET /agents/me`	Account summary for the bearer key.
`POST /agents/me/keys`	Mint another key. Shown once.
`DELETE /agents/me/keys/{id}`	Revoke one key.

Signup is capped at 3 new accounts per source IP per 24 hours (IPv6: per /64) and 20 per /24 (IPv6: per /48). Over the cap: 429 signup_limit. Existing accounts signing in are not counted.

Browser signup is not available on the site. The magic-link endpoints exist; they are not a public path today.

Account summary

GET /account returns the summary for a bearer caller:

{
  "billing_id": "…",
  "kind": "agent",
  "status": "active",
  "balance_usd": "12.50",
  "open_slabs": 42,
  "egress_used_bytes": 21000000000,
  "days_left": 23,
  "topup_open": true,
  "topup_rails": { "nowpayments": true, "x402": true },
  "warnings": []
}

Field	Meaning
`status`	`pending`, `active`, `past_due`, `suspended`, or `terminated`.
`balance_usd`	Prepaid balance in USD, as a string.
`open_slabs`	Slabs currently open.
`egress_used_bytes`	Download bytes. On a technical-validation download this is the actual size; after top-up it is billed blocks × 40 MiB.
`days_left`	After top-up: an estimate from balance and burn, not a promise. `null` at $0.00.
`topup_open` / `topup_rails`	Whether top-up is open, and which rail. Check the rail you intend to use.
`warnings`	Recent threshold warnings, newest first. Agents poll this; there is no mailbox.

The response may also carry plan, period_end, and included_storage_bytes. Ignore them. The live model is metered prepaid balance, not a plan.

Rates

Live rates: GET /api/v1/billing/rates or tessera rates.

Storage is metered on logical volume, in 40 MiB blocks. Network redundancy is Tessera's cost, already in the rate. Uploads are metered by what you write; downloads by what you read.

Top-ups

Three rails. Check topup_rails first. A closed rail returns 503 topup_closed.

x402 (USDC on Base). Minimum $0.01. tessera topup 0.50 --wallet.
Deposit address. Any enabled coin. USDC on Base is the default. Processor minimums apply (about $0.38 for USDC on Base; other coins higher).
Hosted invoice. "mode": "invoice" lets the payer choose the coin.

Tessera's floor is $0.01 on every rail. Live minimums: GET /billing/topup/minimums or tessera topup --minimums. Under the processor minimum: 409 below_asset_minimum.

POST /billing/topup with {"amount_usd": 25} returns a payment intent: pay_address, pay_amount, pay_currency. Send the exact amount. The address quote expires in about 20 minutes. Partial and overpayments are credited.

x402: a 402 carries the challenge. Sign an EIP-3009 TransferWithAuthorization and retry with PAYMENT-SIGNATURE. Settled payments return 200 and the new balance_usd. A refused authorization returns a fresh 402; a retry with a new authorization is not double-charged.

Suspension and deletion

If the balance cannot cover usage, the account moves to past_due and keeps serving through a grace window, rather than stopping immediately. Stored data stays retrievable during that window.

Warnings fire at the threshold days-left values and at zero, on the warnings array.

Unpaid past grace, the account is suspended. Funding stops. Contracts already funded are not renewed. When those contracts end, the storage credential is revoked, objects are removed, and slabs are queued for pruning. Deletion is not reversible. Export first. Billing records are retained as required.

Recovery phrase

tessera signup prints a recovery phrase and an API key once. Keep both. On a new machine, tessera login "<12 words>" restores the same account. Tessera cannot recover a lost phrase.

Deleting your account

POST /account/delete with {"confirm_account_id":"<your id>"}. The CLI asks you to type the account ID; agents pass --yes.

Deletion revokes every key and session, deletes stored files, and stops billing. It cannot be undone. No balance is refunded; the response reports balance_forfeited_usd. A closed account cannot sign in or be restored from its phrase.