Docs/Get started

theaimart adx documentation

Everything you need to serve ads from the theaimart Ad Network — one versioned wire contract, implemented natively across 9 platforms plus two drop-in web tags.

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.

Every official SDK implements this identically, so switching platforms — or writing your own client against the raw contract — never changes the mental model. The wire contract is generated from and verified against the live theaimart-adnetwork backend, not written from memory, so it stays the single source of truth for all 9 SDKs.

A minimal example

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

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

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));
  if (ad.isTrackable) await adx.reportViewable(ad.impId!);
}

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

Install + usage + full API surface for all 9 native SDKs, plus the adx.js / adx-lite.js drop-in tags.

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

Eleven integration surfaces implement the same contract: native SDKs for Python, Node.js, Rust, Web, React Native, Android, iOS, Flutter and Unity, plus the zero-build adx.js drop-in tag and adx-lite.js for low-bandwidth 2G/3G audiences. See the developer overview for the marketing tour, or jump straight to the SDK reference for install commands and full API surfaces.

Core concepts