Credits API

Read and spend micro-credits from your users' Proma balance.

The Credits API is available at proma.credits. It requires the credits scope.

Unit: 1,000,000 micro-credits = $1.00

getBalance

Returns the user's current credit balance.

const { balance, formatted } = await proma.credits.getBalance()

console.log(balance)    // 1230000 (micro-credits)
console.log(formatted)  // "$1.23"

Return type

interface BalanceResponse {
  balance: number    // micro-credits
  formatted: string  // human-readable, e.g. "$1.23"
}

spend

Deducts credits from the user's account. The operation is atomic — it fails if the user's balance would go negative.

// Spend 500,000 micro-credits ($0.50)
const result = await proma.credits.spend(500_000, 'Generated AI report')

console.log(result.amount_spent)  // 500000
console.log(result.new_balance)   // remaining balance in micro-credits

Parameters

Parameter	Type	Description
`amount`	`number`	Micro-credits to deduct. Must be a positive integer.
`description`	`string?`	Optional note shown in the user's transaction history.

Return type

interface SpendCreditsResponse {
  amount_spent: number
  new_balance: number
}

Errors

Throws if the user has insufficient credits. Catch and handle this in your UI:

try {
  await proma.credits.spend(1_000_000, 'Feature usage')
} catch (err) {
  // err.message will be 'insufficient_credits' or similar
  alert('Not enough credits')
}