> ## 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.

# Upto Scheme

> Metered payments where the client authorizes a ceiling and the seller settles for the actual amount used.

The `upto` scheme handles the case where the seller does not know the final price at request time. The client authorizes a ceiling, the seller does the work, and settlement charges the actual amount consumed (never more than the ceiling).

## Wire shape

```json theme={null}
{
  "scheme": "upto",
  "network": "stellar:testnet",
  "amount": "1000000",
  "asset": { "address": "CBIELTK6...", "decimals": 7 },
  "payTo": "GCKF...",
  "maxTimeoutSeconds": 600,
  "extra": {
    "pricing": {
      "unit": "1k_tokens",
      "pricePerUnit": "5000"
    }
  }
}
```

`amount` is the **ceiling**, not the final price. `extra.pricing` is optional but strongly recommended: it tells buyers what unit they are being metered on. See [Declaring Discovery Metadata](/guides/sellers/declaring-discovery-metadata).

## Settlement

After the seller finishes the work, they call `/settle` with an `actualAmount` less than or equal to `amount`. The facilitator settles for `actualAmount` and discards any remaining authorization. There is no refund step, because no funds move until settle.

```http theme={null}
POST /settle
{
  "paymentPayload": { ... },
  "paymentRequirements": { ... },
  "actualAmount": "340000"
}
```

If `actualAmount` exceeds `amount`, `/settle` returns `amount_exceeds_ceiling` and no funds move.

## When to use it

* LLM completions, transcription, translation, any pay-per-token workload.
* Data queries where response size determines cost.
* Long-running jobs where the final cost is only known when the job finishes.

## When not to use it

* Simple per-request pricing. Use [`exact`](/payment-schemes/exact) so buyers can budget precisely.

## Buyer-side considerations

Agents should set ceilings that reflect what they are willing to spend, not "a very large number." See [Budgets & the Upto Scheme](/guides/buyers/budgets-and-upto) for how to compose per-call ceilings with session-level budgets in a smart account contract.

## Related

* [Choosing a Pricing Scheme](/guides/sellers/choosing-a-pricing-scheme)
* [POST /settle](/api/settle)