Skip to content

Seller Agent Integration

The buyer agent does not operate in isolation --- it needs at least one seller agent to provide advertising inventory. This page explains how to configure the buyer to connect to a seller, what API calls flow between them during a booking, and how authentication and multi-seller discovery work. If you are setting up the buyer for the first time, start with the Quickstart and return here when you are ready to customize the seller connection.

The buyer agent connects to one or more seller agents to search inventory, check availability, negotiate pricing, and book deals using the IAB OpenDirect 2.1 protocol.

Connection Configuration

The OpenDirectClient is configured through environment variables:

Variable Description Default
OPENDIRECT_BASE_URL Base URL of the seller's OpenDirect API http://localhost:3000/api/v2.1
OPENDIRECT_TOKEN OAuth 2.0 bearer token for seller auth (none)
OPENDIRECT_API_KEY API key for seller auth (fallback if no token) (none)

The client is instantiated in interfaces/api/main.py:

OpenDirectClient(
    base_url=settings.opendirect_base_url,
    oauth_token=settings.opendirect_token,
    api_key=settings.opendirect_api_key,
)

Authentication Priority

The client sets headers in this order:

  1. If oauth_token is provided: Authorization: Bearer <token>
  2. Else if api_key is provided: X-API-Key: <key>
  3. Otherwise: no authentication header

Multi-Seller Mode

For connecting to multiple seller agents, use the SELLER_ENDPOINTS setting (comma-separated URLs):

SELLER_ENDPOINTS=https://seller-a.example.com/api/v2.1,https://seller-b.example.com/api/v2.1

Parse with settings.get_seller_endpoints().

Discovery

Seller agents may expose a well-known discovery endpoint:

GET <seller-base>/.well-known/agent.json

This returns the seller's capabilities, supported OpenDirect version, and available endpoints. The buyer agent can use this to verify compatibility before starting a booking flow.

Main Integration Points

The buyer queries the seller's product catalog during the research phase:

  • List products: GET /products?$skip=0&$top=50 --- paginated product listing
  • Search products: POST /products/search --- filtered search with channel, format, pricing criteria
  • Get product: GET /products/{id} --- single product details

Availability and Pricing

Before recommending products, channel specialists check availability:

  • Check avails: POST /products/avails --- returns available impressions, estimated CPM, total cost, and delivery confidence

Negotiation

For eligible buyer tiers (Agency and Advertiser), the buyer can negotiate pricing with the seller before booking:

  • Start negotiation: Via NegotiationClient, the buyer submits a counter-offer on a seller's proposal
  • Multi-turn: The buyer and seller exchange offers until agreement or walk-away
  • Auto or manual: Negotiations can run fully automatically using a pluggable NegotiationStrategy, or step-by-step

See the Negotiation Guide for configuration and strategy details.

Order and Line Management

After approval, the buyer creates orders and books line items:

  • Create order: POST /accounts/{id}/orders --- creates an insertion order
  • Create line: POST /accounts/{id}/orders/{id}/lines --- creates a line item for a product
  • Reserve line: PATCH /accounts/{id}/orders/{id}/lines/{id}?action=reserve --- reserves inventory
  • Book line: PATCH /accounts/{id}/orders/{id}/lines/{id}?action=book --- confirms the booking

Performance Monitoring

For in-flight campaigns:

  • Line stats: GET /accounts/{id}/orders/{id}/lines/{id}/stats --- delivery metrics, pacing, spend

Request Flow

sequenceDiagram
    participant Buyer as Buyer Agent
    participant Seller as Seller Agent

    Buyer->>Seller: GET /.well-known/agent.json
    Seller-->>Buyer: Agent capabilities

    Buyer->>Seller: POST /products/search
    Seller-->>Buyer: Matching products

    Buyer->>Seller: POST /products/avails
    Seller-->>Buyer: Availability + pricing

    opt Negotiation (Agency/Advertiser tiers)
        Buyer->>Seller: POST /proposals/{id}/counter
        Seller-->>Buyer: Counter-offer or accept
    end

    Buyer->>Seller: POST /accounts/{id}/orders
    Seller-->>Buyer: Order created

    Buyer->>Seller: POST /accounts/{id}/orders/{id}/lines
    Seller-->>Buyer: Line created (Draft)

    Buyer->>Seller: PATCH .../lines/{id}?action=reserve
    Seller-->>Buyer: Line Reserved

    Buyer->>Seller: PATCH .../lines/{id}?action=book
    Seller-->>Buyer: Line Booked