Skip to main content

​
Bid Schema

​
Overview

Brand Agent bid submitted in response to a ContextRequest. Includes pricing for CPX/CPC/CPA, structured offer metadata, and a signed auth block.

​
Required Fields

FieldTypeDescription
bid_idstringUnique identifier for this bid
brand_agent_idstringIdentifier of the Brand Agent placing the bid
context_idstringID of the ContextRequest being bid on
wallet_idstringWallet to debit if the bid wins
pricingobjectPricing vector (CPX required, CPC/CPA optional)
offerobjectOffer metadata + creative input
timestampstringISO 8601 timestamp for the bid
authobjectNonce + signature for replay prevention

​
Pricing Object

FieldTypeRequiredDescription
cpxstringYesPrice per exposure (USD). Pattern: ^\d+\.\d{2,}$
cpcstringNoPrice per click (USD). Pattern: ^\d+\.\d{2,}$
cpastringNoPrice per conversion (USD). Pattern: ^\d+\.\d{2,}$
currencystringNoISO 4217 currency code (default USD)

​
Offer Object

Contains creative_input, the normalized asset payload shared with the operator.
FieldTypeRequiredDescription
brand_namestringYesBrand or advertiser name
product_namestringYesProduct or offer name
descriptionsstring[]YesLong-form descriptions / copy
value_propsstring[]YesShort bullet value props
resource_urlsURI[]YesDestination / tracking URLs
image_urlsURI[]YesCreative image URLs

​
Authentication Object

FieldTypeDescription
noncestringOne-time nonce used to prevent replays
signaturestringSignature over the canonical bid payload

​
Example

{
  "bid_id": "bid_7823",
  "brand_agent_id": "brand_agent_123",
  "context_id": "ctx_92f",
  "wallet_id": "wallet_890",
  "pricing": {
    "cpx": "0.05",
    "cpc": "0.45",
    "cpa": "10.00",
    "currency": "USD"
  },
  "offer": {
    "creative_input": {
      "brand_name": "Nimbus",
      "product_name": "Nimbus CRM Pro",
      "descriptions": ["AI-native CRM for 5-50 person teams."],
      "value_props": ["Automated pipeline insights", "Embedded copilots"],
      "resource_urls": ["https://nimbus.example/signup"],
      "image_urls": ["https://cdn.example.com/nimbus/crm.png"]
    }
  },
  "timestamp": "2025-11-11T18:00:01Z",
  "auth": {
    "nonce": "nonce_456",
    "signature": "sig_789"
  }
}

​
Validation Rules

  • cpx, cpc, cpa must match ^\d+\.\d{2,}$
  • Arrays in creative_input must contain at least one entry
  • resource_urls and image_urls must be valid URIs
  • timestamp must be ISO 8601 / RFC 3339 formatted