Python

Zero runtime dependencies (standard library only). Primarily for server-side ad serving.

Package	`theaimart-adx`
Language	Python 3.8+
Distribution	PyPI
Requirements	Python 3.8+.

Install

pip

bash

pip install theaimart-adx

Usage

Django/Flask/FastAPI handler

python

from theaimart_adx import Adx

adx = Adx(api_key="pk_your_publisher_key")

ad = adx.request_ad(
    slot_id="8b1f2c3d-....-uuid",   # from your publisher dashboard
    page_url="https://yoursite.com/some/page",
    # If you are proxying a request for a real end user, forward THEIR context —
    # otherwise every impression looks like one server IP and gets fraud-scored:
    user_agent=incoming_request.headers.get("User-Agent"),
    client_ip=incoming_request.remote_addr,
)

if ad.filled:
    html_snippet = Adx.render_html(ad)      # inject into your page
    if ad.is_trackable:                      # house ads have no imp_id
        adx.report_viewable(ad.imp_id)
else:
    # No-fill (ad.reason may explain, e.g. "fraud_rejected"). Render nothing.
    ...

Production hardening

SQL-filter-safe encoding of page_url/page_keywords/us_privacy/euconsent_v2 so real URLs never trip the backend WAF.
Fraud-safe User-Agent: sends theaimart-adx-python/<ver> instead of the blocklisted default requests/urllib UA, and lets you forward the real end-user UA.
Parses the 4-way response union into one Ad object and fails closed: any error, timeout, or non-200 -> ad.filled == False, never an exception (unless raise_on_error=True).

These behaviors come directly from the wire contract — see User-Agent rules and WAF-safe encoding for why they matter. Not getting fills? See Troubleshooting.

API

Member	Notes
`Adx(api_key, base_url=…, timeout=…, user_agent=…, transport=…, raise_on_error=False)`	Construct a client.
`request_ad(*, slot_id=…, slot_name=…, page_url=…, page_keywords=…, us_privacy=…, euconsent_v2=…, user_agent=…, client_ip=…, identity_cookie=…) -> Ad`	Request an ad decision.
`report_viewable(imp_id, *, user_agent=…, client_ip=…) -> bool`	Fire the viewability beacon.
`click_url(imp_id) -> str`	Build a click-tracker URL (rarely needed).
`Adx.render_html(ad, css_class=…) -> str`	Render an ad to an HTML snippet.

The normalized Ad model

filled, kind (AdKind.IMAGE/HTML/NO_FILL), source (AdSource.INTERNAL/OPENRTB/HOUSE), imp_id, identity_id, creative, auction, reason, retry_after_seconds, is_trackable, raw.

Build & test

bash

cd packages/python
python -m pip install -e ".[dev]"
python -m pytest            # or: python -m unittest discover -s tests
mypy src/theaimart_adx

The test suite runs with no third-party dependencies via unittest, including an end-to-end test against a local mock server that reproduces the backend WAF to prove the encoding survives it.

Node.js (server)

Rust (server)