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

# Credits & Billing

<Info>
  **Private Beta:** Stratus is currently in private beta. Visit [stratus.run](https://stratus.run/?beta=true) to apply for access.
</Info>

Stratus uses a **credit-based pricing model**. Purchase in advance, pay only for what you use — no subscriptions, no monthly fees.

<CardGroup cols={3}>
  <Card title="1 credit = $0.05" icon="dollar-sign" color="#22d3ee">
    Flat rate across all packages. No hidden fees.
  </Card>

  <Card title="Credits never expire" icon="infinity" color="#34d399">
    No monthly commitments. Use at your own pace.
  </Card>

  <Card title="Per-request billing" icon="receipt" color="#c084fc">
    Credits are deducted as requests complete. The model is never called if your balance is insufficient.
  </Card>
</CardGroup>

## Credit Packages

| Package        | Credits | Price   | Per Credit |
| -------------- | ------- | ------- | ---------- |
| **Starter**    | 1,000   | \$50    | \$0.05     |
| **Pro**        | 5,000   | \$250   | \$0.05     |
| **Enterprise** | 25,000  | \$1,250 | \$0.05     |

Same \$0.05 rate across all packages. Credits never expire.

## Purchasing Credits

<Tabs>
  <Tab title="Dashboard (Card)">
    1. Sign in at [stratus.run/dashboard](https://stratus.run/dashboard)
    2. Click **"Purchase Credits"**
    3. Select a package and proceed to checkout
    4. Enter your card details via Stripe's secure hosted checkout
    5. Credits are added to your balance immediately upon payment

    <Note>
      Stratus never stores your card details — all payments are processed by Stripe.
    </Note>
  </Tab>

  <Tab title="API (x402 / USDC)">
    Stratus also supports programmatic credit purchases via the [x402 payment protocol](https://x402.org) — USDC on Base.

    ```bash theme={null}
    # List available packages
    curl https://api.stratus.run/v1/credits/packages \
      -H "Authorization: Bearer $STRATUS_API_KEY"
    ```

    ```bash theme={null}
    # Initiate a purchase — returns 402 with payment instructions
    curl -X POST https://api.stratus.run/v1/credits/purchase/starter \
      -H "Authorization: Bearer $STRATUS_API_KEY"
    ```

    The 402 response contains an x402 payment challenge with the required USDC amount and treasury address on Base. Pay the amount, then retry with the `X-PAYMENT` header containing the signed transaction. Credits are posted immediately upon on-chain settlement.
  </Tab>
</Tabs>

## How Credits Are Consumed

Credits are deducted based on:

1. **Model used** — different models have different credit costs
2. **Token count** — more tokens = more credits
3. **Key source** — Formation's pool adds a 25% markup; BYOK does not

### Formation Pool vs. BYOK

| Key Source                   | Credit Cost      | LLM Cost                                  |
| ---------------------------- | ---------------- | ----------------------------------------- |
| **Formation pool** (default) | Base cost × 1.25 | Covered by Formation (included in markup) |
| **Your own key** (BYOK)      | Base cost only   | Billed directly to your provider account  |

Every response includes billing transparency in the `stratus` field:

```json theme={null}
{
  "stratus": {
    "key_source": "formation",
    "formation_markup_applied": 0.25
  }
}
```

With BYOK: `key_source` is `"user"` and `formation_markup_applied` is `null`.

### Credit Costs by Model

Approximate usage per request (varies by token count):

| Model                                 | Credits per 1K tokens | Typical request   |
| ------------------------------------- | --------------------- | ----------------- |
| `stratus-x1ac-small-gpt-4o-mini`      | 0.02                  | 0.05–0.10 credits |
| `stratus-x1ac-small-gpt-4o`           | 0.15                  | 0.20–0.40 credits |
| `stratus-x1ac-base-gpt-4o`            | 0.25                  | 0.30–0.60 credits |
| `stratus-x1ac-large-gpt-4o`           | 0.40                  | 0.50–1.00 credits |
| `stratus-x1ac-base-claude-sonnet-4-5` | 0.20                  | 0.25–0.50 credits |

Actual usage varies by prompt and response length. Monitor your balance from the [Dashboard](https://stratus.run/dashboard).

## Bring-Your-Own-Key (BYOK)

BYOK removes Formation's 25% pool markup by routing LLM calls through your own provider account instead of Formation's shared OpenRouter pool.

### How It Works

1. **Store your provider keys** in Stratus vault (encrypted AES-256-GCM) — or pass them per-request via inline headers
2. **Stratus routes** LLM calls directly through your key
3. **You pay your provider** at your negotiated rates — not deducted from credits
4. **Credits cover only the X1 planning layer** — no markup applied

<CardGroup cols={2}>
  <Card title="No Markup" icon="dollar-sign">
    Pay providers directly at your rates. Formation's 25% pool markup is not applied.
  </Card>

  <Card title="Privacy" icon="lock">
    Vault-stored keys are encrypted at rest using AES-256-GCM and never leave encrypted storage.
  </Card>
</CardGroup>

Set up BYOK via [Dashboard → LLM Keys](https://stratus.run/dashboard?tab=llm-keys) or `POST /v1/account/llm-keys`. See [Authentication → BYOK](/docs/authentication#bring-your-own-key-byok) for the full setup guide.

## Referrals

Every Stratus account includes **5 referral codes** — share them to earn credits when friends sign up.

* **Your reward:** 25 credits (\$1.25) added to your balance for each successful referral
* **Find your codes:** [Dashboard → Referrals](https://stratus.run/dashboard)
* **Referral link format:** `https://stratus.run/?ref=STR-XXXXXXXX`

Referral credits appear as `bonus` transactions in your billing history.

## Billing History

View all credit activity from [Dashboard → Billing History](https://stratus.run/dashboard):

* **Purchases** — Stripe card payments and x402/USDC purchases
* **Usage** — per-request credit deductions
* **Bonuses** — referral rewards
* **Refunds / Grants** — any manual adjustments

To manage your payment method or download past invoices, use the [Billing Portal](https://stratus.run/dashboard) — accessible from the dashboard under billing settings.

## Cost Optimization

### Choose the Right Model

```typescript theme={null}
// Lowest cost — simple tasks
model: 'stratus-x1ac-small-gpt-4o-mini'

// Good balance — most use cases
model: 'stratus-x1ac-small-gpt-4o'

// Complex reasoning — higher cost
model: 'stratus-x1ac-large-gpt-4o'
```

### Limit Response Length

```typescript theme={null}
const response = await client.chat.completions.create({
  model: 'stratus-x1ac-small-gpt-4o',
  messages: [...],
  max_tokens: 100
});
```

### Use BYOK

Eliminate the 25% Formation pool markup by adding your own provider key — the single most impactful cost reduction for high-volume usage.

## Troubleshooting

### 402 — Insufficient Credits

```json theme={null}
{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Required: 0.05, Available: 0.01",
  "required_credits": 0.05,
  "available_credits": 0.01,
  "x402": {
    "x402Version": 1,
    "accepts": [
      {
        "scheme": "exact",
        "network": "eip155:8453",
        "description": "Pay for inference: 1 credits ($0.05 USDC)",
        "payTo": "..."
      }
    ],
    "error": "Payment required"
  },
  "top_up_url": "https://api.stratus.run/v1/credits/purchase/starter"
}
```

**Cause:** The estimated cost of the request exceeds your credit balance. This is a pre-flight check — the model is never called.

**Fix:** Top up via the [Dashboard](https://stratus.run/dashboard) or follow the `top_up_url` in the error response for the API purchase flow.

***

## FAQs

**Do credits expire?**
No. Credits never expire.

**What happens when I run out of credits?**
The next request fails pre-flight with a `402` before the model is called. No partial charges.

**Can I transfer credits between accounts?**
No. Credits are tied to the purchasing account and cannot be transferred.

**Are there hidden fees?**
No. \$0.05/credit. Formation pool adds a 25% markup; BYOK removes it. No monthly fees, setup fees, or other charges.

**Do you offer custom pricing for high volume?**
Yes — email [sales@stratus.run](mailto:sales@stratus.run) for Enterprise pricing beyond the 25K package.

**Can I get a refund?**
Email [billing@stratus.run](mailto:billing@stratus.run) with your account email and purchase date. Refund requests are considered within 30 days of purchase for unused credits.

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" color="#22d3ee" href="/docs/authentication">
    Set up API keys and configure BYOK to pay providers directly.
  </Card>

  <Card title="Quickstart" icon="rocket" color="#c084fc" href="/docs/quickstart">
    Make your first API call in under 60 seconds.
  </Card>

  <Card title="API Reference" icon="code" color="#34d399" href="/docs/api-reference/introduction">
    Full endpoint docs, parameters, and error codes.
  </Card>
</CardGroup>