> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thrads.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding

> End-to-end walkthrough: request/response shape, pricing, timeouts, and the integration, test, and scale-up process.

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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/dsp/guides/rendering) 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 theme={null}
HTTP/1.1 204 No Content
```

**Option B: HTTP 200 with empty data**

Return an HTTP 200 with an empty `data` object:

```json theme={null}
{
  "data": {}
}
```

**Option C: HTTP 200 with bid: 0**

Return an HTTP 200 with a bid value of 0:

```json theme={null}
{
  "data": {
    "bid": 0
  }
}
```

<Warning>
  **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.
</Warning>

**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:

```json theme={null}
{
  "bidId": "bid_abc123",
  "realizedPrice": 7.50
}
```

**Timeout**: 1 second maximum

See [Pre-Rendering vs Render Endpoint](/dsp/guides/rendering) 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:

| Endpoint                                    | Timeout   | Recommended Target |
| ------------------------------------------- | --------- | ------------------ |
| **Bid**                                     | 2 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](/dsp/guides/rendering).

3. Ensure your responses match the schemas in the [API Reference](/dsp/api-reference/dsp-bid).

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

<Note>
  **Security Thresholds**: Your error rate and no-bid rate must remain below acceptable limits. Work with the Thrad team to understand specific threshold requirements.
</Note>