<- Back to Home

UniAds Protocols

Developer Ads Protocol Guide

Use UniAds protocols to add sponsored context without letting ads interrupt the agent's main task.

Default trial API key

sk-demo-default-uniads

Developer trial API key

sk-dev-trial-uniads

Platform base URL

http://103.242.15.56

Proxy endpoint

/v1/serve-ad

Admins can modify these values in Admin Command Center > Developer Trial Configuration.

Protocol Overview

Developers can choose REST, SDK, MCP, or deterministic server-side weave. All sponsored API trials must go through the UniAds proxy or platform serving endpoint, never a direct vendor URL.

REST

Universal HTTP integration for any language or no-code platform.

SDK

Native Python path with fail-open sponsored fetch, telemetry, and proxy helpers.

MCP

Tool-host integration for Claude Desktop, local agents, or MCP-aware runtimes.

Server Weave

Backend-rendered sponsored presentation for deterministic output boundaries.

Quick Start

  1. 1Unlock developer access from the user dashboard.
  2. 2Copy the developer trial key or rotate your own developer key when ready.
  3. 3Test REST first, then SDK or MCP depending on your agent host.

REST Protocol

The universal protocol. Use it for JavaScript, Go, Java, no-code tools, or first smoke tests.

curl -X POST "http://103.242.15.56/v1/serve-ad" \
  -H "Authorization: Bearer sk-dev-trial-uniads" \
  -H "Content-Type: application/json" \
  -d '{"user_context":"Find internship tools for a product-minded student."}'

Python SDK Protocol

Recommended for Python agents. The SDK handles matching, fallback, telemetry, and proxy calls.

from agent_ad_broker import AgentAdBroker

broker = AgentAdBroker(
    api_key="sk-dev-trial-uniads",
    base_url="http://103.242.15.56",
    demo_mode=False,
)

ad = broker.get_ad("internship search, product and engineering")

MCP Protocol

Good for tool hosts and local agents. MCP exposes controlled tools without letting ads rewrite the primary task.

# PowerShell
$env:AD_EXCHANGE_API_KEY="sk-dev-trial-uniads"
$env:AD_EXCHANGE_BASE_URL="http://103.242.15.56"

cd agent_ad_mcp
pip install -e .
agent-ad-mcp

Server-Side Weave Protocol

Use when the platform needs strict presentation boundaries. Generate the main answer first, then let the server append sponsored presentation deterministically.

POST http://103.242.15.56/v1/weave-ad
Authorization: Bearer sk-dev-trial-uniads
Content-Type: application/json

{
  "raw_agent_text": "Here is the user's main answer.",
  "campaign_id": "selected-campaign-id"
}

Safety Rules

  • ✓Primary answer must continue even if ads fail or time out.
  • ✓Sponsored data is supplemental and must not override user intent or developer policy.
  • ✓Do not expose trial keys as permanent production secrets.
  • ✓Service API trials and external calls must go through the UniAds proxy layer.
  • ✓Use short timeouts and log telemetry asynchronously.

Production Checklist

  • ✓Unlock developer access from the user dashboard.
  • ✓Copy the developer trial key or rotate your own developer key when ready.
  • ✓Test REST first, then SDK or MCP depending on your agent host.
  • ✓Confirm fallback behavior by temporarily disabling sponsor settings.
  • ✓Move production secrets to environment variables before launch.