Skip to main content
This guide walks you through integrating your DSP with the Thrad SSP platform.

​
Traffic Overview

Once integrated, your DSP will receive full traffic from the Thrad SSP:
  • Average Volume: ~50,000 requests per hour
  • Peak Traffic: Up to 30 requests per second
  • Traffic Type: Real-time bid requests from active chat conversations
Be prepared to handle peak loads of 30+ requests per second. Ensure your infrastructure can scale to meet these demands.

​
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. 
{
  "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 analyzes the request and returns a bid (or no-bid). Submitting a Bid: 
{
  "data": {
    "bid": 7.50,
    "bidId": "bid_abc123"
  }
}
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 Validation: The SSP validates your bid response. The following will cause your bid to be rejected:
  • ❌ Response is not a valid JSON object (e.g., Exception, None, string)
  • ❌ Missing bidId field when bid > 0
  • ❌ bid is not a number (e.g., “three dollars”)
  • ❌ bid is below the floor price ($4.00 CPM)
Make sure your response passes validation to participate in the auction.

​
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

​
4. Render Request (Winner Only)

If your DSP wins, the SSP sends a render request to generate the ad creative. 
{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50
}
Timeout: 1 second maximum

​
5. Ad Delivery

Your DSP returns the ad creative, which the SSP delivers to the publisher.

​
Pricing & Commission

​
Floor Price

Minimum bid: $4.00 CPM (gross)
  • Any bid below $4.00 will be rejected before the auction
  • The floor applies to your gross bid (before 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< 300ms
Render1 second< 300ms
If your endpoint doesn’t respond within the timeout, your bid will be excluded from the auction. Optimize for low latency!

​
Integration Steps

​
Step 1: Implementation

  1. Implement the required endpoints on your server:
    • Bid endpoint: Receives bid requests, returns bid or no-bid
    • Render endpoint: Generates ad creative for winning bids
  2. Ensure your endpoints return responses in the required format (see API Reference)
  3. 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.

​
Payment and Billing

At the end of each calendar month, Thrad will send you an invoice for the amount due based on your winning bids.

​
How It Works

  1. Monthly Calculation: We calculate your total winning bid amount for the calendar month
  2. Commission Deduction: The 10% SSP commission is deducted from your gross bids
  3. Invoice: You receive an invoice with the net amount due to the publisher
  4. Payment: Payment terms will be agreed upon during integration setup
Example:
  • Total winning bids for the month: $10,000
  • SSP commission (10%): -$1,000
  • Net amount due to publisher: $9,000
The invoice will include detailed reporting of all winning auctions, impressions, and any applicable adjustments.

​
Support

For integration support or questions, contact us at contact@thrads.ai Ready to get started? Review the API Reference for detailed endpoint specifications.