Skip to main content
Credits are prepaid funds in your Saturn account. The ledger is the immutable record of all credit movements—deposits, deductions, and refunds. Credits are denominated in USD cents internally. You add credits via card payment or Lightning. Agents spend credits per-call.

​
Why Prepaid

Prepaid credits create a hard ceiling. You cannot spend money you haven’t deposited. This is fundamentally different from post-pay models where the bill arrives after damage is done. The ledger provides:
  • Complete audit trail
  • Per-agent attribution
  • Reconciliation data
  • Refund tracking

​
Enforcement Behavior

Before every upstream call:
  1. Saturn quotes the expected cost
  2. Credits are checked against the quote
  3. If insufficient credits → call rejected with CREDIT_EXHAUSTED
  4. If sufficient → credits held, call executed, credits settled
Settlement is atomic. If the upstream call fails, held credits are released. 
Quote: $0.024
Balance: $0.015
Result: REJECTED (CreditExhausted)

Quote: $0.024
Balance: $50.00
Result: Credits held → Call executed → $0.024 deducted → Receipt issued

​
Adding Credits

const checkout = await saturn.wallet.fundCard({
  amountUsdCents: 1000 // $10
});

console.log('Pay here:', checkout.checkoutUrl);
// Opens Stripe checkout

​
Checking Balance

const wallet = await saturn.wallet.get();
console.log(`Balance: $${(wallet.balanceUsdCents / 100).toFixed(2)}`);

​
Transaction History

const transactions = await saturn.wallet.transactions();

for (const tx of transactions) {
  console.log(`${tx.type}: ${tx.amountUsdCents} cents - ${tx.description}`);
}

​
Receipt Data

Every successful call returns metadata with cost information: 
const result = await saturn.reason({ prompt: '...' });

console.log({
  charged: result.metadata.chargedUsdCents,     // Cost of this call
  quoted: result.metadata.quotedUsdCents,       // Pre-quoted estimate
  balanceAfter: result.metadata.balanceAfter,   // Remaining credits
  auditId: result.metadata.auditId,             // Unique receipt ID
});

​
Common Mistakes

MistakeConsequence
Not monitoring balanceAgents stop unexpectedly
Assuming credits = budgetCredits are pool; budgets are caps
Ignoring low-balance warningsProduction outage when credits exhaust

​
Balance vs Budget

Credits and budgets are different concepts.
  • Credits = How much money is in your account
  • Budget (caps) = How much an agent is allowed to spend
An agent with 100increditsbuta100 in credits but a 5/day cap cannot spend more than $5/day.

​
Example

// Check current balance
const wallet = await saturn.wallet.get();
console.log(`Available: $${(wallet.balanceUsdCents / 100).toFixed(2)}`);

// Every call returns cost in receipt
const result = await saturn.reason({ prompt: '...' });
console.log(`Charged: $${(result.metadata.chargedUsdCents / 100).toFixed(4)}`);
console.log(`Remaining: $${(result.metadata.balanceAfterUsdCents / 100).toFixed(2)}`);