Funding API

Fund and manage balances for your app users.

Grant User Balance

POST /v1/funding/grant

Add balance to an app user's account from your grant pool. Provide an Idempotency-Key header to prevent duplicates.

Request

curl https://api.usequota.ai/v1/funding/grant \
  -H "Authorization: Bearer sk-quota-your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: funding-user123-jan2026" \
  -d '{
    "external_user_id": "user_123",
    "amount": 0.50,
    "description": "Welcome bonus"
  }'

Request Fields

Field	Type	Description
`external_user_id`	string	Your unique identifier for the user
`amount`	number	Dollar amount to add (e.g., 0.50 for $0.50)
`description`	string	Optional. Notes stored in the ledger

Response

{
  "external_user_id": "user_123",
  "amount_granted": "$0.50",
  "balance_before": "$5.00",
  "balance_after": "$5.50",
  "ledger_id": "ledg_123",
  "duplicate": false
}

Check User Balance

GET /v1/users/:id/balance

Check an app user's dollar balance.

Request

curl https://api.usequota.ai/v1/users/user_123/balance \
  -H "Authorization: Bearer sk-quota-your-api-key"

Response

{
  "external_user_id": "user_123",
  "balance": "$15.00",
  "billing_mode": "user"
}

Developer Balance

GET /v1/balance returns the developer balance. Whenexternal_user_id is provided, it returns that user's balance instead.

User Profile & Usage

GET /v1/me returns the authenticated user with a 30-day usage summary.

curl https://api.usequota.ai/v1/me \
  -H "Authorization: Bearer sk-quota-your-api-key"

Purchase Packages

GET /v1/packages lists purchasable balance packages (public endpoint, no auth required). Users buy balance in tiered packages -- larger packages get a better rate.

curl https://api.usequota.ai/v1/packages

Error Responses

Status	Code	Endpoint	Description
401	`invalid_api_key`	All	Missing or invalid API key
400	`bad_request`	POST /v1/funding/grant	Missing required fields
404	`user_not_found`	GET /v1/users/:id/balance	User not found
402	`insufficient_balance`	POST /v1/users/:id/chat/completions	User balance too low

All errors return a JSON body:

{
  "error": {
    "code": "bad_request",
    "message": "Missing required fields"
  }
}