EXCHANGES + PUBLISHERS + WALLET
Auctionly is the bidder, campaign manager, publisher portal and billing for running your own ad network. Buy from ad exchanges over OpenRTB 2.5 with a bid out in under 100 ms, or from publishers you onboard yourself with a verified site and one ad tag. Seven ad formats, and every record on a server you control.
You deploy it. You own the database. Nothing phones home.
POST /bid/xyz-ssp Content-Type: application/json { "id": "8f2c…", "tmax": 120, "imp": [{ "id": "1", "banner": { "w": 320, "h": 250 } }], "device": { "os": "android", "geo": { "country": "USA" } } }
Auctionly
{ "seatbid": [{ "bid": [{
"impid": "1", "price": 2.40,
"nurl": "…/win?sig=hmac" }] }] }
no match → 204 + X-Nobid-Reasons: targeting:country=3
<!-- one tag, pasted where the ad goes --> <script async src="…/t/z-4f2a91c07b.js"></script> verified site → ad served → impression counted → paid
Advertisers, and two ways to bring supply: exchanges over OpenRTB, or publishers you onboard directly. One event stream either way. Each step writes to rtb:events, so billing and reporting read the same facts the bidder produced.
Sign up, add funds by card or bank transfer, create a campaign in any of seven formats. It reaches the bidder about three seconds after you save it.
An exchange registers once and posts OpenRTB 2.5 to its own /bid/{exchange} endpoint. A publisher verifies a site, creates a zone and pastes one tag or sends visitors to a URL.
Exchange traffic runs an auction inside the exchange's tmax. Publisher traffic goes to matching campaigns in turn at their fixed prices. The aggregator debits the wallet and credits the publisher one time per impression.
/bid/{exchange}Auction runs against in-memory campaigns./winExchange reports the clearing price. Wallet is debited, once./pixelAd renders and the impression is confirmed./clickRedirect to the advertiser's page, click recorded./conversionPostback matched to the click inside its window./t/{zone}.jsOne script on the publisher's page adds a sized, sandboxed frame./a/{zone}A real browser, on the zone's own site, within the zone's limits.rotationMatching campaigns take turns, each at its own fixed price.impressionServed is counted. Advertiser debited, publisher credited, once./clickRedirect to the advertiser with a click id. A conversion postback matches it.Pick a format and the form asks for exactly the creative that format needs. The web form and the REST API share one rule set, so neither can save a campaign the other would refuse.
displayBanner image or HTML in the sizes the exchange requests.videoA video file or VAST tag, matched to the player size.nativeTitle, description, icon and image that the publisher styles.pushNotification title, body, icon and a destination URL.popA destination URL. No creative to host.domainA destination URL for redirect traffic.deeplinkAn app deeplink or universal link as the destination.Through exchanges all seven formats run. Publishers you onboard directly sell display through an ad tag, and pop, domain redirect and deeplink through a traffic URL. Video, native and push need an ad server, so they stay on OpenRTB.
Display, video and native are read from the OpenRTB imp objects. Push, pop, domain and deeplink are not, so the exchange either sends imp.ext.adformat or is registered with a traffic type.
Advertisers fund a prepaid wallet. Spend is debited as impressions are won, and a campaign pauses when its funds run out. You choose which funding methods to switch on.
Limits are defaults you can change in the environment file. The first-top-up cap applies until an advertiser's first payment has settled, which limits the damage from a stolen card. The wallet balance shows in the top bar, with a warning when it will not cover the recent daily spend. Every credited top-up has a printable receipt with your company details.
The path that answers an exchange is kept small and separate from everything that can be slow.
The bidder reads campaigns from memory and Redis, for exchange bids and publisher views alike. It never opens a database connection, so a slow Postgres cannot slow a bid.
Campaigns, wallets and users live in PostgreSQL. Events flow through a Redis stream to the aggregator and the indexer, at their own pace.
Campaigns are held in memory. The bidder has no database driver in its request loop.
An impression delivered twice is charged once. Events are keyed by stream id, so a redelivery overwrites itself.
A per-request deadline is derived from the exchange's tmax. make latency measures it with wrk on your hardware.
Seeded random malformed bid requests must never crash the parser or the auction. make fuzz
Redis, Postgres, Elasticsearch, mail and a killed worker are injected on purpose. make chaos
If Redis is down, win notices answer 503 so the exchange retries instead of losing the sale.
Banner pictures are served from a media domain by Caddy straight from disk, with immutable caching. Point a CDN at it when traffic grows.
Zones live in their own Redis hash, are fetched on demand and cached for seconds. A new zone never makes every bidder reload the campaigns.
Daily ceilings per address and per zone cap what any one zone can cost advertisers, whatever a script does. TAG_VIEWS_PER_ZONE_PER_DAY
Counts and spend go to PostgreSQL for billing. The raw click goes to Elasticsearch for search and reports, kept 90 days by default.
Seven services, one shared kernel, one Docker Compose file. Read it, change it, ship it.
One campaign form with ad-format cards, budgets, bid hierarchy, delivery limits, creatives, targeting and conversion setup. The API enforces the same rules.
Totals, time series and breakdowns by campaign, day, hour, exchange, bid level, creative, country, OS, device, site, publisher, ad format and zone. CSV export and event-log search.
Give a campaign a CPA or CTR goal and a bid multiplier moves toward what converts, without anyone touching the bid.
Block or allow placements, share large lists between campaigns, and set a bid for one zone straight from the report.
Insert tags like {click_id}, {zone} and {country} into destination URLs. A postback builder writes the conversion URL for your tracker.
Daily and lifetime budgets, pacing, frequency caps, schedules, impression and click limits. A campaign that hits one pauses and records why.
The bidder serves /health and Prometheus /metrics: requests by exchange and outcome, rejections by reason, a latency histogram.
Sign-up, password reset and payment email goes through a queue with retries after 1, 2, 4 and 8 minutes. Bodies are erased once sent.
make fake-data creates advertisers, wallets and campaigns. make traffic sends 300 requests through bid, win, pixel, click and conversion.
An advertiser's campaign waits in review until you approve it or send it back with a note. Trusted advertisers can skip it.
Every credited top-up has a printable receipt with your company details. Sign-up records which version of the Terms was accepted.
Publishers sign up, add a site, create zones and copy a tag. Earnings, payout progress and billing details are in their own area.
A meta tag, a file or a DNS record proves a site is the publisher's. You approve it, and only then can it have zones.
Zones are looked up on demand and kept out of the campaign snapshot, so adding publishers never slows a campaign reload.
Upload creatives in the form or with POST /api/v1/media. Serve them from their own domain, cached for a year, with a CDN in front when you need one.
z-100news.exampleIAB12xyz-sspdefault bidPay more on the zone that converts, and the default everywhere else. Ties are split at random.
Advertisers cannot put a campaign live by themselves. You decide what runs on your network, and the advertiser always hears the outcome.
The advertiser presses submit. The campaign is In review and does not bid.
Administrators get an email and see it on the dashboard, in the In review tab and as a count in the navigation.
Approve and it bids within seconds. Or send it back to draft with a note, which the advertiser is emailed.
Pausing and resuming needs no new review. Changing a creative or its landing URL sends it back.
active gets 202 and pending_review.REQUIRE_CAMPAIGN_REVIEW=false turns it off for everyone.Why it matters. Exchanges hold you responsible for what you show. A review step is the cheapest protection against a misleading ad costing you a supply partner.
Ten endpoints under /api/v1, JSON in and out, one personal token per script. An advertiser's token only ever sees that advertiser's campaigns, and the same validation applies as in the form.
GET /api/v1/meWho the token belongs to.
GET /api/v1/advertisersThe accounts you can see, with wallet balance.
GET /api/v1/campaignsList with filters, paging and sorting.
POST /api/v1/campaignsCreate. The body is the campaign form.
GET · PUT · DELETE /api/v1/campaigns/{id}Read, change or delete one campaign.
POST /api/v1/campaigns/{id}/statusActivate, pause, draft or archive. Activating can answer 202 while it waits for review.
POST /api/v1/mediaUpload a creative image and get its address.
GET /api/v1/reports/campaignsSpend, clicks and conversions per campaign.
$ curl -X POST $BASE/api/v1/media \ -H "Authorization: Bearer $TOKEN" \ -F image=@banner.png { "data": { "url": "https://media.example.com/media/ab/3f…c1.png", "width": 320, "height": 250 } } $ curl -X POST $BASE/api/v1/campaigns/123/status \ -H "Authorization: Bearer $TOKEN" \ -d '{"status":"active"}' HTTP 202 { "data": { "id": 123, "status": "pending_review" } }
An administrator registers the exchange with its token, seat, network margin and traffic type. The exchange gets one endpoint.
/bid/{exchange}, token-checked, pausable.$ curl -X POST localhost:9501/bid/demo \ -H 'Content-Type: application/json' \ -d @services/bidder/fixtures/sample-bid-request.json $ make win # bid, win notice (sent twice), pixel, click # wallet debited once
Most publishers cannot speak OpenRTB. They sign up, add a website, prove it is theirs and paste one tag. There is no auction here: matching campaigns take turns at fixed prices, and the publisher is paid on terms you set.
A publisher creates an account and adds the website it sends traffic from. The site waits for review.
A meta tag, a file at the root, or a DNS TXT record. Any one is enough, and the check refuses private addresses.
Approve or reject with a reason, and the publisher is emailed. Suspend a site and its zones stop at once.
Only an approved site can have zones. A Get tag page gives copy-and-paste code and says what happens next.
<!-- display zone: a banner on the page --> <script async src="https://bid.example.com/t/z-4f2a91c07b.js"> </script> <!-- pop, domain, deeplink: send the visitor --> <a target="_blank" href="https://bid.example.com/r/z-9c13">Open</a> verified site → zone → tag → earnings on the dashboard
A portal of their own: sites and their review status, zones, copy-and-paste tags and a dashboard of impressions, clicks, conversions and earnings.
Earnings are credited together with the advertiser's charge, one time per impression, with the terms that applied kept on each row.
A payout moves through requested, processing and paid, with a reference. The money leaves the balance when it is asked for, and comes back if it is rejected.
Sites waiting for review, payouts to send, quality flags per zone, and a margin view of what advertisers paid against what publishers earned.
Exchanges are contracted companies. Publishers are anyone who signs up, so the platform assumes any number a publisher produces could be false and bounds what it can cost.
A zone serves traffic only while its site is approved. Suspending a site stops its zones at once.
An ad is served only to a page on the zone's own site. Copying the tag onto another site gets nothing.
Bots, crawlers and scripts are not sold. Country and device come from your edge network, not from the publisher.
Per address and per zone, per day, whatever browser string is used. Raise a limit for a large site after a review.
Tracked URLs carry an HMAC. A forged price, campaign or level is refused, and a click or win counts once.
A publisher's own bid requests prove nothing, so the endpoint is opt-in per zone for partners you trust.
Earnings are held for a few days so bad traffic can be taken back with an adjustment before the money leaves.
Zones with a very high click rate, no conversions, or a payout above what advertisers pay are flagged for you.
Honest limits. A redirect has no page to inspect, and a script can fake a referrer. The limits, the hold and the flags are what bound the cost, not a promise that no fake traffic exists.
Admins must enable TOTP. Recovery codes and a 48-hour cancellable lost-phone flow.
Win, pixel and click URLs carry an HMAC, so they cannot be forged.
Sign-ins, account changes and admin actions are recorded.
Cards are credited after Stripe confirms. A worker reconciles lost webhooks.
make backup dumps the database and creatives, keeping as many as you set.
Switch it on and a new account cannot sign in until it opens a one-time link. Only a button confirms, so mail scanners cannot use the link up.
Sign-up requires accepting the Terms and Privacy Policy, and stores which version and when.
Failed sign-ins lock out for 15 minutes. Sign-up, password reset, confirmation email and uploads are rate-limited per address.
Every service is its own container. Start on a laptop, then move the same images to a server.
$ cp .env.example .env $ make install $ make up $ make migrate $ make seed → campaign manager on :9502, bidder on :9501
Seeds an admin, demo advertisers, campaigns and exchanges. make traffic then sends 300 requests through bid, win, pixel, click and conversion.
internet → caddy :80 :443 ├─ campaign-manager └─ bidder private network only: postgres · redis · elasticsearch reporting · aggregator · indexer
Caddy is the only published service. It issues certificates, speaks HTTP/2 and limits request sizes. The written guide takes a fresh Linux server to HTTPS in about 45 minutes, plus DNS.
ok DB_PASSWORD looks strong ok administrators must use two-factor ok Stripe is in LIVE mode FAIL LEGAL_REVIEWED is not true FAIL COMPANY_ADDRESS is empty NOT READY: 2 blocking problem(s)
It refuses to pass while a secret is weak, debug is on, email goes nowhere, Stripe is in test mode or your company details are missing. The owner's guide walks from an empty server to your first advertiser.
MEDIA_DOMAIN=media.example.com MEDIA_BASE_URL=https://media.example.com # or the address of a CDN that pulls from it uploads → ads.example.com → disk viewers → media.example.com → disk
Uploads always go to the app and are saved on your server. The media domain only reads and serves them, so ad images never load from the web app.
Fully self-hosted. There is no Auctionly cloud. Campaigns, wallets, events and creatives stay on your infrastructure, and your data never leaves it.
You receive the code and deploy it yourself. Choose how much help you want with it: none, ongoing support, or a white-label setup we plan with you.
The code, sold once. No consultation and no support: you read it, you run it.
Everything in Tier A, with a team behind it when something needs answering.
Your brand on the whole platform, with our support and consultation. The terms are agreed in a conversation, not listed.
Prices are in US dollars.
No. Auctionly is self-hosted software. You deploy it with Docker on your own server, and your campaigns, wallets and events stay on your infrastructure.
OpenRTB 2.5. Each exchange gets its own /bid/{exchange} endpoint and receives a bid, win notices and tracked clicks.
The target is under 100 ms, typically a few milliseconds. The bidder never touches the database on the bid path, and it applies a deadline derived from the exchange's tmax.
Yes. A publisher signs up, adds a website, verifies it and pastes one ad tag, or sends visitors to a traffic URL. There is no OpenRTB and no auction on that path: matching campaigns take turns at their own fixed prices.
The publisher proves it with a meta tag on the home page, a file at the root of the site, or a DNS TXT record. An administrator then approves the site, and only an approved site can have zones. Suspending or rejecting a site stops its zones at once.
On terms you set per publisher or per zone: a share of what the advertiser spent, or a fixed amount per impression, click or conversion. Earnings are credited once, held for a few days, and paid out on request, with progress from requested to processing to paid.
Ads are only served to the zone's own approved site, bots are not sold, and limits per address and per zone per day bound what any zone can cost. Tracked URLs are signed, OpenRTB is off by default for publisher zones, and earnings are held so bad traffic can be taken back. Zones with odd click rates are flagged for review.
Seven: display, video (VAST), native, push, pop, domain redirect and deeplink. Through publishers you onboard directly, display runs through an ad tag and pop, domain redirect and deeplink through a traffic URL.
They fund a prepaid wallet by card through Stripe or by bank transfer. Card payments are credited only after Stripe confirms them. Bank transfers are credited when an administrator approves the request.
No. An impression that is delivered twice is charged once. Events are keyed by their stream id, so a redelivered event overwrites itself instead of billing again.
Reporting falls back to PostgreSQL rollups. The dimensions that only the event log knows are then reported as unavailable, and bidding is not affected because the bidder only uses Redis.
Yes, by default. An advertiser's campaign waits in review until an administrator approves it or sends it back with a note, and the advertiser is emailed either way. Administrators can mark an advertiser as trusted to skip the review, or switch the review off.
Yes. The REST API has ten endpoints for campaigns, status changes, image upload and reports, with personal tokens and the same validation as the web form. An advertiser's token only sees that advertiser's campaigns.
Not at first. By default the web app serves uploaded images. When traffic grows, serve them from a separate media domain, cached for a year, and put a CDN in front of it. Uploads always go to the app; the media domain only serves files.
Run the demo on your machine, then put it on your own server.
$ make stan # PHPStan level 8, every service $ make fuzz # malformed bid requests $ make chaos # kill redis, postgres, elastic