> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saturn-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits & Ledger

> Prepaid funds and immutable transaction history

**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

<Tabs>
  <Tab title="Card (USD)">
    ```typescript theme={null}
    const checkout = await saturn.wallet.fundCard({
      amountUsdCents: 1000 // $10
    });

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

  <Tab title="Lightning (sats)">
    ```typescript theme={null}
    const invoice = await saturn.wallet.fund({
      amountSats: 10000 // ~$3-5 depending on rate
    });

    console.log('Pay this invoice:', invoice.paymentRequest);
    ```
  </Tab>
</Tabs>

## Checking Balance

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

## Transaction History

```typescript theme={null}
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:

```typescript theme={null}
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

<Warning>
  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.
</Warning>

## Example

```typescript theme={null}
// 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)}`);
```