Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

The bid sanity gate compares each bid’s price against the bidfloor declared on the corresponding impression in the request. A bid price that is many multiples of the floor typically signals a misconfigured bidder — a stale price config, a decimal-point shift, or a currency mismatch. Letting such bids through inflates auction clearing prices and corrupts pacing data.

​
Usage

import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.rtb.tmaxGuard({ bufferMs: 15 }),
    gates.rtb.bidSanity({ maxFloorMultiple: 50 }),
    // ...
  ],
  timeout: 15,
});

​
Options

​
maxFloorMultiple
number
default:"50"
The maximum ratio of bid.price to imp.bidfloor allowed. A bid priced at more than this multiple of the floor fails the gate. Defaults to 50. Must be a positive number — passing zero or a negative value throws at construction time.
​
maxPrice
number
default:"Infinity"
A hard upper bound on bid price regardless of the floor. Useful when you want to cap absolute values in addition to the floor-relative check. Defaults to Infinity (no hard cap).
​
name
string
default:"rtb.bid-sanity"
Override the gate’s name in evaluation results and telemetry.

​
What the gate checks

For every bid in seatbid[].bid[], the gate validates:
  1. Missing price — bid.price is absent or not a finite number → fails with "bid missing price"
  2. Negative price — bid.price < 0 → fails with "bid price is negative"
  3. Hard cap exceeded — bid.price > maxPrice → fails with the price and cap value
  4. Floor ratio exceeded — bid.price / imp.bidfloor > maxFloorMultiple → fails with the computed ratio
The floor is read from imp[].bidfloor on the matching impression (matched by bid.impid). If the impression has no bidfloor set, or if the floor is zero or negative, the ratio check is skipped and only the hard cap applies.

​
Example: failing bid

A request declares a floor of 0.50 CPM for impression imp-001: 
{
  "imp": [
    {
      "id": "imp-001",
      "bidfloor": 0.50,
      "bidfloorcur": "USD"
    }
  ]
}
A bid agent with a stale config returns a price of 75.00 — 150× the floor: 
{
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid-1",
          "impid": "imp-001",
          "price": 75.00
        }
      ]
    }
  ]
}
The gate computes a ratio of 150× against the 50× limit and returns: 
{
  "name": "rtb.bid-sanity",
  "passed": false,
  "reason": "bid price is 150.0x the bidfloor (max 50x)",
  "latency_ms": 1
}

​
Skipping behaviour

The gate returns passed: true, skipped: true when the response contains no bids. If a bid’s impid does not match any impression in the request, the floor check is skipped for that bid (only the hard cap applies).
The bidfloorcur field is read from the request impression but is not used in the ratio calculation — all values are compared as raw numbers. Ensure your bidder normalises prices to the same currency as the floor before submitting.
Start with the default maxFloorMultiple: 50 and tighten it once you have baseline data on your pipeline’s normal price-to-floor ratios. Values between 10× and 20× are common in well-tuned production setups.