Credits & Ledger

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:

Saturn quotes the expected cost
Credits are checked against the quote
If insufficient credits → call rejected with CREDIT_EXHAUSTED
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

Card (USD)
Lightning (sats)

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

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

const invoice = await saturn.wallet.fund({
  amountSats: 10000 // ~$3-5 depending on rate
});

console.log('Pay this invoice:', invoice.paymentRequest);

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

Mistake	Consequence
Not monitoring balance	Agents stop unexpectedly
Assuming credits = budget	Credits are pool; budgets are caps
Ignoring low-balance warnings	Production 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

100 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)}`);

Getting Started

Core Concepts

Capabilities

SDK

Tutorials

Resources

Credits & Ledger

Why Prepaid

Enforcement Behavior

Adding Credits

Checking Balance

Transaction History

Receipt Data

Common Mistakes

Balance vs Budget

Example

​Why Prepaid

​Enforcement Behavior

​Adding Credits

​Checking Balance

​Transaction History

​Receipt Data

​Common Mistakes

​Balance vs Budget

​Example

Why Prepaid

Enforcement Behavior

Adding Credits

Checking Balance

Transaction History

Receipt Data

Common Mistakes

Balance vs Budget

Example