# Bidcliq — Full Technical Reference for AI Agents

> The programmatic operating system. Publisher tools, agentic ads, and header bidding infrastructure — unified in one platform.

## Company

- Name: Bidcliq, Inc.
- Website: https://bidcliq.com
- App: https://app.bidcliq.com
- Documentation: https://docs.bidcliq.com
- Blog: https://blog.bidcliq.com
- Contact: ops@bidcliq.com
- Address: 1007 N Orange St. 4th Floor Suite #5300, Wilmington, Delaware 19801, United States
- LinkedIn: https://www.linkedin.com/company/bidcliq/
- GitHub: https://github.com/prebid/salesagent

---

## Product 1: Publisher Console

The Publisher Console is a self-serve web application for managing the full ad stack. It is deployed at https://app.bidcliq.com.

### Features

**Site Management**
- Register and manage multiple publisher websites
- Domain verification and ownership confirmation
- Per-site configuration and script injection

**Ad Unit Management**
- Create, edit, and delete ad units (banner, video, native formats)
- Configure sizes, placements, and targeting
- Bulk operations across sites

**Header Bidding — Prebid.js**
- Managed client-side Prebid.js wrapper loaded via a single JS tag
- 30+ bidder adapter support: AppNexus, Rubicon, OpenX, PubMatic, Index Exchange, TripleLift, Sovrn, Sharethrough, Unruly, MediaGrid, Sonobi, Teads, and more
- Per-bidder configuration with timeouts, parameters, and targeting
- Dynamic adapter loading without code changes

**Header Bidding — Prebid Server**
- Managed server-side bidding infrastructure
- Reduces page latency by moving bid requests off the browser
- Global auto-scaling with multi-region deployment
- Hybrid mode: client-side + server-side bidding simultaneously

**User ID Modules**
- ID5 Universal ID
- Unified ID 2.0 (UID2)
- SharedID
- LiveRamp ATS
- Criteo ID
- Lotame Panorama
- Quantcast
- Fabrick
- Automatic cookie sync management

**Amazon APS Integration**
- Amazon Transparent Ad Marketplace (TAM) bidding
- Runs alongside Prebid demand for maximum competition
- Integrated configuration in the dashboard

**Google Ad Manager (GAM)**
- One-click OAuth-based GAM onboarding
- Automatic network detection and configuration sync
- Trafficker management and advertiser list access
- Automation rules for line item creation, pricing, and allocation

**Revenue Analytics**
- Real-time revenue dashboard
- Breakdowns by ad unit, device, country, and time period
- Estimated earnings with trend analysis
- eCPM, fill rate, and impression tracking
- Dynamic GAM reports with CSV export
- Reports explorer with flexible dimensions

**PageSpeed Insights**
- Integrated Core Web Vitals monitoring
- LCP, CLS, TBT impact tracking
- Per-site performance scoring

**Ad Quality — Geoedge**
- Real-time malvertising detection
- Automatic ad blocking for policy violations
- Dashboard integration for quality monitoring

**Billing**
- Self-serve billing dashboard
- Invoice history and downloads
- PayPal payment integration
- Revenue model configuration

**Developer API**
- REST API at /api/v1/
- Endpoints: users, sites, ad units, bidders, GAM reports, billing
- JWT authentication with API tokens
- Google OAuth for user authentication

### Tech Stack
- React 18 + Vite
- Ant Design component library
- Redux (with persist, thunk, logger)
- Axios for API calls
- ApexCharts + Recharts for data visualization
- PostHog analytics
- Google OAuth + reCAPTCHA

---

## Product 2: AI Sales Agent

The AI Sales Agent is an AI-powered deal execution engine implementing the Ad Context Protocol (AdCP). It is the Prebid.org reference implementation, open source at https://github.com/prebid/salesagent.

### Architecture

The agent runs as a Dockerized application behind nginx, exposing three services:

| Path | Service | Port | Purpose |
|------|---------|------|---------|
| /mcp/ | FastMCP Server | 8080 | AI agent tool-calling interface |
| /admin/ | Flask Admin UI | 8001 | Google OAuth-secured dashboard |
| /a2a | FastAPI Server | 8091 | Agent-to-agent protocol |

### MCP Server (Model Context Protocol)

The MCP server exposes the following tools that AI agents can call:

**Product Discovery**
- `get_products` — Search inventory packages by brief, format, pricing model, geography
- `get_creative_formats` — List available creative formats and specifications

**Media Buy Management**
- `create_media_buy` — Create a new media buy (insertion order) with budget, dates, targeting
- `update_media_buy` — Modify an existing media buy
- `list_media_buys` — List and filter media buys by status, date, principal

**Creative Management**
- `sync_creatives` — Upload and assign creatives to media buys
- `list_creatives` — List creatives with status and assignment details

**Delivery & Performance**
- `get_delivery` — Track delivery metrics for media buys
- `get_performance` — Performance reporting and analytics
- `get_signals` — Real-time campaign signals

**Task & Workflow**
- `list_tasks` — View pending tasks (approvals, actions)
- `get_capabilities` — Query agent capabilities

### A2A Protocol (Agent-to-Agent)

Enables autonomous deal negotiation between buyer and seller agents:
- Buyer agents discover inventory via structured queries
- Deal terms are negotiated programmatically
- Media buys are created and approved through workflow
- Creative assets are exchanged and validated

### Supported Pricing Models
- CPM (Cost Per Mille)
- VCPM (Viewable CPM)
- CPC (Cost Per Click)
- CPV (Cost Per View)
- CPCV (Cost Per Completed View)
- CPP (Cost Per Point)
- FLAT_RATE (Sponsorship)

### Ad Server Adapters

**Google Ad Manager (GAM)**
- Automatic line item type selection based on pricing + guarantees
- FLAT_RATE maps to SPONSORSHIP with CPD translation
- VCPM requires STANDARD type (GAM requirement)
- Creative trafficking with targeting and format mapping
- Order and advertiser management

**Broadstreet**
- Campaign and creative management
- Targeting configuration

**Mock Adapter**
- Simulates all pricing models for testing
- Used in development and CI

### Database Schema (PostgreSQL)
- tenants — multi-tenant isolation
- principals — advertisers/buyers with API tokens
- products — inventory packages (formats, pricing, targeting, availability)
- media_buys — orders with budget, dates, status lifecycle
- creatives — ad assets with approval workflow
- creative_assignments — creative-to-media-buy mapping
- workflow_steps — approval pipeline
- audit_logs — every action tracked
- currency_limits — per-tenant budget controls
- property_tags — inventory classification

### Multi-Tenant Architecture
- Database-backed tenant isolation
- Subdomain routing (tenant1.domain.com, tenant2.domain.com)
- Per-tenant configuration, branding, and property tags
- Role-based access: super admin, tenant admin, advertiser

### Security & Governance
- Google OAuth for admin UI
- Token-based auth for MCP and A2A
- Brand manifest policies
- Domain verification
- Property-level access controls
- Full audit logging

### Tech Stack
- Python 3.12 with uv package manager
- FastMCP v3 for MCP server
- Flask for Admin UI
- FastAPI + Uvicorn for A2A
- SQLAlchemy 2.0 + Alembic for database
- PostgreSQL (production)
- nginx reverse proxy
- Docker with multi-stage builds
- Pydantic for schema validation (AdCP-compliant)
- Google Ads API for GAM integration
- Prometheus metrics
- Logfire observability

---

## Product 3: Prebid Cache

High-performance edge caching infrastructure for header bidding auctions.

- URL: https://prebid-cache.bidcliq.com
- Global edge network with sub-50ms latency
- Auto-scaling infrastructure
- Format-aware caching (video, banner, native)
- Real-time cache purge
- Compatible with Prebid Server and Prebid.js

---

## Product 4: Developer Platform

APIs and tools for building on top of Bidcliq:

**REST API**
- Base URL: /api/v1/
- Authentication: JWT tokens, Google OAuth
- Resources: sites, ad_units, bidder_settings, gam/reports, billing, users

**MCP Tools**
- Endpoint: /mcp/
- Authentication: x-adcp-auth header
- Tools: get_products, create_media_buy, sync_creatives, get_delivery, etc.

**Webhooks**
- Delivery updates (pacing, completion, anomalies)
- Creative approvals (status changes)
- Media buy state changes
- Configurable per-tenant

**AdCP Schema**
- Compliant with adcp library (PyPI: adcp>=3.6.0)
- Schema validation: strict in development, permissive in production
- Extends library types with internal-only fields

---

## Pricing

| Plan | Price | Impressions | Key Features |
|------|-------|-------------|--------------|
| Starter | Free | Up to 10M/month | Client-side Prebid.js, 5 bidders, basic analytics |
| Growth | $299/mo (annual) or $349/mo | Up to 50M/month | Hybrid wrapper, Prebid Server, all User ID modules, GAM automation, priority support |
| Enterprise | Custom | Unlimited | Custom adapters, raw data, private Prebid Server, AI Sales Agent, developer API, dedicated AM, SLA |

---

## Integration Quick Start

### Publisher Console
1. Sign up at https://app.bidcliq.com/signup
2. Register your site
3. Configure bidders
4. Add the JS tag to your site header
5. Connect GAM via OAuth

### MCP Client (Python)
```python
from fastmcp.client import Client
from fastmcp.client.transports import StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://your-instance.bidcliq.com/mcp/",
    headers={"x-adcp-auth": "your_token"},
)

async with Client(transport=transport) as client:
    products = await client.tools.get_products(brief="video ads")
    media_buy = await client.tools.create_media_buy(
        product_ids=[products[0].id],
        budget={"amount": 5000, "currency": "USD"},
    )
```

### CLI
```bash
uvx adcp http://your-instance.bidcliq.com/mcp/ --auth your_token list_tools
uvx adcp http://your-instance.bidcliq.com/mcp/ --auth your_token get_products '{"brief":"video"}'
```

### Docker (Sales Agent)
```bash
git clone https://github.com/prebid/salesagent.git
cd salesagent
docker compose up -d
# Access at http://localhost:8000
```