/api/v1/billing/quota

Purchase API TOKENS by debiting the USD `credit_balance` wallet at ONE flat rate — 7,000 tokens per $1 (the same rate the Pro plan is priced at; no volume bonus at any size).

Purchase API TOKENS by debiting the USD `credit_balance` wallet at ONE flat rate — 7,000 tokens per $1 (the same rate the Pro plan is priced at; no volume bonus at any size). Credits the live token ledger. EXEMPT (`cost: 0`). Logs a SPEND `Transaction` plus a `grant` row in the token audit trail. Returns 400 with `INSUFFICIENT_BALANCE` when the wallet does not cover the requested amount.

freeSince v1.0.0

Why use this

Customer-initiated TOKEN top-up — debits the USD `credit_balance` wallet (in DOLLARS) and credits the CANONICAL token ledger (the same balance [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) reports and every `/api/v1/*` call meters against) at ONE flat rate: 7,000 tokens per $1, identical at every purchase size. EXEMPT (`cost: 0`). Atomic single-transaction: wallet debit + ledger credit + SPEND `Transaction` + `grant` audit row commit together — a failure at any point rolls back everything, so a dollar can never be taken without its tokens landing. Returns 400 with `INSUFFICIENT_BALANCE` if `credit_balance < amount_dollars`. To top up the USD wallet first, use [POST /api/v1/payments/create-intent](/docs/account/payments-module/post-payments-create-intent).

Common use case

Dashboard 'Buy Extra Quota' tiles: user picks the $10 pack → POST here with `amount_dollars: 10` → backend debits the wallet by $10, credits 70,000 tokens to the live token ledger, returns the new token balance → UI updates the token-balance display.

Customer-initiated token top-up. EXEMPT (cost: 0). Debits the USD credit_balance wallet (in DOLLARS) and credits the CANONICAL token ledger — the balance every metered /api/v1/* call debits — at ONE flat published rate: 7,000 tokens per $1 (the Pro plan's own 200,000/$29 rounded to a clean number; deliberately no volume bonus, so a top-up can never out-price the subscription). Purchased tokens add on top of the monthly-cycle refill and are consumed by the same meter. Atomic — wallet debit + ledger credit + SPEND Transaction + grant audit row commit together (no half-state on partial failure). Returns 400 with INSUFFICIENT_BALANCE when credit_balance < amount_dollars; gate the UI button by checking GET /api/v1/user/ credit_balance first. To fill the wallet before calling this, use POST /api/v1/payments/create-intent (one-time top-up via Stripe).

Parameters

Name	In	Required	Default	Allowed	Description	Example
amount_dollars	body	required	—	—	USD amount to spend (NOT cents). Positive number; integer or float (e.g. 10, 20, 12.50). Validated server-side: rejected with 400 `BAD_REQUEST` on missing/non-numeric/zero/negative; rejected with 400 `INSUFFICIENT_BALANCE` if `users.credit_balance < amount_dollars`. Each $1 buys 7,000 TOKENS — pack sizes and custom amounts alike, one published rate.	10

Response schema

Field	Type	Nullable	Description
status	string	no	ApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
request_id	string	yes	Per-request correlation ID.
timestamp	string	no	ISO-8601 UTC timestamp.
data	object	no	Post-purchase result payload.
data.message	string	no	Human-readable confirmation (e.g. `Successfully purchased 70000 tokens.`). Use for the UI success toast.
data.tokens_credited	integer	no	Exactly how many tokens this purchase credited — always `amount_dollars x 7,000` (pack prices resolve to the same flat rate). Use for the success toast.
data.new_token_balance	integer	no	Post-purchase token-ledger balance — the same number [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) reports. Use to update the token-balance display client-side without a second call.
data.new_balance	number	no	Post-purchase USD wallet balance (`users.credit_balance`). NOT in cents — server returns `float(credit_balance)`. Use to update the 'Wallet balance' chip client-side.

Sample response

"status": "success"
"request_id": "req_3OqK2jK9L8pQ4xZ5"
"timestamp": "2026-05-02T15:51:00.000Z"
"data":
- "message": "Successfully purchased 70000 tokens."
- "tokens_credited": 70000
- "new_token_balance": 270000
- "new_balance": 2.5
}

}

Errors

Status	Label	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query, body, or path parameter.
401	Unauthorized	Missing or invalid Authorization header / api_Token.
402	Payment Required	Insufficient token balance for this call. Top up
429	Too Many Requests	Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500	Server Error	Unexpected server-side failure. Retry with backoff; report if persistent.

Code samples

Reveal credentials

curl -X POST "https://api.finradar.ai/api/v1/billing/quota" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_dollars": 10
}'

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).