Skip to main content
This guide walks you through integrating your DSP with the Thrad SSP platform — the full lifecycle from receiving a bid request to getting paid.

​
Auction Process Flow

Here’s how the complete auction and ad delivery process works:

​
1. Bid Request

The SSP sends a bid request to your DSP endpoint with conversation context and user information. Request Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-key> (if configured)
  • X-Forwarded-For: <client-ip>
  • User-Agent: <client-ua>
Request Body: 
{
  "userId": "user_123",
  "chatId": "chat_456",
  "messages": [
    {"role": "user", "content": "Looking for running shoes"},
    {"role": "assistant", "content": "What's your budget?"}
  ]
}
Timeout: 2 seconds maximum

​
2. Your Bid Response

Your DSP analyses the request and returns a bid (or no-bid). Submitting a Bid: The simplest bid response carries bid + bidId. By default, your DSP ships the ad creative inline under ad_data (pre-rendered) so the SSP can serve it without a follow-up call: 
{
  "data": {
    "bid": 7.50,
    "bidId": "bid_abc123",
    "ad_data": {
      "headline": "Premium Running Shoes",
      "description": "Perfect for marathon training.",
      "url": "https://your-dsp.com/click/abc123",
      "advertiser": "Nike",
      "image_url": "https://cdn.nike.com/ad.png"
    }
  }
}
If you can’t or don’t want to pre-render — for example, your creative requires per-win generation — omit ad_data and the SSP will call your /render-ad endpoint when you win. See the Pre-Rendering vs Render Endpoint guide for the trade-offs. Submitting a No-Bid: You have three valid options to signal a no-bid: Option A: HTTP 204 No Content (Recommended) Return an HTTP 204 status code with an empty response body. 
HTTP/1.1 204 No Content
Option B: HTTP 200 with empty data Return an HTTP 200 with an empty data object: 
{
  "data": {}
}
Option C: HTTP 200 with bid: 0 Return an HTTP 200 with a bid value of 0: 
{
  "data": {
    "bid": 0
  }
}
Important: You must respond with one of these options within the timeout period. If you don’t send any response, it will be counted as a timeout error on your side, not a no-bid.
Bid Rounding: Bids should be specified with 2 decimal places (e.g., 7.50, 12.34). If you submit a bid with more than 2 decimals, the SSP will automatically round it using banker’s rounding (IEEE 754):
  • 7.125 → 7.12 (round to nearest even)
  • 7.135 → 7.14 (round to nearest even)
  • 7.145 → 7.14 (round to nearest even)

​
3. First-Price Auction

The SSP runs a first-price auction across all DSP responses:
  • Highest bid wins
  • Winner pays their own bid amount (first-price)
  • Bids below the floor price are rejected
  • In case of a tie (multiple DSPs bid the same amount), the winner is picked randomly

​
4. Render Request (Winner Only — when no ad_data was supplied)

If you pre-rendered (ad_data was included in the bid response), this step is skipped — the SSP serves your creative directly. This is the default and recommended path. If you opted out of pre-rendering, the SSP sends a render request so you can return the creative on demand: 
{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50
}
Timeout: 1 second maximum See Pre-Rendering vs Render Endpoint for when to use each path.

​
5. Ad Delivery

The SSP delivers the creative to the publisher — either the pre-rendered ad_data or the response from your render endpoint.

​
Pricing & Commission

​
SSP Commission

Commission Rate: 10% of your bid
  • The SSP takes a 10% commission directly from your bid
  • Your actual payout is bid amount × 0.90
  • Commission is deducted before payment reaches the advertiser
  • The floor price check is on the gross bid (before commission)
Example:
  • You bid: $10.00 CPM
  • SSP commission (10%): $1.00
  • Net to advertiser: $9.00 CPM

​
Timeouts

Your endpoints must respond within strict time limits:
EndpointTimeoutRecommended Target
Bid2 seconds< 1s
Render (only if you don’t pre-render)1 second< 600ms

​
Integration Steps

​
Step 1: Implementation

  1. Implement the bid endpoint on your server:
    • Bid endpoint (required): receives bid requests, returns bid + creative (ad_data) or no-bid.
  2. Optional: implement a render endpoint if you can’t always pre-render — used when you return a bid without ad_data and need to deliver the creative on demand if you win. Most DSPs ship the creative inline and don’t need this. See Pre-Rendering vs Render Endpoint.
  3. Ensure your responses match the schemas in the API Reference.
  4. Set up infrastructure to handle peak loads (30+ req/sec).

​
Step 2: Testing Phase (5% Traffic)

Once your implementation is ready:
  1. Initial Testing: The SSP will direct 5% of traffic to your DSP
  2. Monitoring: We monitor for:
    • Response time performance
    • Error rates
    • No-bid rates
    • Format compliance
  3. Duration: Testing continues until metrics are within acceptable thresholds

​
Step 3: Scale-Up

Once errors and no-bid rates are below the security threshold:
  1. Traffic gradually increases from 5% → 100%
  2. Continued monitoring during scale-up
  3. Rollback capability if issues arise
Security Thresholds: Your error rate and no-bid rate must remain below acceptable limits. Work with the Thrad team to understand specific threshold requirements.