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

# Batch Settlement (Planned)

> A planned scheme for high-frequency callers where per-call amounts are too small to settle on-chain individually.

<Warning>
  Batch settlement is planned. It is not implemented in the current facilitator release. This page describes the design so integrators know what to expect and what not to rely on.
</Warning>

## The problem

Stellar settlement is cheap and fast, but not free of latency. For workloads where a single caller makes many sub-cent requests per second (streaming data, per-token metering, high-frequency scraping), per-call settlement adds unnecessary round-trip time and consumes RPC bandwidth.

## The plan

A `batch` scheme where the client authorizes a rolling ceiling and the facilitator settles the aggregate periodically:

* Client signs a `batch` authorization with `amount` (ceiling), `windowSeconds`, and `payTo`.
* Each request against the batch is verified locally by the facilitator (no on-chain call).
* At the end of the window, or when the accumulated total reaches a threshold, the facilitator settles once for the accumulated amount.
* Any unused ceiling expires without moving funds.

## Trade-offs the design has to answer

* **Trust window.** A seller carries counterparty risk for the duration of the batch. Shorter windows reduce risk; longer windows reduce settlement overhead.
* **Refund semantics.** With aggregation, an over-count is possible. The design will require a scheme-level cap and rejection reason to keep this from being an off-chain accounting problem.
* **Discovery.** Batch-eligible endpoints will need a distinct capability flag in `describe` so buyers can find them explicitly.

## What to do today

Use `upto` with a long `maxTimeoutSeconds` if you need something in the neighborhood of batching. It is not the same thing, but it covers the metered-work case until batch ships.
