RTB Overview
The RTB exchange speaks OpenRTB over JSON. You post a BidRequest describing the
impression, we run it against our demand pool, and we answer with the winning
BidResponse or with 204 when nothing bid.
If your inventory is banner, video, audio or native, this is your wire. For direct link, pop and push supply, the XML feed is simpler and will serve you better.
Supported versions
We support OpenRTB 2.6 and OpenRTB 2.5. Declare which one you are sending on every call:
x-openrtb-version: 2.6
The header is how we pick the parser, so send it on every request. When it is
absent we assume 2.6. Objects and field names follow the IAB specification
exactly for the version you declare, and the reference pages here note where a
field exists in one version and not the other.
The 2.6 fields most partners care about are imp.rwdd, imp.ssai, bid.mtype,
video.plcmt and device.sua. Under 2.5 they are simply absent, and nothing
else changes.
Endpoint
POST /v1/auction/{endpoint_key} HTTP/1.1
Host: rtb.adon3-ads.com
Content-Type: application/json; charset=utf-8
Accept: application/json
Accept-Encoding: gzip
x-openrtb-version: 2.6
{endpoint_key} is issued by the adon3 integration office and identifies your
supply account. Keep it server side.
The rules that apply to every call:
- Method is
POST.GETis not supported. - Content type is
application/json; charset=utf-8. Bodies are UTF-8 with no BOM. - Scheme may be HTTP or HTTPS. Both are accepted on the same host.
- Encoding may be gzip either way. Send
Content-Encoding: gzipwhen you compress, andAccept-Encoding: gzipto receive one. - Connections should be keep-alive.
- Bodies are capped at 256 KB. Above that we return
413. - One impression per request. Send a single entry in
imp.
What we require
On top of the IAB specification, adon3 requires four things on every request. They are the difference between traffic our buyers will bid on and traffic they will not.
| Requirement | Field | Notes |
|---|---|---|
| User agent | device.ua | Required. Send it unmodified. Under 2.6 you may send device.sua as well, but device.ua is still required. |
| Address | device.ip or device.ipv6 | At least one is required. Send the visitor's address, not your server's. |
| Inventory identity | site.domain or app.bundle | At least one is required, matching whichever object you send. |
| Auction id | id | Required by the specification, and echoed on every response and error. |
A request missing any of them is rejected with 400 before it reaches a bidder.
The full list of validation codes is on Errors & No-Bids.
What we return
| Outcome | Status | Body |
|---|---|---|
| A bid | 200 | A JSON BidResponse carrying one seatbid with one bid |
| No bid | 204 | Empty |
We return the single winning bid rather than the whole bid landscape. There is nothing to rank on your side: render the bid, fire the notices, and bill against the price we substitute.
Supply chain
Send source.schain on every request. Every node must resolve against the
sellers.json published at that node's asi domain, and complete should be
1 unless you genuinely cannot see the full chain.
Chains that do not resolve are rejected with SCHAIN_INVALID before reaching a
bidder. This catches a good number of first integrations, so verify yours before
you write any code.
Time and currency
All timestamps across adon3 are UTC. Prices are CPM in cur, and USD is the
only settlement currency at launch. imp.bidfloor may be expressed in a
different bidfloorcur, which we convert at the daily rate before comparing.
What to read next
Quick Start takes you from an endpoint key to live traffic. Bid Request documents everything you send us, Bid Response documents what comes back, and the samples are complete bodies you can post today.