Docs/Get started

theaimart adx documentation

Explore the Theaimart ADX wire contract, nine Experimental SDK source runtimes and two web-tag integration references. Check publication, device validation and production eligibility separately.

adx is theaimart's neutral, transparent ad exchange: an ad server, SSP and exchange in one, reachable at https://api.adx.theaimart.co. Every ad request — whether it comes from a website, a mobile app, a game, or a backend proxying requests for real users — goes through the exact same three-call flow:

New to ad networks? Start with Core concepts

If words like "slot", api_key, "fill" or imp_id are unfamiliar, read Core concepts first — a two-minute, plain-language glossary that makes the rest of this page (and everything after it) click into place.

Request — GET /api/v1/serve/ad with your api_key and a slot_id (or slot_name) returns an ad decision.
Render — the response is a discriminated union (internal image / OpenRTB HTML / house image / no-fill). Render the creative; HTML always goes in a sandboxed iframe/WebView.
Report — once the ad has been ≥50% visible for ≥1 continuous second, fire the viewability beacon. Clicks are pre-wrapped for you.

SDK sources follow the shared lifecycle, with different renderers and runtime requirements. Writing your own client requires explicit request, parsing and viewability handling. The wire contract is generated from and verified against the inspected theaimart-adnetwork source, not written from memory, so it stays the single source of truth for all 9 SDKs.

A minimal example

Server-side, using @theaimart/adx — the shape is the same in every other SDK (see the SDK index):

import { Adx } from '@theaimart/adx';

const adx = new Adx({ apiKey: process.env.ADX_API_KEY });

const ad = await adx.requestAd({
  slotId: '8b1f2c3d-....-uuid',
  pageUrl: 'https://yoursite.com/some/page',
  // Forward the END USER's context, not the server's:
  userAgent: req.headers['user-agent'],
  clientIp: req.ip,
});

if (ad.filled) {
  res.send(Adx.renderHtml(ad));
  // Sending HTML does not prove visibility. Report only after the frontend
  // has measured the required visibility threshold for a trackable ad.
}

No SDK for your stack?

The wire contract is a plain REST API — read the contract reference and call it directly. If you already run a header-bidding stack, point it at the inbound OpenRTB 2.5 endpoint from the publisher dashboard instead of integrating an SDK at all.

What's in these docs

Core concepts

New to ad networks? The plain-language glossary — slot, api_key, fill, imp_id, eCPM and everything else — read this first.

Quickstart

Create an account, mint an API key, create a slot and serve your first ad — with expected results at every step.

Wire contract

The versioned REST contract every SDK implements — endpoints, request/response shapes, beacons, errors.

SDK reference

Source API references for nine SDK runtimes, with verified distribution status and rendering limitations.

Security model

The threat model behind every SDK: sandboxed creatives, URL-scheme allowlisting, fail-closed rendering.

Troubleshooting

Stuck? Symptom → cause → fix for the ten problems almost every integration hits.

Platform coverage

Source references cover nine SDK runtimes: Python, Node.js, Rust, Web, React Native, Android, iOS, Flutter and Unity, plus browser tags adx.js and adx-lite.js in source. Source existence does not establish an installable release, target-device acceptance or production eligibility. Check the capability matrix first. See the developer overview for the marketing tour, or jump straight to the SDK reference for install commands and full API surfaces.

Core concepts