Ad Marketplace

Introduction

Buddo has a built-in ad marketplace that connects operators (apps that host ad placements) with businesses (advertisers that purchase those placements). When a user views an ad, the Buddo treasury pays both the operator and the user — creating a three-way value exchange where everyone benefits.

Operators register ad surfaces in their applications (banners, video slots, interstitials, etc.). Businesses create campaigns targeting those surfaces. The treasury funds all payouts, taking a 10% rake on ad purchases. Operators never pay users out of their own balance.

How It Works

The ad marketplace follows a six-step flow from placement registration through to payout:

Operator                   Business                   Buddo Platform
   |                          |                            |
   |  1. Register ad          |                            |
   |     placements           |                            |
   |     (surface types)      |                            |
   |                          |                            |
   |                          |  2. Create ad campaign     |
   |                          |     (name, surface, rate)  |
   |                          |                            |
   |                          |  3. Purchase placements ──>|
   |                          |     (treasury takes 10%)   |
   |                          |                            |
   |  4. Serve ads ──────────>|                            |
   |     GET /ads/serve       |                            |
   |     in operator's app    |                            |
   |                          |                            |
   |  5. User views ad        |                            |
   |     POST /ads/event      |                            |
   |     (impression/click)   |                            |
   |                          |                            |
   |                          |         6. Treasury pays   |
   |  <── operator payout ───|────────────────────────────|
   |                          |     user payout ──────────>|
   |                          |                            |

Ad Surface Types

Buddo supports five standard ad surface types. Operators register which types their app supports, and businesses target campaigns at specific surface types.

Campaign Lifecycle

Campaigns move through a defined set of states. Not all transitions are reversible — understand the lifecycle before creating campaigns at scale.

draft ──[activate]──> active ──[pause]──> paused ──[resume]──> active
                         |                                          |
                         |──[budget exhausted]──> exhausted        |
                         |                        (terminal)       |
                         |──[cancel]──> cancelled <───────────────┘
                                        (refunds unspent budget)

Serving Ads

When your app needs to display an ad, request a campaign from the serve endpoint. The platform selects an active campaign matching the requested surface type.

Endpoint

GET /api/external/ads/serve

Authentication

OAuth 2.0 Bearer token with the profile:read scope.

Query Parameters

Rate Limits

cURL Example

curl "https://api.buddo.xyz/api/external/ads/serve?surface_type=rewarded" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Success Response (200)

{
  "campaign": {
    "id": "a1b2c3d4-...",
    "name": "Summer Promo",
    "surface_type": "rewarded",
    "payout_rate": 50.0,
    "bitcoin_tier": null,
    "targeting_metadata": null
  }
}

Error Responses

Recording Ad Events

After serving an ad, record click interactions to trigger click-based payouts. Each event is recorded once per campaign per user — duplicates are rejected with a 409.

Endpoint

POST /api/external/ads/event

Authentication

OAuth 2.0 Bearer token with the profile:read scope.

Request Body (JSON)

cURL Example

curl -X POST https://api.buddo.xyz/api/external/ads/event \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "a1b2c3d4-...",
    "event_type": "impression",
    "surface_type": "rewarded"
  }'

Success Response (201)

{
  "event": {
    "id": "e5f6g7h8-...",
    "campaign_id": "a1b2c3d4-...",
    "event_type": "impression",
    "payout_rate_snapshot": 50.0,
    "surface_type": "rewarded",
    "inserted_at": "2026-05-21T14:30:00Z"
  }
}

Error Responses

Payouts

The Buddo ad marketplace uses a treasury-funded payout model. When a business purchases ad placements, the funds go to the Buddo treasury (minus a 10% rake). When users view or click ads, the treasury distributes payouts to both parties:

• Operator earns for hosting the ad surface in their app
• User earns for viewing or interacting with the ad

Payout Flow

1. Business purchases ad placements → funds enter the treasury (10% rake deducted at creation, non-refundable)
2. Ad is served in an operator's app via GET /api/external/ads/serve
3. Impression is recorded automatically at serve time (since v42.0) → no separate event call needed
4. Treasury pays the operator their hosting share immediately
5. Treasury pays the user their viewing reward immediately
6. For clicks: operator app calls POST /api/external/ads/event with event_type: "click"

The payout_rate on a campaign indicates the per-event payout amount. The payout_rate_snapshot on each recorded event freezes the rate at the time of the interaction for auditability.

Ad Reach Multiplier

Each deployment tier includes an ad_reach_multiplier field. Higher-tier deployments get increased ad distribution, meaning their placements are served more frequently. This incentivizes operators to upgrade their hosting tier for greater ad revenue.

The “Watch Ads for Rewards” Pattern

Rewarded ads are the most common integration pattern. The user explicitly opts in to watch an ad in exchange for Buddo points. Here is how to implement it:

1. Show the offer. Display a button like “Watch Ad for 100 Points” in your app UI.
2. Request a campaign. When the user taps the button, call GET /api/external/ads/serve?surface_type=rewarded to get an active campaign. The impression is recorded automatically at this point and the treasury payout is triggered — no separate event call needed.
3. Display the ad. Render the campaign content (video, interstitial, etc.) in your app. Wait for the user to complete viewing.
4. Confirm the reward. The treasury has already paid the user at serve time. Show a confirmation message. Verify the user's updated balance with GET /api/external/points.
5. Report clicks separately. If the user taps/clicks the ad, call POST /api/external/ads/event with event_type: "click" to record the click interaction.

Integration Example

This example shows a complete rewarded-ad flow in JavaScript. The game shows a “Watch Ad for Points” button, serves the ad, records the event, and confirms the user's payout.

const API_BASE = "https://api.buddo.xyz";

async function watchAdForReward(accessToken) {
  // 1. Request a rewarded ad campaign.
  //    Impression is recorded automatically at serve time (since v42.0) —
  //    no separate POST /ads/event call needed for impressions.
  const serveRes = await fetch(
    `${API_BASE}/api/external/ads/serve?surface_type=rewarded`,
    { headers: { "Authorization": `Bearer ${accessToken}` } }
  );

  if (serveRes.status === 404) {
    showMessage("No ads available right now. Try again later!");
    return;
  }
  // Daily cap exhausted — serve returns 200 with no campaign
  const serveData = await serveRes.json();
  if (!serveRes.ok || serveData.reason === "no_campaign_available") {
    showMessage("No ads available right now. Try again later!");
    return;
  }

  const { campaign } = serveData;

  // 2. Display the ad to the user.
  //    The treasury payout has already been triggered for the impression.
  await showAdOverlay(campaign);

  // 3. Confirm the reward — no extra API call needed for the impression.
  showMessage(`You earned ${campaign.payout_rate} points!`);

  // 4. Optionally refresh the displayed balance
  const balanceRes = await fetch(`${API_BASE}/api/external/points`, {
    headers: { "Authorization": `Bearer ${accessToken}` }
  });
  const { points } = await balanceRes.json();
  updateBalanceDisplay(points);

  // 5. If the user clicks/taps the ad, report it separately
  campaign.element.addEventListener("click", async () => {
    await fetch(`${API_BASE}/api/external/ads/event`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        campaign_id: campaign.id,
        event_type: "click",
        surface_type: "rewarded"
      })
    });
  });
}

// Wire up the button
document.getElementById("watch-ad-btn")
  .addEventListener("click", () => watchAdForReward(currentToken));

Required OAuth Scopes

Ad serving and event recording both use the profile:read scope. If your app also reads balances or spends points, you will need additional scopes.

See the OAuth PKCE Flow guide for how to request scopes during authorization.

Further Reading

• User API Reference — Ad serving and event recording endpoint schemas
• API Reference — Full endpoint documentation for all Buddo APIs
• OAuth PKCE Flow — Set up authentication for your operator app
• Operator API — Analytics and app management endpoints
• Deploy API — Deployment tiers and the ad_reach_multiplier
• JWT vs OAuth Tokens — When to use each authentication method