OpenRTB Auction

The /openrtb2/auction endpoint accepts OpenRTB 2.x bid requests and returns deterministic bid responses.

Endpoint

POST /openrtb2/auction
Content-Type: application/json

Request Format

Minimal Request

{
  "id": "request-123",
  "imp": [
    {
      "id": "imp-1",
      "banner": {
        "w": 300,
        "h": 250
      }
    }
  ]
}

Full Request

{
  "id": "request-123",
  "site": {
    "domain": "example.com",
    "page": "https://example.com/article"
  },
  "imp": [
    {
      "id": "imp-1",
      "banner": {
        "w": 300,
        "h": 250,
        "format": [
          { "w": 300, "h": 250 },
          { "w": 320, "h": 50 }
        ]
      },
      "ext": {
        "mocktioneer": {
          "bid": 2.5
        }
      }
    }
  ],
  "ext": {
    "trusted_server": {
      "signature": "base64-encoded-signature",
      "kid": "key-id"
    }
  }
}

Request Fields

Field	Type	Required	Description
id	string	Yes	Request ID
imp	array	Yes	Array of impressions (min 1)
imp[].id	string	Yes	Impression ID
imp[].banner	object	Yes*	Banner object (*or other media type)
imp[].banner.w	integer	No	Width in pixels
imp[].banner.h	integer	No	Height in pixels
imp[].banner.format	array	No	Array of size objects
imp[].ext.mocktioneer.bid	float	No	Override bid price
ext.trusted_server.signature	string	No	Signature for request ID verification
ext.trusted_server.kid	string	No	Key ID for signature verification
site	object	No	Site information
site.domain	string	No	Domain for signature verification

Size Resolution

Size is determined in this order:

1. imp[].banner.w and imp[].banner.h
2. First entry in imp[].banner.format[]
3. Default: 300x250

Response Format

{
  "id": "request-123",
  "seatbid": [
    {
      "seat": "mocktioneer",
      "bid": [
        {
          "id": "019abc123",
          "impid": "imp-1",
          "price": 2.5,
          "adm": "<iframe src=\"//localhost:8787/static/creatives/300x250.html?crid=mocktioneer-imp-1&bid=2.50\" width=\"300\" height=\"250\" frameborder=\"0\" scrolling=\"no\"></iframe>",
          "adomain": ["example.com"],
          "crid": "mocktioneer-imp-1",
          "w": 300,
          "h": 250,
          "mtype": 1
        }
      ]
    }
  ],
  "cur": "USD"
}

Response Fields

Field	Type	Description
id	string	Echoed request ID
seatbid	array	Array of seat bids
seatbid[].seat	string	Always "mocktioneer"
seatbid[].bid	array	Array of bids
seatbid[].bid[].id	string	Unique bid ID (UUIDv7)
seatbid[].bid[].impid	string	Corresponding impression ID
seatbid[].bid[].price	float	Bid price in USD
seatbid[].bid[].adm	string	Ad markup (iframe HTML)
seatbid[].bid[].adomain	array	Advertiser domains
seatbid[].bid[].crid	string	Creative ID
seatbid[].bid[].w	integer	Creative width
seatbid[].bid[].h	integer	Creative height
seatbid[].bid[].mtype	integer	Media type (1 = banner)
cur	string	Currency (USD)

Price Override

Override the bid price using the ext.mocktioneer.bid field:

{
  "id": "test",
  "imp": [
    {
      "id": "1",
      "banner": { "w": 300, "h": 250 },
      "ext": {
        "mocktioneer": {
          "bid": 5.0
        }
      }
    }
  ]
}

The creative will display this bid amount.

Default Pricing

Without a price override, Mocktioneer uses fixed CPM prices based on ad size. Prices range from $1.70 (300x50) to $4.20 (970x250). Non-standard sizes use an area-based fallback formula.

See the complete pricing table for all supported sizes and their CPM values.

Examples

cURL

curl -X POST http://127.0.0.1:8787/openrtb2/auction \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "test-request",
    "imp": [{
      "id": "imp-1",
      "banner": {"w": 300, "h": 250}
    }]
  }' | jq .

Multiple Impressions

curl -X POST http://127.0.0.1:8787/openrtb2/auction \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "multi-imp",
    "imp": [
      {"id": "1", "banner": {"w": 300, "h": 250}},
      {"id": "2", "banner": {"w": 728, "h": 90}},
      {"id": "3", "banner": {"w": 320, "h": 50}}
    ]
  }' | jq .

With Price Override

curl -X POST http://127.0.0.1:8787/openrtb2/auction \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "custom-price",
    "imp": [{
      "id": "1",
      "banner": {"w": 300, "h": 250},
      "ext": {"mocktioneer": {"bid": 10.00}}
    }]
  }' | jq .

Error Responses

Missing Impressions (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "imp: must have at least 1 item"
  }
}

Missing Media Type (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "imp[0]: must have banner, video, or native"
  }
}

Invalid JSON (400)

{
  "error": {
    "code": "PARSE_ERROR",
    "message": "expected value at line 1 column 1"
  }
}

Request Signature Verification

Mocktioneer supports optional request signature verification. When site.domain is present, it attempts to verify the request signature using:

• ext.trusted_server.signature - Base64-encoded signature
• ext.trusted_server.kid - Key ID for signature verification

The JWKS is fetched from http://{site.domain}/.well-known/ts.jwks.json. Verification failures are logged but don't reject the request.