SSP integration
Supply-side platforms can send OpenRTB 2.5 or 2.6 banner bid requests to BIDTORA. Authorized, clean traffic runs a first-price auction across enabled production demand, and we answer with a single bid that is already net of the exchange fee.
Getting access
- /Supply partners are created by the BIDTORA team. You receive an SSP id, an API key (shown once) and, optionally, a dashboard login.
- /Your SSP is listed in our sellers.json as seller_type INTERMEDIARY with seller_id = your SSP id.
- /Each partner has a QPS limit. Requests over the limit get HTTP 429.
Endpoint and authentication
- /POST https://bidtora.io/rtb/ssp/{SSP_ID}
- /Send your key in X-Api-Key (or Authorization: Bearer). Keys are stored as hashes. If a key leaks, ask us to rotate it.
- /Body: OpenRTB 2.5 or 2.6 JSON; optional Content-Encoding: gzip. Both compressed and decompressed bodies are limited to 64 KB. Currency USD only.
Bid request
Required fields are id, imp[0].id, imp[0].banner with w/h or format, and site with a valid domain, device.ua and the end user’s public device.ip or device.ipv6. Exactly one impression is accepted, and only banner is supported today. App, native, video and popunder inventory are not supported. We pass site, app, device, user, regs, bcat and badv through to DSPs.
POST https://bidtora.io/rtb/ssp/{SSP_ID}
Content-Type: application/json
X-Api-Key: bt_ssp_••••••••
X-Openrtb-Version: 2.6
{
"id": "req-7f3a91",
"tmax": 120,
"cur": ["USD"],
"imp": [{
"id": "1",
"tagid": "homepage-mrec",
"banner": { "w": 300, "h": 250, "format": [{ "w": 300, "h": 250 }] },
"bidfloor": 0.40,
"bidfloorcur": "USD",
"secure": 1
}],
"site": { "domain": "news.example", "page": "https://news.example/story",
"publisher": { "id": "pub-123" } },
"device": { "ua": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/130.0 Mobile Safari/537.36", "ip": "203.0.113.7" },
"source": { "tid": "tid-55", "schain": { "complete": 1, "ver": "1.0",
"nodes": [{ "asi": "your-ssp.example", "sid": "pub-123", "hp": 1 }] } }
}Timeouts
OpenRTB 2.5 and 2.6 requests use the same banner subset; responses and outbound DSP requests declare 2.6. The deadline is the lower of your tmax and 100 ms. DSPs get that deadline minus 10 ms. Set your client timeout to at least your tmax plus network round-trip time.
Bid response
HTTP 200 with one bid, or HTTP 204 for no bid. price is a USD CPM net of your take rate: the gross winning bid × (1 − take rate). Your bidfloor is applied to this net price.
HTTP/1.1 200 OK
Content-Type: application/json
X-Openrtb-Version: 2.6
{
"id": "req-7f3a91",
"bidid": "<32-hex bid id>",
"cur": "USD",
"seatbid": [{ "seat": "bidtora", "bid": [{
"id": "<32-hex bid id>",
"impid": "1",
"price": 2.125,
"adm": "<a href=...><img ...></a>",
"crid": "<creative id>",
"w": 300, "h": 250,
"nurl": "https://bidtora.io/rtb/ssp/win?r=<bid id>&p=${AUCTION_PRICE}",
"burl": "https://bidtora.io/rtb/ssp/bill?r=<bid id>&p=${AUCTION_PRICE}"
}]}]
}Win and billing notices
- /Fire nurl when our bid wins your auction. Fire burl when the ad renders, as the billable event. Replace ${AUCTION_PRICE} with the clearing CPM.
- /Both are GET requests that return a 1×1 GIF. Each notice is counted once. A notice must arrive within 1 hour of the bid (4 hours for burl).
- /We forward the win and billing notices to the winning DSP with its own price macros filled in.
Supply chain (schain)
We require a complete, valid SupplyChain 1.0 object in source.schain (or source.ext.schain) and add our own node, {"asi":"bidtora.io","sid":"<SSP_ID>","hp":1,"rid":"<our request id>"}, before sending the request to DSPs.
Inventory authorization and IVT
- /The last schain node asi must match your registered SSP domain. Nodes require valid asi, sid and hp=1; duplicate and BIDTORA loop nodes are rejected.
- /Each publisher must authorize bidtora.io, YOUR_SSP_ID, RESELLER in its own ads.txt and authorize the first schain seller. Each supplied schain seller ID must exist in that advertising system’s sellers.json.
- /We validate ads.txt and sellers.json asynchronously over HTTPS, with SSRF protection and cached results. First-time or unverified inventory receives HTTP 204 until authorized; unavailable or unauthorized inventory receives no bids.
- /Known bot UAs, empty/invalid browser UAs, non-public IPs, hosting/datacenter IPv4 and IPv6, device OS/UA inconsistencies, configured blocklists, excessive per-IP frequency and UA rotation are filtered and logged per partner. These are heuristic GIVT controls, not third-party fraud certification.
- /Per-partner QPS limits return 429. Rejected IVT returns 204. Authorization rejections and IVT have separate reporting counters.
- /sellers.json: https://bidtora.io/sellers.json. Publisher integration: /docs/publisher-integration. No platform GEO allowlist; Asia and Middle East may be submitted after approval. Availability and fill depend on connected production demand; fill is not guaranteed.
Commercial terms
Standard supply partners receive 90%; approved Top/premium partners receive 95%. Net-30 after month end, $100 minimum payout, via PayPal, Payoneer or wire. Publisher accounts require 50k+ monthly visits. BIDTORA, Karachi, Pakistan.
Test traffic
Set test=1 for non-billable tests. Test responses never contain chargeable win or billing notices and never create production revenue. Coordinate test demand before testing: a valid request may return 204 when no production buyer is eligible.
Errors
- /400: invalid JSON or a missing required field (the reason is in the JSON body).
- /401: unknown SSP, or a missing or wrong API key.
- /403: SSP paused.
- /413: body too large.
- /415: unsupported content encoding.
- /429: QPS limit exceeded.
- /503: reporting persistence unavailable; do not bill.
Quick test
curl -s https://bidtora.io/rtb/ssp/$SSP_ID \
-H "Content-Type: application/json" \
-H "X-Api-Key: $BIDTORA_KEY" \
-d @bidrequest.json -w "\nHTTP %{http_code} in %{time_total}s\n"