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 floor is evaluated on the total you pay - on x402 paths that includes the x402 convenience fee and any conservative buffer - not on a subtotal.

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

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 do accept the segment - /min30/v1/models returns 200, not 404 - but the threshold changes nothing there: you get the same payload regardless, because it only applies 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 and cancel have no min{N} form at all - only submit takes the discount segment, and poll_url / cancel_url are always returned bare (/v1/video/generations/:id). Use the URLs the submit response gives you rather than constructing them. 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.
• 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, so only a genuinely free offer can satisfy it.

Error shape

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

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

The envelope is fixed - { error: { type, code, message, detail?, param? }, request_id? } - so there are no top-level minimum_discount_pct / best_available_discount_pct fields. Read the figures from message.

This is returned as HTTP 404 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
  }'