Pixora Ads SDK and API for developers

Select formats when registering your property for moderation. Images and video are creative types; native, interstitial and rewarded are delivery scenarios. There is no separate showVideo() method: the server selects a matching creative.

Mini App advertising stays inside the partner interface. Advertiser navigation is optional; dismissing the ad returns to your screen. Bots use conversation ads paid per click; channels use posts with CPM or CPC. The CTA leads to the advertiser. This JavaScript SDK is for Mini Apps, not messages.

Publisher income and viewer bonuses are separate. Use native or interstitial to monetize without rewards. Ordinary impressions require at least 50% creative visibility for one continuous second in an active window, and actual playback for video. The server checks eligibility, limits and budget before confirming delivery.

For new integrations use SDK 1.8.1: init() and an explicit show method. Legacy create()/mount() remain compatible.

1. Open Monetization → Ad network and choose Mini App, bot or public channel.
2. Provide a name, Telegram URL and a description of the topic and audience. For Mini Apps use the bot link or a t.me/bot/appname direct link. Select native, interstitial and/or rewarded before moderation. Describe the ad placement in the description; there is no separate field.
3. Verify control: bot token for bots/Mini Apps; administrator permissions for channels. The token verifies control of the bot; a moderator reviews the placement.
4. For Mini Apps and bots, create an API key after approval and keep it server-side. Automatic channel posting needs no separate server or API key: save the posting settings and verify bot permissions.
5. Run the test below, connect your backend and SDK or prepare an ad in the dashboard. Live ads require an active property and matching demand; connecting does not guarantee ad fill or income.

The @pixorAds_networkbot demo shows the complete user journey: opening a Mini App, requesting an ad through a server and showing the chosen format inside the Mini App. You can try it before connecting your own property.

1. Open the bot and launch its Mini App. The demo backend verifies the Telegram session through /api/v1/ad-network/demo/session.
2. The SDK calls /api/v1/ad-network/demo/offer on the same origin. The secret publisher key stays on the server.
3. If there is no matching paid offer, the demo app shows an introductory video. This is the publisher's own empty state, not an ad view: it creates no charge, reward or publisher income.

1// Demo only: run after loading pixorads-publisher.js inside Telegram.2const session = await fetch("/api/v1/ad-network/demo/session", {3  method: "POST",4  credentials: "same-origin",5  headers: { "Content-Type": "application/json" },6  body: JSON.stringify({ init_data: window.Telegram.WebApp.initData })7});8if (!session.ok) throw new Error("Telegram session could not be verified");9const { csrf_token, publisher_id } = await session.json();10const placement = window.PixorAdsPublisher.init({11  element: document.getElementById("pixorads"),12  endpoint: "/api/v1/ad-network/demo/offer",13  csrfToken: csrf_token,14  publisherId: publisher_id,15  language: "en"16});17await placement.showNative();

Load the script once in HTML. Set endpoint to your own backend on the same origin. Never expose the API key to the browser. Before init(), send Telegram.WebApp.initData to your backend: verify its signature and age, create a session, and for cookie authentication return a CSRF token for the csrfToken option. Copy the public publisherId from the property card. Examples below are native ads without rewards; see Show methods for other scenarios. Pass the session CSRF token as a React prop and destroy() on unmount.

1<!-- Render this page AFTER your backend verifies the Telegram session. -->2<!-- Your backend inserts its session CSRF token into this meta tag. -->3<meta name="csrf-token" content="YOUR_SESSION_CSRF_TOKEN">4<script src="https://pixora-ads.com/sdk/pixorads-publisher.js"></script>5<div id="pixorads"></div>6<script type="module">7  const placement = window.PixorAdsPublisher.init({8    element: document.getElementById("pixorads"),9    endpoint: "/api/pixorads/offer",10    csrfToken: document.querySelector('meta[name="csrf-token"]').content,11    publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",12    trackAudience: false,13    personalized: false,14    language: "en"15  });16  const state = await placement.showNative();17  if (state.status === "error") console.warn(state.code);18  // empty: no ad available. Continue the app; do not retry in a loop.19  // On screen removal: placement.destroy();20</script>

Choose one example below. Load the SDK and have your backend verify the Telegram session first. Replace publisherId with your public property ID. csrfTokenFromYourSession is your session CSRF token, not an API key. /api/pixorads/offer is a route you implement on your backend.

1// Prerequisites: SDK loaded, your session verified, <div id="ad-slot"></div>.2const ads = window.PixorAdsPublisher.init({3  publisherId: "YOUR_PUBLIC_MINIAPP_PUBLISHER_ID",4  endpoint: "/api/pixorads/offer",5  csrfToken: csrfTokenFromYourSession,6  element: document.getElementById("ad-slot"),7  language: "en",8  trackAudience: false, // Enable explicitly if you measure app activity.9  personalized: false10});1112const state = await ads.showNative();13if (state.status === "empty") {14  // No matching ad. Continue your app normally; try later.15} else if (state.status === "error") {16  console.warn("Ad unavailable:", state.code);17}18// ready means rendered, NOT a paid impression.19// Keep ads alive while the card is visible.20// When removing this screen: ads.destroy();

Method results

1{2  shown: true,              // Viewer handshake completed; NOT proof of payment3  completed: false,         // true only for completed rewarded viewing4  impression_confirmed: true // Ordinary viewer confirmation, when available5  // receipt, session_id: present when supplied by the viewer6  // test:true => {shown:false, completed:false, test:true}; no overlay or payout7}

Only one ad viewer can be open at a time. Do not run showNative() and a full-screen method concurrently on one controller. Continue your app on no_fill; never replace a promised reward with an ordinary ad. Destroy the controller when its screen is removed, not immediately after rendering a card.

Native and interstitial need no reward integration. In rewarded mode PixorAds verifies the view; your backend grants any additional coins, lives or other bonus inside your app.

1. Read the opaque receipt from showRewarded() after dismissal. It is proof to verify, not a reward amount.
2. Send it to your authenticated backend. Verify it using this property's key and match telegram_id against your own session user.
3. In one transaction save the unique receipt_id and grant the server-configured bonus. Repeated requests must return the existing outcome without granting twice.

1// Inside YOUR authenticated, CSRF-protected reward route.2// req.user.telegramId must come from a verified session, never the request body.3const response = await fetch("https://pixora-ads.com/api/v1/ad-network/publisher-api/reward/verify", {4  method: "POST",5  headers: {"Content-Type": "application/json", "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY},6  body: JSON.stringify({receipt: req.body.receipt}),7  signal: AbortSignal.timeout(8000)8});9if (!response.ok) throw new Error("Reward not verified");10const proof = await response.json();11if (!proof.rewarded || String(proof.telegram_id) !== String(req.user.telegramId)) {12  throw new Error("Wrong viewer");13}14// YOUR database transaction (required; not implemented by this snippet):15// 1. Insert (receipt_id, your_user_id) into a ledger with UNIQUE(receipt_id).16// 2. On a new row, grant YOUR server-configured internal bonus.17// 3. On duplicate, return the existing result for the same user.18// Commit both operations together, then return 2xx to the browser.19// Never take a reward amount from req.body or credit proof.reward as app coins.

Response: rewarded, receipt_id, session_id, publisher_id, telegram_id, operation_id, reward, currency, completed_at. Receipts last seven days and are property-bound. Verification transfers no money. If your backend is unavailable, retry the same receipt instead of requiring another ad view.

When to use onReward

onReward({receipt, session_id}) fires on completion while the viewer can remain open. It is an alternative to processing the receipt after dismissal. The SDK neither awaits nor retries your async callback: implement errors and retries yourself. If you use both paths, server deduplication by receipt_id is essential. onEvent notifications and CTA clicks never authorize a bonus.

API amounts are integer minor units: XTR / 1000 = Stars; RUB / 1000 = rubles; USD / 1,000,000 = dollars. reward:70 with currency:XTR means 0.07 Stars. In an offer, viewer_reward/viewer_currency describe the viewer reward; reward and publisher_amount use the campaign currency. publisher_income estimates USD earnings, fixed on confirmation. Neither defines the number of coins in your app.

Your backend authenticates the user, rate-limits requests and requests an ad from PixorAds. Forward the JSON response to the widget. Reuse one Idempotency-Key for retries of the same logical request; use a new key for a new offer.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"en","format":"native"}'

1// Node.js 22+ / Express. Keep this code on YOUR SERVER.2// app, requireYourSession, verifyYourCsrf and yourRateLimit3// belong to your app. Implement them before exposing the route.4import { randomUUID } from "node:crypto";56app.post("/api/pixorads/offer", requireYourSession,7  verifyYourCsrf, yourRateLimit, async (req, res) => {8    res.set("Cache-Control", "no-store");9    const language = req.body?.language ?? "en";10    const context_token = req.body?.context_token ?? "";11    // Legacy create().mount() omits format; preserve the API's auto default.12    const format = req.body?.format ?? "auto";13    if (!["ru", "en"].includes(language)) return res.status(400).json({error:{code:"invalid_language"}});14    if (typeof context_token !== "string" || context_token.length > 2048) return res.status(400).json({error:{code:"invalid_viewer_context"}});15    if (!["auto", "native", "interstitial", "rewarded"].includes(format)) return res.status(400).json({error:{code:"invalid_format"}});16    // Reuse this ID if you retry this upstream request.17    const requestId = randomUUID();18    try {19      const response = await fetch(20        "https://pixora-ads.com/api/v1/ad-network/publisher-api/offer",21        {22          method: "POST",23          headers: {24            "Content-Type": "application/json",25            "X-PixorAds-Key": process.env.PIXORADS_PUBLISHER_KEY,26            "Idempotency-Key": requestId27          },28          body: JSON.stringify({ language, context_token, format }),29          signal: AbortSignal.timeout(8000)30        }31      );32      const retryAfter = response.headers.get("Retry-After");33      if (retryAfter) res.set("Retry-After", retryAfter);34      const payload = await response.json();35      // Preserve structured error.code so the SDK can show useful diagnostics.36      res.status(response.status).json(payload);37    } catch {38      res.status(503).json({ error: { code: "upstream_unavailable" } });39    }40  });

Rotating or revoking a key disables it and its placement links. Update your environment variable and create new placements. Started sessions retain their terms, but new viewer actions check current status and key version.

The main bot format is an ad after a useful reply, paid per confirmed visit. BotFather tokens stay on the owner server; viewers need no separate registration.

Configure delivery, approve creatives and view rates and earnings in the bot property card under Conversation ads. Rewarded viewing remains an optional format with its own integration.

Add a public channel with your account and the PixorAds bot as administrators. After moderation, check posting and deletion permissions. Choose views (CPM, default) or confirmed clicks (CPC) in channel settings. Set minimum earnings and the result cap per post. Automatic posting and approval are available for both.

CPM pays Telegram counter views in the first 24 hours, including forwards; this is not unique reach or completion. CPC pays navigation confirmed on a short page without registration. Views, previews and repeats to the same advertiser in channels within 24 hours are free. An IP and User-Agent fingerprint is not proof of a unique person. Readers receive no reward.

Settlement follows the 24-hour placement, then the campaign hold. Post history shows earnings, paid views or clicks and release dates. Channel prices and shares are independent of Mini Apps; current rates appear in property earnings.

1// Load /sdk/pixorads-offerwall.js first.2const demo = new PixorAdsOfferwall.DemoClient();3const { items } = await demo.catalog();4const attempt = await demo.start(items[0].id, "demo-1");5await demo.check(attempt.id); // demo_completed; paid=false; no receipt6demo.reset();

Offerwall 1.3 · Connection, a nonfinancial sandbox, bonuses and diagnostics in one dashboard.

One task catalog: a hosted screen, Mini App component and API for your own interface or Telegram bot. Public channel subscriptions and group joins are supported. PixorAds must be an administrator of the target chat. First bot launches and advertiser-confirmed Mini App actions are also supported after an integration test. Public-group reactions, non-anonymous PixorAds polls, new Premium boosts, website visits, surfing and report tasks including product research are supported. Website availability depends on service settings. Dedicated purchase formats and multi-step tasks are not supported.

1. Prepare your property

Add and verify a property under My properties and complete moderation. In Tasks & rewards choose the reward mode, configure callbacks and enable tasks. Only campaigns whose advertisers explicitly enabled partner distribution are eligible.

• PixorAds reward: a registered user earns cash; the property earns a share of the platform fee. Initial share: 50% of the fee.
• Property reward: you grant coins or access; your property earns a share of the result price. Initial share: 80%. Your server delivers internal rewards.

Shares are configurable and frozen when a task starts. Property income is recorded in USD at a frozen exchange rate and held after final verification (24 hours by default). Membership retention is shown separately. A confirmed action does not mean income is immediately withdrawable.

Task referral rewards are funded from the platform share remaining after the publisher split. They do not reduce the agreed user reward or property income.

2. Choose an integration

Before enabling tasks, open Monetization → Offerwall → Connection. Save settings, create a sample task and complete it. Its event has test=true, user_id=null and zero monetary income. Never credit a real user for it. Repeat the test after changing settings.

With webhooks, the test is sent to the saved URL with the usual HMAC signature. Otherwise fetch GET /publisher-api/tests. Your server acknowledges it through POST /publisher-api/tests/{conversion_id}/ack with X-PixorAds-Key. HTTP 2xx alone does not confirm a reward. Test events remain available for 24 hours.

Hosted screen: copy the Telegram link from offerwall settings. It works in Mini Apps, bots and channel posts. Source attribution is preserved and does not create a referral relationship.

1<script src="https://pixora-ads.com/sdk/pixorads-offerwall.js"></script>2<pixorads-task publisher-id="YOUR_PUBLISHER_UUID" theme="light">3</pixorads-task>

The component runs inside a Telegram Mini App using signed initData for the bot verified on the property. Never expose an API key in the browser. Theme: light/dark; height: CSS variable --pixorads-offerwall-height.

1const client = new PixorAdsOfferwall.Client({ publisherId: "YOUR_PUBLISHER_UUID", telegramInitData: Telegram.WebApp.initData });2// Show terms and obtain consent before connect().3const { items, history, options } = await client.connect({ accepted: true });4// items already honor the publisher's task_types on the server.5// Show an empty state when items is empty; always render history separately.6// Call only when the user chooses a task from items.7async function startSelectedTask(campaignId, retryKey) {8  const task = await client.start(campaignId, retryKey);9  const destination = await client.open(task.id);10  return { task, url: destination.url };11}12// Open the returned protected URL; offer a separate Check button.13async function checkTask(attemptId) {14  return client.check(attemptId);15}16// Do not grant a reward based on a JavaScript event.

API base: https://pixora-ads.com/api/v1/offerwall. Append the /viewer/... and /publisher-api/... paths shown here. Client({baseUrl}) accepts only an HTTPS origin, such as https://pixora-ads.com, without a path, query or hash.

On screen removal call client.disconnect(): pending requests fail with disconnected and the viewer token is cleared. Obtain consent and reconnect before further use. After a lost response, reload history; retry start or report submission with the original key because the server may have saved the request. The SDK does not retry automatically.

3. Bot API

Ready examples include /bonus and /bonusbalance, start/check buttons, reconciliation after restart, setup tests and reward deduplication. They poll the API and do not need a public webhook.

• Python 3.11+ · aiogram 3 · httpx
• Node.js 24+ · Telegraf 4

Each file starts with setup commands and environment variables. Examples credit a standalone SQLite balance. For your game currency, put the credit and UNIQUE(conversion_id) in one transaction in your own database; acknowledge only after commit. Do not start a second polling process for an existing bot: integrate the handlers into its app.

Your bot server uses the property API key in X-PixorAds-Key. Request a session for a Telegram ID. If verified=false, show verification_url so the user can verify their Telegram account and accept terms. An arbitrary ID cannot earn rewards. Identity proof lasts one day; server requests do not extend it.

1import os, httpx2BASE = "https://pixora-ads.com/api/v1/offerwall"3KEY = os.environ["PIXORADS_KEY"]45async def get_tasks(telegram_user_id):6    async with httpx.AsyncClient(timeout=20) as api:7        r = await api.post(BASE + "/publisher-api/session",8            headers={"X-PixorAds-Key": KEY},9            json={"telegram_id": telegram_user_id})10        r.raise_for_status()11        session = r.json()12        if not session["verified"]:13            return session  # Show verification_url as a button.14        token = session["viewer_token"]15        r = await api.get(BASE + "/viewer/catalog",16            headers={"Authorization": "Bearer " + token})17        r.raise_for_status()18        return {"verified": True, "token": token, **r.json()}1920# Call only after the user selects a task.21async def start_task(token, campaign_id, retry_key):22    async with httpx.AsyncClient(timeout=20) as api:23        r = await api.post(BASE + "/viewer/start",24            headers={"Authorization": "Bearer " + token,25                     "Idempotency-Key": retry_key},26            json={"campaign_id": campaign_id})27        r.raise_for_status()28        return r.json()2930# Send title, reward and conditions. POST /viewer/attempts/{id}/open31# with the viewer token and use its url; for reports use hosted_url.32# A separate Check callback POSTs /viewer/attempts/{task_id}/check.33# Keep tokens on your server and bind callbacks to the same user.34# Store retry_key before the request and reuse it on retries.35# If items is empty, continue the ordinary bot flow.

A user has one separate quick-task slot and can take up to five report tasks across maps, marketplaces and extended tasks. Review and waiting for delivery do not count towards this limit. Existing tasks returning for revision or from delivery remain available. New assignments are unavailable while the limit is reached. Browsing does not reserve budget, and restarting the same campaign through another property does not create a second reward.

Handle HTTP 409 task_assignment_limit when starting a task: the report-task limit is reached. task_quick_assignment_limit means the quick-task slot is occupied. Show a clear message and keep the selected card; do not switch to a different execution automatically. These errors create no new assignment or reserve. Once capacity is available, retry. After a network error, reuse the same command key.

4. Deliver rewards on the server

Configure a public HTTPS webhook. The signing secret is in offerwall settings. X-PixorAds-Signature = HMAC-SHA256(secret, timestamp + '.' + raw body bytes); timestamp is X-PixorAds-Timestamp. Use constant-time verification and a bounded clock skew (for example 5 minutes). Do not reserialize JSON before verification.

• completed — action observed, membership retention pending. An early bonus is allowed only for the explicitly enabled advance mode;
• qualified — final verification passed: grant the internal reward once;
• revoked — retention verification failed; no payout;
• paid — property income released from hold.

Before crediting, request GET /publisher-api/rewards/{conversion_id}. Check telegram_id, reward_mode=partner, test=false and reward_eligible=true. Credit reward_units from that response exactly once. After your transaction commits, POST /publisher-api/rewards/{conversion_id}/ack with {reference: 'your credit identifier'}. Retry with the same reference after network errors. This acknowledgement appears to the user and in analytics; it does not trigger PixorAds money transfers.

5. Flexible bonuses

Choose fixed units or units per $1 of property income. Units are rounded down and bounded by your minimum and maximum. Promotion multipliers have an end date. Terms freeze at task start; advertiser prices and the monetary split stay unchanged. Catalog estimates can change before start if settings or exchange rates change.

By default, grant after final verification. In advance mode, the property grants its own bonus after the initial check at its own risk: failure to retain membership cancels the property income. PixorAds does not claw back spent internal bonuses. Cash rewards and income release are not accelerated.

Use conversion_id as the reward key and save it atomically with the reward under a UNIQUE constraint. Deduplicate event_id. Events can be repeated or arrive out of order. Return 2xx only after durable storage. Up to 12 delivery attempts; errors and manual retries are available in the property dashboard.

If using the receipt from a final result, send it to your server: POST /publisher-api/reward/verify with the property key. Match telegram_id and conversion_id to your user. A receipt does not replace payout deduplication. Without webhooks, poll history and final results.

1{2  "campaign_id": "CAMPAIGN_UUID",3  "attempt_token": "px_ATTEMPT_TOKEN",4  "event_id": "your-stable-event-id",5  "telegram_id": 123456789,6  "event_name": "tutorial_complete",7  "occurred_at": "2026-10-06T10:05:00Z",8  "first_seen_at": "2026-10-06T10:01:00Z",9  "status": "completed",10  "reason": null11}

Reporting and limits

Pass placement to Client, as a component attribute, or in an API session request. Use 1–40 ASCII letters, digits, _ or -. The widget reports a card when at least 50% is visible. In a custom UI call client.visible([campaignId]) after actual display, not catalog loading. Bot message visibility is unknown, so do not report card visibility there.

Support is tied to an execution: POST /viewer/attempts/{id}/ticket with {message: 'description'}, or client.support(id, message). The response appears in history[].ticket. Publishers see their own requests; operators respond under Ad network → Offerwall support.

The dashboard reports starts, retention checks, confirmed results, cancellations, advertiser spend and property income. Periods refer to task start date. A catalog request is not an ad impression, unique reach or billable action. Billing includes only final verified results.

Use init({publisherId, trackAudience:true}); this is init()'s default. Set false to opt out. trackVisit() uses signed Telegram initData at most one hour old. Installation only in an ad slot measures its visitors, not your entire app audience.

Call trackVisit() on meaningful returns without polling. The server deduplicates people. recorded:false means no observation was saved, not an ad failure. trackAudience:false disables automatic submission but does not block an explicit trackVisit() call.

Bots report genuine activity via POST /api/v1/ad-network/publisher-api/activity with {telegram_id} and a server-only X-PixorAds-Key. These are partner-reported observations, not paid-view evidence. Channels refresh subscriber counts after admin verification; subscribers are not advertising reach.

Activity over 24 hours / 7 / 30 days, unique ad viewers, visible impressions and completed views are separate. Forecasts need seven full UTC days for every selected property; unsupported targeting history produces no estimate. Measured audiences are deduplicated; channel subscribers are not summed. Groups below 20 are hidden from advertisers.

Disclose measurement to users. Enable personalized:true only with permission to use an existing PixorAds profile. Never substitute initDataUnsafe for signed initData. Activity observations use HMAC identifiers retained for up to 90 days.

The real SDK below runs with test: true. No ads are requested and no money or statistics change. Click the card button. Use the same mode on your page; it requires no endpoint.

1window.PixorAdsPublisher.mount({2  element: document.getElementById("pixorads"),3  language: "en",4  test: true5});

New integrations: init() → chosen method → destroy() when removing the screen. Legacy create() requires element; mount() uses auto selection and returns a state promise. PixorAdsPublisher.mount(options) exposes no controller; use init() or create() for lifecycle management.

Runtime and CSP

Live embedded viewing requires HTTPS and a Telegram launch with signed initData at most one hour old. Use test:true in an ordinary browser; initDataUnsafe is not identity proof. Refresh expired launch data by reopening the Mini App, not by changing auth_date.

Allow https://pixora-ads.com in script-src, frame-src and connect-src; allow card assets in img-src and media-src. Retain your app’s existing permissions. If CSP restricts styles, check compatibility: the SDK applies inline styles to its card and overlay. Never send the API key to the browser.

TypeScript: save the .d.ts in a folder included by tsconfig and use window.PixorAdsPublisher. These declarations describe a global script, not an npm module. There is no official npm package.

1curl https://pixora-ads.com/api/v1/ad-network/publisher-api/offer \2  -H "X-PixorAds-Key: $PIXORADS_PUBLISHER_KEY" \3  -H "Idempotency-Key: unique-logical-request-id" \4  -H "Content-Type: application/json" \5  -d '{"language":"en","format":"native"}'

Response example

Below is an abbreviated rewarded example. Return the full upstream JSON unchanged, including URLs, format and accounting fields. Native/interstitial use billing = confirmed_impression and include impression_url. reward and publisher_amount are integer minor units: divide XTR and RUB by 1000, USD by 1,000,000. Viewer reward: viewer_reward/viewer_currency. Estimated USD publisher earnings: publisher_income.

1{2  "source": "pixorads",3  "placement_id": "<placement UUID>",4  "title": "<advertisement title>",5  "text": "<plain text>",6  "disclosure": "Реклама · Ad · PixorAds",7  "url": "https://t.me/pixoradsbot?startapp=net_<32 hex characters>",8  "expires_at": "<ISO 8601 timestamp>",9  "format": "rewarded",10  "billing": "completed_rewarded_session",11  "currency": "XTR",12  "reward": 70,13  "publisher_amount": 114}15// No suitable demand: { "source": "none", "monetag_enabled": false }16// Rewarded response excerpt, not a complete offer to return from your backend.17// Example: 70 XTR minor units = 0.07 Stars; 1 = 0.001 Stars.18// Ordinary: billing:"confirmed_impression", reward:0, impression_url present.19// Forward the FULL upstream JSON unchanged; never build it from this excerpt.

Ordinary placements last five minutes; rewarded placements last 24 hours. Follow expires_at. Idempotency-Key: up to 80 characters, one per logical request. Rewarded retries replay the response. Repeating an issued ordinary offer returns placement_already_issued: request a fresh placement with a new key. Avoid retry loops.

Property statistics show issued sessions, verified completions, held income and released income. Confirmed ordinary impressions are separate from rewarded completions; an offer request, card render or click alone does not prove earnings. Earnings accrue in USD. Mini Apps: 80% during the current promotion, then 70%; new channel campaigns: 90%, then 88%; bot CPC has an independent rate. Current rates appear in property earnings. Ordinary ads use paid impression revenue; Rewarded uses revenue after the viewer reward. Channel prices and shares are fixed at campaign creation and FX at post reservation. Mini App terms are fixed at issuance and USD at confirmation. Historical RUB and Stars remain separate. USD withdrawals use crypto only. Rates depend on auction bids and available demand. Restrictions can keep income under review.

Contact support with the property ID, error time, HTTP status and code. Do not send your API key or bot token.

Select formats when registering your property for moderation. Images and video are creative types; native, interstitial and rewarded are delivery scenarios. There is no separate showVideo() method: the server selects a matching creative.

Mini App advertising stays inside the partner interface. Advertiser navigation is optional; dismissing the ad returns to your screen. Bots use conversation ads paid per click; channels use posts with CPM or CPC. The CTA leads to the advertiser. This JavaScript SDK is for Mini Apps, not messages.

Publisher income and viewer bonuses are separate. Use native or interstitial to monetize without rewards. Ordinary impressions require at least 50% creative visibility for one continuous second in an active window, and actual playback for video. The server checks eligibility, limits and budget before confirming delivery.

For new integrations use SDK 1.8.1: init() and an explicit show method. Legacy create()/mount() remain compatible.

Send referral milestones to Keitaro, Binom v2 or your server. This is outgoing analytics: it does not change payouts or replace Offerwall reward webhooks or Pixel server confirmation.

1. Connect your tracker

Partners → Links → Postbacks: choose a tracker, enter its public HTTPS endpoint, add goals and saved links. Preview the generated request, test delivery and enable the integration. One integration can serve several links; each link has one integration.

2. Preserve your tracker's click ID

1# Keitaro2https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={subid}34# Binom5https://pixora-ads.com/api/v1/referrals/track/YOUR_LINK_CODE?tracker_click_id={clickid}

Use the code from your saved link; your tracker substitutes its click macro. tracker_click_id is the external identifier (up to 128 characters); click_id is Pixora's separate internal ID. The bridge saves the external ID and opens the selected website, bot or Mini App. A direct Telegram link with fixed sub_id values does not capture the tracker's dynamic click ID.

3. Choose goals and amounts

Up to 24 goals per integration. amount is the event amount; payout is partner income: a referral's 1,000 RUB deposit is not 1,000 RUB of partner revenue. Only commission generates monetary payout by default. Currencies remain separate; Stars are not converted to rubles or dollars. In the settings API, amount_minor is an integer string: RUB and XTR use 1,000 units, USD 1,000,000. Outgoing amount and payout are decimal strings in their currencies.

Keitaro receives a stable tid per goal and event so retries do not add another conversion. In Binom, reserve event1…event24 and one payout currency, RUB or USD. The adapter sends absolute event values and cumulative revenue with disable_upsell=1 and disable_postback=1. Do not add them again in your tracker rules.

Custom endpoint: GET or POST

1https://tracker.example/pixora?click={tracker_click_id}&goal={goal_id}&event={event}&amount={amount}&currency={currency}&payout={payout}&payout_currency={payout_currency}

Macros are allowed only in query values: tracker_click_id, click_id, event_id, goal_id, event, link_id, sub_id_1…sub_id_5, amount, currency, payout, payout_currency and occurred_at. Wrap macro names in braces. status, goal and amount_minor are not macros. event_id and tracker_click_id are added to custom GET requests even when omitted from your template.

POST sends fixed JSON with those fields plus schema_version=1, test_mode, event_type and corrects_event_id; it is not a custom body template. Store event_id with a UNIQUE constraint in the same transaction as processing, and return 2xx for duplicates. An event_type=correction references its original event through corrects_event_id. Never credit real users from test_mode=true events.

Delivery, retries and journal

Preview sends no request. A delivery test uses a synthetic px_test_… ID; HTTP 2xx proves only an endpoint response, not a tracker conversion. For an end-to-end check, follow your tracker link and reach a goal. The journal shows the event, status and error reason while masking secret parameters.

Network failures, 429 and 5xx are retried with backoff, up to 8 automatic attempts per cycle. Other 4xx and redirects stop delivery. Manual retry keeps the original event_id, URL and payload. A failed event blocks later events for that external click: restore the endpoint and retry it. Setting changes apply to future visits without resending history. The original referral attribution is preserved.

Management API: /api/v1/referrals/postbacks, authenticated owner only. GET lists and POST creates; /{id} supports GET and PUT; /{id}/events is the journal; /preview and /{id}/preview render a request; /{id}/test and /events/{event_id}/retry explicitly deliver. Create, save, test and retry require Idempotency-Key (1–96 characters); updates need the current version. The publisher X-PixorAds-Key is not used here.