Publisher Documentation

Pick the right format for what you want

Tag URL formats

After creating a placement you'll see a tag URL in the dashboard. The shape depends on the format:

# video_session → VMAP
https://app.popadsnetwork.com/api/vmap/pop-7f3bafe6

# pause_screen → VAST with t=pause
https://app.popadsnetwork.com/api/vast/pop-7f3bafe6?t=pause

# display → JS tag (drop in a <script src="…">)
https://app.popadsnetwork.com/api/tag/pop-7f3bafe6

Worked example: a video page with all four ad types

Say you want pre-roll, mid-rolls, post-roll, in-stream overlay, pause-screen, and a 728×90 banner above the player. Here's the full publisher-side wiring.

Step 1 — Create three placements on the dashboard

Step 2 — Drop the SDK + display tag in your page

<!-- Loaded once per page -->
<script src="https://app.popadsnetwork.com/popads-sdk.js" async></script>

<!-- 728×90 banner above the player. Standalone, no SDK needed. -->
<script
  src="https://app.popadsnetwork.com/api/tag/pop-BANNER789?creator_id=42&content_id=video-abc"
  data-refresh="60"
  async>
</script>

<div id="player-wrap">
  <video id="my-video" controls></video>
</div>

Step 3 — One PopAds.init() call wires the video + pause inventory together

PopAds.init({
  playerInstance:  player,                                                                // your player object
  playerType:      'bitmovin',                                                            // 'bitmovin' | 'videojs' | 'jwplayer' | 'html5'
  playerContainer: document.getElementById('player-wrap'),

  vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-VIDEO123',                 // video_session: pre/mid/post + overlay
  pauseAdUrl:      'https://app.popadsnetwork.com/api/vast/pop-PAUSE456?t=pause',         // pause_screen

  overlayPosition: 'top-right',                                                           // for the overlay non-linears in vmapUrl
  pauseMinSeconds: 3,                                                                     // debounce; ignore quick scrubs

  contentId:       videoId,                                                               // optional attribution — see Creator Attribution
  creatorId:       creatorUuid,
  creatorWallet:   creatorSolanaAddress,

  viewerWallet:    solanaWalletAddress,                                                   // optional — logged-in viewer's wallet, unlocks Audience Insights
  viewerExternalId: hashedUserId,                                                         // optional — for non-wallet auth; hash before send
})

What serves where

• Pre-roll, mid-rolls, post-roll, in-stream overlay — all from vmapUrl (the video_session placement). Single VMAP, all four break types.
• Pause-screen ad — from pauseAdUrl (the pause_screen placement). Suppressed automatically while a linear ad is playing.
• 728×90 above the player — from the display tag <script>. Independent lifecycle from the SDK; the page can have as many of these as it wants in different slots.

Notice there's no separate overlayVmapUrl — overlays come from the same vmapUrl as the linear breaks. If you only want overlays (no pre-roll), keep the same video_session placement and just untick "Pre-roll" / "Post-roll" and leave mid-rolls empty in placement settings. The VMAP will emit only the NonLinear overlay breaks; same URL, same SDK call.

1. Load the SDK

Drop this once per page, before your player code runs:

<script src="https://app.popadsnetwork.com/popads-sdk.js" async></script>

2. Initialise after your player loads

PopAds.init({
  playerInstance:  player,                                        // your player object
  playerType:      'bitmovin',                                    // 'bitmovin' | 'videojs' | 'jwplayer' | 'html5'
  playerContainer: document.getElementById('player-wrap'),        // DOM node containing the <video>
  vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-XXXXXXXX',
  contentId:       videoId,           // optional — per-content attribution
  creatorId:       creatorUuid,       // recommended — per-creator attribution
  creatorWallet:   creatorSolanaAddr, // optional — helps with payouts
  viewerWallet:    solanaWalletAddress, // optional — viewer's wallet; unlocks Audience Insights (see Audience Insights)
  viewerExternalId: hashedUserId,     // optional — for non-wallet auth; hash internal user ID server-side
  contentType:     'long_form',       // 'short_form' | 'long_form' | 'live' — drives Better Ads + mid-rolls
  contentDuration: video.duration,    // seconds — enables dynamic mid-roll cadence on long-form
  mutedOnStart:    true,              // default true; in-player unmute button shown to viewer
  overlayPosition: 'top-right',
})

Bitmovin

const player = new bitmovin.player.Player(container, { key: 'YOUR_BITMOVIN_KEY' })
await player.load({ hls: 'your-stream.m3u8' })

PopAds.init({
  playerInstance:  player,
  playerType:      'bitmovin',
  playerContainer: container,
  vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-XXXXXXXX',
  creatorId:       creator.id,
})

Video.js

<video id="my-video" class="video-js" controls preload="auto">
  <source src="your-video.mp4" type="video/mp4">
</video>

<script>
  const player = videojs('my-video')
  PopAds.init({
    playerInstance:  player,
    playerType:      'videojs',
    playerContainer: player.el(),
    vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-XXXXXXXX',
    creatorId:       creator.id,
  })
</script>

JW Player

const player = jwplayer('my-player').setup({ file: 'your-video.mp4' })
const container = document.getElementById('my-player')

PopAds.init({
  playerInstance:  player,
  playerType:      'jwplayer',
  playerContainer: container,
  vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-XXXXXXXX',
  creatorId:       creator.id,
})

HTML5 native

<div id="player-wrap">
  <video id="my-video" controls>
    <source src="your-video.mp4" type="video/mp4">
  </video>
</div>

<script>
  const player = document.getElementById('my-video')
  PopAds.init({
    playerInstance:  player,
    playerType:      'html5',
    playerContainer: document.getElementById('player-wrap'),
    vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-XXXXXXXX',
    creatorId:       creator.id,
  })
</script>

Basic placement

<script
  src="https://app.popadsnetwork.com/api/tag/pop-XXXXXXXX?creator_id=42&content_id=article-123"
  async>
</script>

The placement's banner_size (set when you create it — 728×90, 300×250, etc.) determines which creatives are eligible.

Auto-refresh (optional)

Add data-refresh to rotate banners on a timer. Refresh is gated by viewability — it only fires when the slot is on-screen and the tab is visible.

<script
  src="https://app.popadsnetwork.com/api/tag/pop-XXXXXXXX"
  data-refresh="60"
  async>
</script>

Minimum refresh interval: 30 seconds.

Manual refresh (SPAs)

window.PopAds.refresh('popads-pop-XXXXXXXX')

Creative dimensions

PNG, JPG, or WebP up to 500 KB. The SDK renders at 50% width × 50% height of the player, centred, with a close button.

Create the placement

In your dashboard → Placements → New Placement, pick Video Overlay Pause, choose creative size, and set the minimum pause duration (1–10 seconds — defaults 3, stops scrubbing from triggering ads). You'll get a tag URL like:

https://app.popadsnetwork.com/api/vast/pop-XXXXXXXX?t=pause

Wire it into the SDK

Pass the pause tag URL alongside (or instead of) your VMAP URL in the same PopAds.init() call:

PopAds.init({
  playerInstance:  player,
  playerType:      'bitmovin',
  playerContainer: document.getElementById('player-wrap'),
  vmapUrl:         'https://app.popadsnetwork.com/api/vmap/pop-VIDEOXXX',   // optional — pre/mid/post-roll + overlay
  pauseAdUrl:      'https://app.popadsnetwork.com/api/vast/pop-PAUSEXXX?t=pause', // optional — pause-screen ad
  pauseMinSeconds: 3,                  // optional — debounce
  contentId:       videoId,
  creatorId:       creatorUuid,
})

vmapUrl and pauseAdUrl are independent — pass either, both, or neither.

Pass it at init

PopAds.init({
  // …
  contentType:     'long_form',    // 'short_form' | 'long_form' | 'live'
  contentDuration: video.duration, // seconds — drives dynamic mid-rolls on long_form
})

What each classification does

Mid-roll cadence (long-form)

Configured per placement in the dashboard. Dynamic cadence computes break points from the runtime contentDuration + four knobs:

• Interval — how often to insert a break (e.g. 900s = 15 min)
• Lead-in — protected window at the start (default 300s = 5 min)
• Tail-out — protected window at the end (default 120s = 2 min)
• Max breaks — hard ceiling, e.g. 6 breaks on a 2-hour film

A 90-min film with interval=900 → 5 breaks at 5/20/35/50/65 min. A 120-min film with the same config → 6 breaks (capped). Static-offset mode is still available for fixed-position breaks regardless of content length.

Audio & the unmute button

Linear ads start muted by default (web). The SDK draws an unmute button in-player; sound switches on only after the viewer clicks it. This satisfies two policies at once: browser autoplay (Chrome/Safari/Firefox block sound-on autoplay) and Better Ads ("auto-playing video with sound" is a flagged violation). Pass mutedOnStart: false only on surfaces where the user already opted into audio for the surrounding content (e.g. a music-streaming app).

Display banners

The script tag served by /api/tag/{key} renders the creative immediately, then arms an IntersectionObserver at threshold 0.5 plus a 1-second continuous-visibility timer. When the gate passes, the script fires a single beacon to /api/impression via navigator.sendBeacon (with a 1×1 pixel fallback for legacy browsers).

• ≥50% of the slot's pixels must be in the viewport.
• For ≥1 continuous second.
• Tab must be foregrounded (the visibilitychange event cancels the pending timer).
• Scrolling out of view before 1s elapses cancels the timer; the gate re-arms on re-entry.
• Each rendered creative fires exactly once. data-refresh rotation pulls a fresh creative + new beacon URL and re-arms the gate.

Video (VAST / VMAP)

The VAST 4.2 XML returned by /api/vast/{key} embeds a single <Impression> URL per <Ad> entry. Per the VAST spec, your player MUST trigger that URL when the ad's first frame is presented to the viewer — not on parse, not on preload. All compliant players (IMA SDK, Bitmovin, video.js, JW Player, html5-vast adapters) do this by default. PopAds doesn't count an impression for video until the player fires that beacon.

Pause ads

The pause-screen creative is fetched as a single VAST response when the viewer pauses. The SDK fires the embedded <Impression> URL the moment the pause overlay is rendered — same gating model as video.

Suspicious traffic

Beacons that fail PopAds' fraud signals (datacenter IP, headless browser, IP velocity, frequency-cap breach, etc.) are still recorded for forensics, but with payouts zeroed and an is_suspicious flag set. Advertiser dashboards and publisher revenue calcs exclude these rows automatically — you only see the IAB-viewable, paid count.

Four measurement cards

Content-type filter

Advertiser analytics ships with an All / Short / Long / Live pill alongside the 7d/30d/90d range. Lets buyers compare CPM efficiency across inventory types, decide which content classification to bid more aggressively on, and avoid blending unlike inventory in a single average.

Third-party verification (OMID)

When an advertiser attaches OMID verification scripts (Moat, IAS, DoubleVerify, etc.), they flow through transparently — no publisher action required. VAST responses include an <AdVerifications> block; display tags load the OMID Session Client and dispatch lifecycle events. The OMID layer is a no-op when no verifications are attached, so there's zero overhead for the common case.

Passing viewerWallet

Any Solana base58 string (32–44 chars). PopAds doesn't care where it came from — just that it's the logged-in user's wallet on your platform. A few common sources:

// 1. Phantom / Solflare / any wallet exposing window.solana
const viewerWallet = window.solana?.publicKey?.toBase58();

// 2. Solana Wallet Adapter (@solana/wallet-adapter-react)
const { publicKey } = useWallet();
const viewerWallet = publicKey?.toBase58();

// 3. Dynamic Labs (multichain auth UI)
const { primaryWallet } = useDynamicContext();
const viewerWallet = primaryWallet?.address; // already base58 for Solana wallets

// 4. Privy / Magic / Web3Auth / your own adapter
const viewerWallet = session.wallet?.address;

Then pass it like any other PopAds option:

PopAds.init({
  // …everything else…
  viewerWallet, // undefined for anonymous users — impression still counts, just no enrichment
})

Passing viewerExternalId

Any opaque string that uniquely and stably identifies the logged-in user on your platform. Never send raw user IDs, emails, or usernames — PopAds is a third party. Hash server-side with a salt you control:

// Server-side, where you already know the user. Returns a 64-char hex string.
import { createHash } from 'node:crypto';

const SALT = process.env.POPADS_VIEWER_SALT;   // long random string, set once, never rotate
                                               //   (rotating it makes returning users look new)
function viewerExternalId(internalUserId: string): string {
  return createHash('sha256').update(`${SALT}:${internalUserId}`).digest('hex');
}

Pass the hex digest into the SDK on the client:

PopAds.init({
  // …everything else…
  viewerExternalId, // 64-char sha256 hex from your backend
})

The salt matters because without it an adversary who knows your user ID format could rainbow-table the hash back to a known ID. With the salt, the digest is meaningless outside your platform — it's only useful as a stable opaque key for PopAds' frequency and reach maths.

What advertisers see — wallet path

• Reach summary — unique wallets, total impressions, average frequency per wallet.
• Wallet-age cohorts — fresh (<30d on-chain) / aged (30–180d) / veteran (180d+). Built from each wallet's earliest signature timestamp.
• Balance cohorts — zero / small (<1 SOL) / mid (1–10 SOL) / large (10+ SOL). USDC balance shown separately on the top-viewer table.
• Audience interest fingerprint — top SPL token mints held across the audience, weighted by impressions. Useful signal for which sub-communities your inventory reaches.
• Top viewers — top-50 wallets by impressions, with Solana Explorer links so the advertiser can verify on-chain.

Each wallet is enriched on first sight via Solana RPC (balance, signature count, holdings, first-tx date) and cached for 24 hours. First dashboard load on a new campaign takes ~5 seconds while wallets enrich; subsequent loads hit the cache and are sub-second.

How to verify it's landing

After deploying, hit a placement as a logged-in user and check the most recent impression row:

SELECT viewer_wallet, viewer_external_id, fingerprint_hash, served_at
FROM ad_impressions
WHERE publisher_id = '<your-publisher-uuid>'
  AND served_at > now() - interval '5 minutes'
ORDER BY served_at DESC
LIMIT 5;

Wallet path: at least one row should have viewer_wallet populated. External-ID path: viewer_external_id should be the 64-char hex. Once 20–50 authenticated impressions land per advertiser, their Audience Insights tab unlocks the enriched view.

When to fire

Once per content item, when ZiB tells you the sidecar is ready. ZiB fires a vision.complete webhook with { file_id, sidecar_file_id, ... } once the AI pass finishes. Use that as your trigger to fetch the sidecar from ZiB, trim it, and POST it to PopAds. Subsequent ad requests for the same content_id find the cache warm — no re-posting needed.

If ZiB re-processes a video (sidecar version bumps), re-posting is safe — PopAds upserts on (publisher_id, content_id) and COALESCEs the optional display fields, so you don't blank out a title by re-posting without one.

The endpoint

POST https://api.popadsnetwork.com/api/sidecar
Content-Type: application/json

{
  "placement_key":     "pop-6ea6afe9",                // your video_session placement
  "content_id":        "<your internal content UUID>",
  "title":             "Episode 42: The Investigation",
  "thumbnail_url":     "https://your-cdn.example.com/thumb.jpg",
  "duration_seconds":  1800,
  "sidecar": {
    "version":           "2.0",
    "video":             { "duration_s": 1800 },
    "content_format":    "interview",
    "keyframes": [
      { "ts": 12.5,  "setting": "studio_interior", "presenter_emotion": "calm",
        "objects": ["microphone", "desk", "laptop"], "brands_visible": [],
        "on_screen_text": [] },
      { "ts": 124.0, "setting": "studio_interior", "presenter_emotion": "engaged",
        "objects": ["microphone", "phone"], "brands_visible": ["Apple"],
        "on_screen_text": ["iPhone 17 Pro"] }
    ],
    "content_classification": {
      "iab_primary": "53",
      "iab_categories": [
        { "id": "53",   "name": "Technology & Computing", "tier": 1, "confidence": 0.92 },
        { "id": "5310", "name": "Consumer Electronics",      "tier": 2, "confidence": 0.81 }
      ]
    },
    "garm":            null,
    "detected_brands": ["Apple"],

    "ad_targeting": {                                 // v2.0 — all keys optional
      "contextual_keywords":     ["technology","interview","product launch"],
      "brand_affinity":          ["innovation-oriented","premium tech"],
      "competitor_exclusions":   ["samsung","google","huawei"],
      "ad_moment_candidates": [
        { "timestamp_s": 120, "type": "scene_break",      "score": 0.85 },
        { "timestamp_s": 480, "type": "topic_transition", "score": 0.72 }
      ],
      "cpm_floor_suggestion":    { "floor_usd": 8.50, "confidence": 0.78,
                                   "rationale": "premium production, brand-safe" },
      "suitable_for_ads":        true,
      "recommended_ad_categories": ["technology","consumer electronics","productivity"],
      "monetisation_notes":      "Strong demand expected from tech advertisers"
    },
    "intent": {
      "viewer_intent":     "entertainment",
      "content_intent":    "interview",
      "call_to_action":    "none",
      "emotional_tone":    "curious",
      "controversy_score": 0.05,
      "controversy_reason": null
    },
    "audience": {
      "description":        "Tech-curious adults interested in product launches",
      "psychographic_tags": ["innovation-oriented","early-adopter","professional"],
      "age_skew":           "25-44",
      "gender_skew":        "balanced",
      "affluence_signal":   "above-average",
      "knowledge_level":    "intermediate-to-advanced",
      "viewing_context":    "lean-back evening"
    }
  }
}

Response: 200 OK with { "ok": true }. Errors: 400 for malformed body, 404 if placement_key doesn't exist. The placement_key is your auth signal — same trust model as /api/vmap and /api/vast. HTTPS provides confidentiality in transit; no app-layer encryption needed.

Every field is optional. Older sidecars without ad_targeting / intent / audience still serve correctly — PopAds ingests defensively. Sending the new blocks unlocks scene-anchored mid-roll placement (ad_moment_candidates), competitor suppression (competitor_exclusions), publisher-suggested CPM floors (cpm_floor_suggestion), brand-safety kill switch (suitable_for_ads: false), and richer dashboard surfaces.

content_id must match your SDK init

The content_id you POST here must be byte-equal to the contentId you pass to PopAds.init({ contentId }) on the player side. PopAds uses it as the join key — when an ad request fires for content_id=X, the backend looks up the cached sidecar under the same key. Whatever stable identifier your CMS uses (your internal content UUID, not the ZiB file_id) — use the same string in both places.

Trimming — what to send, what to strip

The raw ZiB sidecar includes plenty of fields PopAds doesn't need (executive summaries, narrative arcs, target audience descriptions, monetisation notes). Strip those before sending. The fields PopAds actually uses:

The one rename to get right is keyframes[].timestamp_s → keyframes[].ts. PopAds reads ts when picking the keyframe nearest the player's current position. The same rename does not apply to ad_targeting.ad_moment_candidates[].timestamp_s — that key stays timestamp_s because it's read by the VMAP scheduler, not the keyframe picker.

// Trim the raw ZiB sidecar to the ad-relevant subset before POSTing.
function trimSidecar(raw) {
  const sc  = raw ?? {};
  const ck  = sc.scene_understanding   ?? {};
  const cls = sc.content_classification ?? {};
  return {
    version:        sc.zib_sidecar_version,
    video:          { duration_s: sc.video?.duration_s },
    content_format: ck.content_format,
    keyframes: (ck.keyframes ?? []).map(kf => ({
      ts:                kf.timestamp_s,                     // ← rename
      setting:           kf.setting,
      presenter_emotion: kf.presenter_emotion,
      objects:           kf.objects         ?? [],
      brands_visible:    kf.brands_visible  ?? [],
      on_screen_text:    kf.on_screen_text  ?? [],
    })),
    content_classification: {
      iab_primary:    cls.iab_primary,
      iab_categories: cls.iab_categories ?? [],
    },
    garm:            cls.garm,
    detected_brands: cls.detected_brands ?? [],
    ad_targeting:    sc.ad_targeting,   // pass through as-is
    intent:          sc.intent,         // pass through as-is
    audience:        sc.audience,       // pass through as-is
  };
}

Mid-roll matching — player position

For PopAds to pick the right keyframe when a mid-roll fires, the SDK passes &t_pos=NNN (current player position in seconds) on every mid-roll / post-roll VAST request. Already supported — no action needed if you're using popads-sdk.js v1.0.6+. Older versions don't pass t_pos and PopAds falls back to the first keyframe (still better than no context).

How to verify it's landing

After sending a sidecar, fire a mid-roll on that content and check the impression:

SELECT
  content_id,
  content_timestamp_seconds,
  scene_context_at_serve->'brands_visible' AS brands_seen,
  scene_context_at_serve->'objects'        AS objects_seen,
  policy_version,
  served_at
FROM ad_impressions
WHERE publisher_id = '<your-publisher-uuid>'
  AND content_id   = '<content-id-you-just-posted>'
  AND served_at    > now() - interval '5 minutes'
ORDER BY served_at DESC
LIMIT 5;

You should see scene_context_at_serve populated with the keyframe's objects / brands_visible / setting, content_timestamp_seconds matching the mid-roll position, and policy_version = 'cpm_baseline' (this changes once the learning ranker ships).

What gets stored, what gets dropped

PopAds stores the trimmed JSON verbatim in content_sidecars.sidecar_json, plus the optional display fields (title, thumbnail_url, duration_seconds) on flat columns for fast aggregation. Nothing you send leaves PopAds — sidecar data is read by the contextual matcher (server-side) and aggregated into the advertiser-facing Inventory tab; it is never echoed to client code or third parties.

Where to pass them

Either through the SDK config (preferred for video):

PopAds.init({ /* … */, contentId, creatorId, creatorWallet })

Or directly on the tag URL (for display banners or server-rendered VMAP):

https://app.popadsnetwork.com/api/vmap/pop-XXXX
  ?content_id=video-123
  &creator_id=creator-42
  &creator_wallet=GPxRxtGb...BCtR

Issue a key from the dashboard

1. Sign in to app.popadsnetwork.com and open the publisher dashboard.
2. Go to API Access.
3. Set your daily and hourly USDC caps. These are circuit breakers in case the key leaks — pick numbers a few times higher than your typical throughput.
4. Click Generate API key and approve the signature in your wallet.
5. Copy the key from the modal — it's only shown once. Store it in your secrets manager (e.g. as POPADS_API_KEY).

Authenticate requests

curl -H "Authorization: Bearer $POPADS_API_KEY" \
  https://app.popadsnetwork.com/api/publisher/v1/stats

Rotate or revoke

Re-running Generate API key (now labelled Rotate key) replaces the existing key — the old one stops working immediately. Use this if a key has leaked or you need to change limits.

@popads/publisher (Node SDK)

A typed Node wrapper around all four endpoints. Recommended over raw fetch.

npm install @popads/publisher

import { PopAdsPublisher } from '@popads/publisher'
const popads = new PopAdsPublisher({ apiKey: process.env.POPADS_API_KEY })

const stats = await popads.getStats()
console.log(`${stats.balance.pendingUsdc} USDC available, ${stats.impressions.lifetime} lifetime impressions`)

GET /v1/stats

Account state — pending balance, lifetime + 30-day rollups, current cap usage.

{
  "publisher": {
    "id": "7f4f9f8d-…",
    "platformName": "rite3",
    "revenueSharePct": 70,
    "payoutsFrozen": false
  },
  "balance": {
    "pendingUsdc": 142.371500,
    "paidUsdc": 50.000000,
    "lifetimeRevenueUsdc": 192.371500
  },
  "impressions": { "lifetime": 18234, "last30d": 4521 },
  "revenue": { "last30dUsdc": 38.940000 },
  "payoutLimits": {
    "dailyUsdc": 5000, "hourlyUsdc": 1000,
    "dailyUsedUsdc": 124.0, "hourlyUsedUsdc": 12.0
  },
  "asOf": "2026-04-26T15:55:23.812Z"
}

GET /v1/creators

All creators ranked by lifetime revenue.

{
  "creators": [
    {
      "creatorId": "creator_42",
      "creatorWallet": "GPxRxtGb…BCtR",
      "impressions": 1248,
      "revenueUsdc": 12.480000,
      "lastSeenAt": "2026-04-26T15:42:11.000Z"
    }
  ],
  "count": 87
}

GET /v1/creators/{creatorId}

Per-creator detail with claimable balance — lifetime revenue minus what's already been dispatched to that creator's wallet.

{
  "creatorId": "creator_42",
  "creatorWallet": "GPxRxtGb…BCtR",
  "impressions": { "lifetime": 1248, "last30d": 320 },
  "revenue":     { "lifetimeUsdc": 12.480, "last30dUsdc": 3.200 },
  "payouts":     { "paidUsdc": 5.000, "claimableUsdc": 7.480 }
}

GET /v1/impressions

Paginated impression log. Pass nextCursor as ?before= for the next page.

GET /v1/impressions?limit=100&creator_id=creator_42

GET /v1/content

Per-content value estimates for every piece of content you've registered with PopAds via POST /api/sidecar. Each row carries the ZiB-suggested CPM, an estimated monthly publisher-side revenue forecast, and the classification signals advertisers see (IAB, detected brands, audience psychographics). Use this to render a "what's this video worth on PopAds" view on your creator dashboard.

curl -H "Authorization: Bearer $POPADS_API_KEY" \
  "https://app.popadsnetwork.com/api/publisher/v1/content?sort=cpm_desc&limit=50"

Response:

{
  "content": [
    {
      "content_id": "e21e5c38-7d04-42fd-9786-326a8f08d52f",
      "title": "Crypto Trader Daily — Episode 47",
      "thumbnail_url": "https://cdn.zibnetwork.com/objects/...",
      "duration_seconds": 1320,
      "indexed_at": "2026-05-26T00:18:19Z",
      "sidecar_version": "2.0",

      "estimated_cpm_usd":      12.50,
      "cpm_confidence":         0.78,
      "cpm_rationale":          "premium production, brand-safe audience",
      "suitable_for_ads":       true,

      "impressions_30d":        47000,
      "ad_breaks_count":        4,

      "estimated_monthly_publisher_revenue_usd": 411.25,
      "publisher_revenue_share_pct":             70,

      "iab_primary": "596",
      "iab_categories": [
        { "id": "596", "name": "Cryptocurrency",     "tier": 3, "confidence": 0.92 },
        { "id": "53",  "name": "Business & Finance", "tier": 1, "confidence": 0.85 }
      ],
      "top_detected_brands": ["Ledger", "Phantom", "Trezor"],
      "psychographic_tags":  ["crypto-native", "early-adopter", "investor"],
      "viewer_intent":       "education",
      "content_format":      "interview"
    }
  ],
  "total":  142,
  "limit":  50,
  "offset": 0,
  "sort":   "cpm_desc"
}

Field notes:

• estimated_cpm_usd is ZiB Vision AI's suggested CPM floor for the content. Combines audience inference, brand-safety, production quality. Forward-looking estimate, not a guaranteed clearing price.
• estimated_monthly_publisher_revenue_usd = cpm × (impressions_30d / 1000) × (publisher_revenue_share_pct / 100). This is publisher-side revenue, before any creator share you apply on your end. Returns null when either input is missing.
• impressions_30d is the actual billable impression count over the trailing 30 days. Excludes pre-dispatched + suspicious rows.
• suitable_for_ads: false means PopAds is suppressing ads on this content entirely (brand-safety kill switch from the sidecar). Revenue estimate will still be present but won't realise.

GET /v1/content/{content_id}

Same shape as a single entry from the list endpoint above, scoped to one content. Useful when your dashboard navigates to a specific creator video page and wants the live value estimate.

curl -H "Authorization: Bearer $POPADS_API_KEY" \
  "https://app.popadsnetwork.com/api/publisher/v1/content/e21e5c38-7d04-42fd-9786-326a8f08d52f"

Returns 404 when the content_id has no sidecar registered yet (you haven't POSTed it via /api/sidecar) or belongs to another publisher. Returns the same JSON object shape as a single entry in the list endpoint's content[] array — no envelope wrapping.

POST /v1/payout

import { PopAdsPublisher, PopAdsInsufficientBalance, PopAdsRateLimited } from '@popads/publisher'

try {
  const result = await popads.payout({
    recipient:      creator.solanaWallet,
    amountUsdc:     1.50,
    idempotencyKey: PopAdsPublisher.idempotencyKey({ claimId }),
  })
  // result.txSignature is the on-chain signature you can link on Solscan
} catch (err) {
  if (err instanceof PopAdsInsufficientBalance) { /* not enough accrued revenue */ }
  else if (err instanceof PopAdsRateLimited)    { /* hit your hourly/daily cap */ }
  else throw err
}

Idempotency

The idempotencyKey is unique per publisher. Replays of the same key never double-pay:

Use a deterministic key per claim attempt (e.g. ${claimId}-${attempt}). Safe to retry on transient errors with the same key.

Error codes

Setup

Dashboard → API Access → Webhooks → enter your https:// endpoint → Save. We return a signing secret once; copy it into your env (e.g. POPADS_WEBHOOK_SECRET).

Events

Verifying signatures

Always verify against the raw request body — re-stringifying JSON breaks the HMAC.

import express from 'express'
import { verifyWebhookSignature } from '@popads/publisher'

app.post('/popads-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  const ok = verifyWebhookSignature(
    rawBody,
    req.header('x-popads-signature'),
    process.env.POPADS_WEBHOOK_SECRET,
  )
  if (!ok) return res.status(401).end()

  const event = JSON.parse(rawBody)
  switch (event.event) {
    case 'payout.dispatched': /* mark claim paid */ break
    case 'payout.failed':     /* show retry option */ break
  }
  res.status(200).end()
})

Headers

USDC mints

Test funds (devnet)

• • Devnet SOL — faucet.solana.com
• • Devnet USDC — faucet.circle.com (select Solana Devnet)

All payouts

Dispatched as standard SPL transferChecked instructions. PopAds creates the recipient's USDC associated token account idempotently and pays the rent — creators never need SOL to receive funds.

Stuck on integration? Reach out via any of the channels below — include your publisher ID and any failing idempotencyKey if applicable.

Full API reference

The version-controlled API reference lives at the dashboard host and is always in sync with what's live: