> ## Documentation Index
> Fetch the complete documentation index at: https://shinydapps-bd9fa40b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Budget Control

> Set spend limits, track payments by domain, and get callbacks before each transaction.

## Why budget control matters

An AI agent calling paid APIs in a loop can rack up costs fast. Budget control lets you:

* Cap total spend per session
* Set per-domain limits (e.g., max 100 sats/session on `api.weather.com`)
* Receive a callback before each payment
* Get a full spending report at any time

***

## Global budget

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { L402Client, BlinkWallet } from "l402-kit";

    const client = new L402Client({
      wallet: new BlinkWallet(process.env.BLINK_API_KEY!, process.env.BLINK_WALLET_ID!),
      budgetSats: 500, // max 500 sats total this session
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from l402kit import L402Client
    from l402kit.wallets import BlinkWallet

    client = L402Client(
        wallet=BlinkWallet(os.environ["BLINK_API_KEY"], os.environ["BLINK_WALLET_ID"]),
        budget_sats=500,
    )
    ```
  </Tab>
</Tabs>

When a 402 response includes a `priceSats` field and it would exceed the remaining budget, the client throws `BudgetExceededError` **before paying** — no satoshis are spent.

***

## Per-domain budget

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const client = new L402Client({
      wallet,
      budgetSats: 2000,
      budgetPerDomain: {
        "api.weather.com": 100,
        "api.finance.com": 500,
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    client = L402Client(
        wallet=wallet,
        budget_sats=2000,
        budget_per_domain={
            "api.weather.com": 100,
            "api.finance.com": 500,
        },
    )
    ```
  </Tab>
</Tabs>

Per-domain limits are checked independently from the global limit — both must pass for the payment to proceed.

***

## Callbacks

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const client = new L402Client({
      wallet,
      budgetSats: 1000,
      onSpend: (sats, url) => {
        console.log(`✓ Paid ${sats} sats → ${url}`);
        // log to your telemetry, update a dashboard, etc.
      },
      onBudgetExceeded: (url, sats) => {
        console.warn(`✗ Blocked: ${sats} sats requested by ${url} — budget exhausted`);
        // alert, notify Slack, etc.
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    def on_spend(sats: int, url: str) -> None:
        print(f"✓ Paid {sats} sats → {url}")

    def on_budget_exceeded(url: str, sats: int) -> None:
        print(f"✗ Blocked: {sats} sats requested by {url} — budget exhausted")

    client = L402Client(
        wallet=wallet,
        budget_sats=1000,
        on_spend=on_spend,
        on_budget_exceeded=on_budget_exceeded,
    )
    ```
  </Tab>
</Tabs>

`onBudgetExceeded` / `on_budget_exceeded` is called just before `BudgetExceededError` is thrown — useful for logging or alerts.

***

## Spending report

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const report = client.spendingReport();

    if (report) {
      console.log(`Total spent: ${report.total} sats`);
      console.log(`Remaining:   ${report.remaining} sats`);
      console.log("By domain:", report.byDomain);
      // { "api.weather.com": 42, "api.finance.com": 105 }

      for (const tx of report.transactions) {
        console.log(`  ${tx.ts}  ${tx.sats} sats  ${tx.url}`);
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    report = client.spending_report()

    if report:
        print(f"Total spent: {report.total} sats")
        print(f"Remaining:   {report.remaining} sats")
        print("By domain:", report.by_domain)
        # {"api.weather.com": 42, "api.finance.com": 105}

        for tx in report.transactions:
            print(f"  {tx['ts']}  {tx['sats']} sats  {tx['url']}")
    ```
  </Tab>
</Tabs>

`spendingReport()` returns `null` / `None` when no budget is configured.

***

## Handling BudgetExceededError

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { BudgetExceededError } from "l402-kit";

    try {
      const res = await client.fetch("https://api.example.com/premium");
    } catch (err) {
      if (err instanceof BudgetExceededError) {
        console.log(`Need ${err.required} sats, only ${err.remaining} remaining`);
        // gracefully degrade — return cached data, skip this step, etc.
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from l402kit import BudgetExceededError

    try:
        r = client.get("https://api.example.com/premium")
    except BudgetExceededError as e:
        print(f"Need {e.required} sats, only {e.remaining} remaining")
        # gracefully degrade
    ```
  </Tab>
</Tabs>

***

## Concurrency notes

<Warning>
  **Do not share one `L402Client` instance across concurrent `Promise.all` calls when budget limits matter.**

  `BudgetTracker.check()` and `record()` are separated by an `await` (the Lightning payment). Two concurrent `client.fetch()` calls to different endpoints can both pass the budget check before either records the spend — meaning the combined cost can temporarily exceed your budget cap by one payment.

  **Safe pattern — sequential calls:**

  ```typescript theme={null}
  for (const url of urls) {
    const res = await client.fetch(url); // awaited one at a time
  }
  ```

  **Risky pattern — parallel calls:**

  ```typescript theme={null}
  // Both may pass budget.check() before either calls budget.record()
  const results = await Promise.all(urls.map(url => client.fetch(url)));
  ```

  **Mitigation for parallel workloads:** set your `budgetSats` conservatively (e.g. 80% of your true limit) to absorb the over-spend from one concurrent payment. For strict enforcement, process calls sequentially.
</Warning>

***

## Full options reference

| Option        | TypeScript         | Python               | Default   | Description                |
| ------------- | ------------------ | -------------------- | --------- | -------------------------- |
| Global budget | `budgetSats`       | `budget_sats`        | unlimited | Max sats for the session   |
| Per-domain    | `budgetPerDomain`  | `budget_per_domain`  | `{}`      | Map of `domain → max sats` |
| Spend hook    | `onSpend`          | `on_spend`           | —         | Called after each payment  |
| Exceeded hook | `onBudgetExceeded` | `on_budget_exceeded` | —         | Called before throwing     |