OpenRTB API Integration Guide

This document is for DSP partners integrating with Lotus ADX. The endpoint is compatible with OpenRTB 2.5, with JSON request and response payloads.

Endpoint: https://ad.cardbbs.net/api/adx/reqrtb?adunit=xxx

Method: POST

Content-Type: application/json

Download OpenRTB 2.5 Spec (PDF)

1. Request Overview

Location	Field	Type	Required	Description
Query	adunit	string	Yes	Ad placement identifier assigned by Lotus (example: banner_home_001).
Body	OpenRTB BidRequest	object	Yes	Standard OpenRTB 2.5 bid request object.

2. Key BidRequest Fields

Field Path	Type	Required	Description
id	string	Yes	Unique request ID.
imp	array	Yes	Impression array, at least one element.
imp[].id	string	Yes	Impression ID.
imp[].bidfloor	number	No	Bid floor price, in the currency defined by bidfloorcur.
imp[].banner / imp[].video / imp[].native	object	Yes	Exactly one media object should be provided.
site or app	object	Yes	Traffic source context, one of site/app.
device	object	Recommended	Device info such as ua, ip, os, ifa.
user	object	Recommended	User identifiers and targeting data.
tmax	integer	Recommended	Timeout in milliseconds, recommended 100-300.
at	integer	No	Auction type, 1 = first price, 2 = second price.
cur	array	No	Accepted currency list, e.g. ["USD"].

3. Request Example

curl -X POST "https://ad.cardbbs.net/api/adx/reqrtb?adunit=banner_home_001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-100001",
    "imp": [
      {
        "id": "1",
        "bidfloor": 0.2,
        "bidfloorcur": "USD",
        "banner": {
          "w": 300,
          "h": 250
        }
      }
    ],
    "site": {
      "id": "site-001",
      "domain": "publisher.example"
    },
    "device": {
      "ua": "Mozilla/5.0",
      "ip": "203.0.113.10",
      "os": "iOS"
    },
    "user": {
      "id": "user-abc"
    },
    "tmax": 120,
    "at": 1,
    "cur": ["USD"]
  }'

4. BidResponse Format

The response follows OpenRTB 2.5 BidResponse format. If there is no valid bid, the server may return HTTP 204 or an empty seatbid.

{
  "id": "req-100001",
  "seatbid": [
    {
      "seat": "dsp-demo",
      "bid": [
        {
          "id": "bid-90001",
          "impid": "1",
          "price": 0.35,
          "adm": "<html>...creative...</html>",
          "crid": "creative-001",
          "adomain": ["advertiser.example"],
          "w": 300,
          "h": 250
        }
      ]
    }
  ],
  "cur": "USD"
}

5. Status Codes and Error Handling

HTTP Status	Meaning	Description
200	Success	A valid BidResponse is returned.
204	No Bid	No eligible ad for this request.
400	Bad Request	Missing parameters, invalid JSON, or unsupported field values.
401/403	Unauthorized	Account is not authorized or credentials are invalid (if auth is enabled).
500	Server Error	Internal platform error. Retry and contact support if needed.

6. Integration Recommendations

Keep total request timeout within 300ms for stable auction performance.
Ensure request IDs are globally unique for troubleshooting and log tracing.
For additional fields (deal, pmp, native assets), please contact technical support for whitelisting.