Discount floor and price cap

Kyvalt sends each request to the cheapest healthy seller offer for the model. A discount floor or a price cap narrows the offers it may use, so a request never costs more than you decided.

How an offer is chosen

1. Kyvalt collects the live offers for the requested model.
2. It drops offers that are over their seller's daily limit, below your discount floor, or above your price cap.
3. It tries the cheapest healthy offer first. If that seller fails, Kyvalt retries the next offer automatically, so a single failing seller does not fail your request. A failed attempt is never charged.

Requests from the same account that share a prompt prefix stay on the same offer for a few minutes, so provider prompt caching keeps working and cached input tokens are billed at the lower cached rate.

Discount floor

A floor is a whole-number percentage from 0 to 100. With a floor of 40, only offers priced at least 40% below list price can serve the request. You can set it in three places; when more than one is set, the highest wins.

curl https://api.kyvalt.com/v1/chat/completions \
  -H "Authorization: Bearer $KYVALT_API_KEY" \
  -H "X-Min-Discount: 40" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4-pro", "max_tokens": 200, "messages": [{"role": "user", "content": "Hello"}]}'

The URL form is useful for tools that let you change the base URL but not add headers:

client = OpenAI(api_key=os.environ["KYVALT_API_KEY"], base_url="https://api.kyvalt.com/min40/v1")

If no offer meets the floor, the request returns 404 minimum_discount_not_met and nothing is charged. A header value that is not a whole number from 0 to 100 returns 400 invalid_min_discount_header.

Price cap

Add max_price_per_1m to the JSON body to set the most you will pay, in US dollars per 1M output tokens. Offers above it are skipped.

{
  "model": "deepseek-v4-pro",
  "max_price_per_1m": 2.5,
  "max_tokens": 200,
  "messages": [{"role": "user", "content": "Hello"}]
}

With the OpenAI Python SDK, pass it through extra_body={"max_price_per_1m": 2.5}. If no offer is under the cap, the request returns 404 max_price_exceeded and nothing is charged.

Never above list price

Without a floor or cap, Kyvalt still only uses offers priced at or below the provider's list price, after its fee.