Minimum-Discount Routing

Minimum-discount base URLs filter SI marketplace seller offers by estimated buyer discount before routing. The threshold is evaluated before the provider request using estimated request tokens or media units. Final realized discount may differ when actual usage differs from the estimate. Buyer-owned priority/fallback providers are not marketplace seller offers and are not covered by the minimum-discount guarantee.

How it works

Prefix the request path with a min{N} segment (the same form is used on x402 paths):

https://api.surplusintelligence.ai/min30/v1

For every marketplace seller candidate the router computes:

estimated_discount_pct = (1 - estimated_buyer_cost / estimated_direct_cost) * 100

An offer qualifies only when estimated_discount_pct >= N. The estimated buyer cost includes the marketplace fee, any platform fee in force, and — on x402 paths — the x402 convenience fee and any conservative buffer. In other words the floor is evaluated on the total you pay, not on a pre-fee subtotal — so enabling a platform fee lowers the advertised discount rather than adding a charge on top of it.

The floor is applied to the request as estimated, which is what makes it a routing gate rather than a settlement guarantee: output length is not known before the response exists, so it is estimated from max_tokens (default 4096). A request that generates far fewer output tokens than estimated can settle at a lower realized discount than the one it qualified on — most visibly on an offer whose discount is concentrated in output pricing. estimated_discount_pct names this honestly; the per-request truth is always GET /v1/requests/{id}.

One consequence worth knowing: because the floor is measured after any platform fee, a non-zero fee makes every floor strictly harder to meet, and caps the maximum achievable discount below 100%. With a fee of r, no offer on a priced model can exceed a (1 − r) discount — even a free one — so floors above that are unsatisfiable for those models. (A free-reference model, where the list price itself is $0, is unaffected: there are no savings to take a share of, so a $0 offer still reports a 100% discount.) If the direct/reference cost is unknown or zero, the offer cannot prove a discount and is skipped.

Grammar

• Valid: min0 through min100.
• No leading zeros: min030 is invalid; min0 is the only zero form.
• No decimals or signs: min30.5, min-1 are invalid.
• Invalid segments return 400 invalid_minimum_discount.

Supported endpoints

x402-paid inference uses these same /min{N}/v1/* paths — the payment rail is selected by the x402 headers on the request, not by a separate path prefix. (There is no /x402/min{N}/... URL; /x402/* is reserved for the resource relays.)

The min-discount mirror applies to inference submit endpoints. Catalog reads (/v1/models, /v1/prices) are shared routes with no min{N} variant — they return the same payload regardless of threshold, and the threshold applies only at inference routing time.

Scope and limits (v1)

• BYOK providers are not covered. Buyer-owned priority/fallback providers are not marketplace seller offers, so they keep the normal routing order and are never subject to the discount threshold. A min30 request can still be served by a priority provider before the marketplace, or by a fallback provider after the marketplace fails.
• Embeddings are excluded. /v1/embeddings has no min-discount route yet; it ships with the embeddings marketplace work.
• Async video/music enforce the threshold at submit time only. Poll/cancel do not re-apply it. Submit responses preserve the min{N} segment in poll_url/cancel_url. Idempotency is scoped by threshold, so a min50 submit will not return a job created earlier by a min0 submit with the same idempotency key.
• Artifact URLs stay non-min: /v1/media/artifacts/....
• x402 text wrappers preserve the min{N} resource URL in payment challenges. MPP / dual-402 does not — the MPP side advertises the non-min resource, so min-discount applies to x402 and API-key paths only in v1.
• min0 means offers must be at least no more expensive than direct/reference pricing — it is not identical to plain /v1 routing if above-direct offers exist.
• min100 requires estimated buyer cost to be zero; with any flat fee, even a zero seller-cost offer fails.

Error shape

When no qualifying marketplace seller meets the threshold and no buyer-owned route applies:

{
  "error": {
    "message": "No marketplace sellers currently meet the minimum 30% estimated discount for 'claude-opus-4.6'. Best otherwise-eligible estimated discount is 18.4%.",
    "type": "no_discounted_offer",
    "code": "minimum_discount_not_met"
  },
  "minimum_discount_pct": 30,
  "best_available_discount_pct": 18.4
}

This is returned (HTTP 503) only when minimum discount is provably the blocking condition. Trust filters, caps, health backoff, and price ceilings retain their existing error semantics and precedence.

Examples

OpenAI SDK:

const client = new OpenAI({
  apiKey: process.env.SURPLUS_API_KEY,
  baseURL: 'https://api.surplusintelligence.ai/min30/v1',
})

curl:

curl https://api.surplusintelligence.ai/min30/v1/chat/completions \
  -H "Authorization: Bearer $SURPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.6",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": true
  }'