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

# Balance Block

> Querying account balances from upstream APIs.

The `balance` block instructs ONR on how to query and parse the remaining credit balance available on a specific API Key for the upstream provider.

This is particularly useful when combined with the Admin Panel CLI or Web UI to monitor your credential fleet automatically.

Global reusable presets can now be declared in `config/modes/balance_modes.conf` and included from `config/onr.conf`:

```nginx theme={null}
balance_mode "openai" {
  usage_path "/v9/dashboard/billing/usage";
}
```

```nginx theme={null}
provider "demo" {
  defaults {
    balance {
      balance_mode openai;
    }
  }
}
```

## Syntax

```nginx theme={null}
balance {
  balance_mode <mode>;
}
```

### Built-in Modes

* `openai`: Leverages standard OpenAI Dashboard endpoints to report remaining USD.
* `custom`: Explicitly fetch and parse an arbitrary JSON endpoint.

In this repository's default config, `config/modes/balance_modes.conf` also declares `openai` as a global `balance_mode` preset, so it can be overridden in DSL if needed.

## Custom Balance Parsing

If a provider does not support OpenAI-like `/dashboard/billing/credit_grants` endpoints, you can write complete request and parse directives.

```nginx theme={null}
balance {
  balance_mode custom;
  
  method GET;
  path "/v1/user/balance"; # relative to base_url, or absolute
  
  # Inject Required Auth Headers
  set_header "Authorization" concat("Bearer ", $channel.key);
  
  # Parse out the JSON float amount for remaining/used credits
  balance_path "$.data.available_balance";
  used_path "$.data.consumed_amount";
  
  # (Optional) USD or CNY
  balance_unit "USD";
}
```

### Value Arithmetic

If your endpoint returns an expression or you need to do basic +/- operations instead of strictly extracting the path, you can use the expression fields.

```nginx theme={null}
balance {
  balance_expr = "$.data.total - $.data.used";
}
```

*Note: The expression allows a restricted syntax using JSONPaths and basic +/- arithmetic.*