Bidding Agent

Having your own "bidding agent" in Beeswax allows you to implement custom real-time decisioning in your private bidder. Common use cases for real-time decisioning include custom bid price algorithms, custom budget pacing or custom creative decisioning including dynamic creatives. Bidding agents can be written in any language, they simply must be able to parse our data interfaces and respond within the strict timeout of 10ms.

The diagram below shows how a bidding agent for real time price decisioning works:

Bidding Agents in Practice

Reading from left to right in the diagram, the Stinger bidder receives a fully normalized open RTB request. Once it enters the bidder, Beeswax applies several layers of filtering to determine which line items configured in Buzz match the given request and ares thus eligible to serve. The layers of filtering include matching targeting and creative attributes, respecting any user-specific frequency caps, keeping within the daily and total budgets, and pacing evenly. What remains after filtering is a list of line items that are eligible to bid for this request – we call these ad candidates in our protobuf definitions.

Next, the Private Bidder makes an HTTP POST containing the request.proto to a bidding agent outside of the Beeswax cloud, typically hosted by a customer in the same AWS Region. The request proto contains both the full openRTB request along with a list of the eligible line items. The Bidding Agent must receive this request, parse it, and either respond with an HTTP 204 to not bid, or an HTTP 200 with a list of line items and corresponding bid prices. We enforce a strict timeout of 10ms for your HTTP response, so it is important that your Bidding Agent is in the same AWS region and highly performant.

Data Interfaces and Tools

The following are all the data interfaces used when implementing a bidding agent:

request.protoThe interface between the bidder and the bidding agent. Includes both the openRTB request and the adcandidates
openrtb.protoThis proto is imported by the request.proto. It contains the full openRTB request
adcandidates.protoThis proto is imported by the request.proto. It contains all the candidate line items for the given request

The following tool can be used to stream sample bidding agent requests to an endpoint

Bid requestor toolThis tools generates Beeswax bid http requests
and sends to a designated endpoint with http headers used in the bidding service
and http body generated from the specified input file.


A common technique for bidding algorithms is to "pace" buying during the day or over the lifetime of the campaign in order to deliver ads on a regular schedule. Beeswax supports what we call "Pacing-as-a-Service" for Bidding Agents where customers can utilize their own algorithms with our built-in pacing. This service works by filtering bids to your Bidding Agent based on the ratio of current delivery against goals.

There is no technical implementation required to utilize Beeswax pacing, as long as the strategy is set up to do so when first created by the Beeswax team.

Response Codes

See also: Bidding Agent and Augmentor Response Codes, Bidding Agent Supported Fields