# Payments and metering

Version 0.1 — SAND-WP-0006. OpenRouter-style credits for metered SaaS extensions.

## Credits store

Path: `~/.local/share/sandboxer/credits.json` (override via test injection).

| Env | Default |
|-----|---------|
| `SANDBOXER_DEFAULT_CREDITS` | `10.0` USD on first use |

```bash
sandboxer credits show
sandboxer credits add 25.00
```

## Metered lifecycle

1. **create** — `estimate_cost` on metered extension; block if balance insufficient
2. **ready** — `SandboxStatus.meter.estimate_usd` recorded
3. **destroy** — `meter_actual` (or prorated estimate); debit credits; State Hub note event

Self-hosted extensions (`pricing_model: self-hosted`) skip credits.

## Extension contract

Metered extensions implement on `SandboxExtension`:

```python
def estimate_cost(self, profile, inputs, *, duration_s=3600) -> MeterQuote | None
def meter_actual(self, handle, *, duration_s: float) -> float | None
```

Reference: `ext.saas-stub` (no external API).

## BYOK

Provider API keys are resolved at provision boundary via `secret_refs` / OpenBao —
not implemented in v0 stub. Set provider env vars per extension when adapters land.

## Billing export

sand-boxer meters sandbox consumption only. Domain billing authority (fin-hub) is a
future export consumer of State Hub meter events — not owned here.