Neuron Sports Ad Exchange

Query live sports advertising inventory: formats, list CPM, the biddable hard floor, and REAL remaining capacity from the booking ledger. Start here to see what is actually available. Each format reports list_cpm_usd (published rate) and floor_cpm_usd (lowest price a bid can win at).

{
  "type": "object",
  "properties": {
    "sport": {
      "type": "string",
      "enum": [
        "all",
        "gridiron",
        "fiba",
        "starsofsoccer",
        "fnba",
        "pitwall",
        "fifa"
      ],
      "description": "Target sports desk, or \"all\" for run-of-network."
    },
    "format": {
      "type": "string",
      "enum": [
        "leaderboard_728x90",
        "medium_rectangle_300x250",
        "mobile_banner_320x50",
        "voice_sponsor_read",
        "pregame_anthem_slot",
        "halftime_music_show"
      ],
      "description": "Optional single ad format to inspect."
    }
  },
  "required": []
}

Issue a BINDING quote for a slot. Returns a quote_id valid for 30 minutes and the exact price. You MUST call this before create_ad_order or create_checkout_session — the quote_id is the only thing that authorizes a charge.

{
  "type": "object",
  "properties": {
    "sport": {
      "type": "string",
      "enum": [
        "all",
        "gridiron",
        "fiba",
        "starsofsoccer",
        "fnba",
        "pitwall",
        "fifa"
      ],
      "description": "Target sports hub."
    },
    "format": {
      "type": "string",
      "enum": [
        "leaderboard_728x90",
        "medium_rectangle_300x250",
        "mobile_banner_320x50",
        "voice_sponsor_read",
        "pregame_anthem_slot",
        "halftime_music_show"
      ],
      "description": "Ad format type."
    },
    "impressions": {
      "type": "number",
      "description": "Impressions or audio listeners to reach (minimum 5000)."
    },
    "voice_persona": {
      "type": "string",
      "enum": [
        "The Architect",
        "Marcus",
        "Leo",
        "Sam",
        "Zareena",
        "Big Mike"
      ],
      "description": "Optional AI persona for synthetic voice sponsor reads."
    },
    "tender_id": {
      "type": "string",
      "description": "Optional. Pass the tender_id from list_open_tenders to buy a specific flagship event (e.g. the Super Bowl halftime slot). Flagship events carry a price premium; omit this to buy run-of-schedule at the base rate."
    }
  },
  "required": [
    "sport",
    "format",
    "impressions"
  ]
}

Book a flight against a quote_id from estimate_ad_cost, with creative assets. Price and impressions come from the stored quote — anything you send that contradicts it is ignored. Returns an order_id and a Stripe checkout URL for the exact quoted amount. Pass idempotency_key to make retries safe.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "description": "REQUIRED. The quote ID from estimate_ad_cost."
    },
    "brand_name": {
      "type": "string",
      "description": "Brand or sponsor company name."
    },
    "headline": {
      "type": "string",
      "description": "Short sponsor headline."
    },
    "click_url": {
      "type": "string",
      "description": "Destination HTTPS click-through URL."
    },
    "image_url": {
      "type": "string",
      "description": "HTTPS display creative (required for display formats)."
    },
    "voice_script": {
      "type": "string",
      "description": "10-15s spoken script, max 35 words (required for voice_sponsor_read)."
    },
    "selected_persona": {
      "type": "string",
      "enum": [
        "The Architect",
        "Marcus",
        "Leo",
        "Sam",
        "Zareena",
        "Big Mike"
      ],
      "description": "AI persona voicing the read."
    },
    "track_title": {
      "type": "string",
      "description": "Track title (required for music slots)."
    },
    "artist_name": {
      "type": "string",
      "description": "Artist name (required for music slots)."
    },
    "audio_stream_url": {
      "type": "string",
      "description": "HTTPS audio stream (required for music slots)."
    },
    "cover_art_url": {
      "type": "string",
      "description": "Cover artwork image URL."
    },
    "streaming_platform_url": {
      "type": "string",
      "description": "Spotify / Apple Music / SoundCloud link."
    },
    "rights_confirmed": {
      "type": "boolean",
      "description": "Must be true for music slots: you confirm licensing or ownership."
    },
    "advertiser_email": {
      "type": "string",
      "description": "Optional buyer email for the Stripe receipt."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional. Reuse on retry to avoid double-booking."
    }
  },
  "required": [
    "quote_id",
    "brand_name",
    "click_url"
  ]
}

Generate a live Stripe Checkout URL for an existing quote_id or order_id, settling to @neuronsystems. The amount is read from the stored quote; it cannot be supplied by the caller. Call estimate_ad_cost first.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string",
      "description": "Quote to settle. Provide this or order_id."
    },
    "order_id": {
      "type": "string",
      "description": "Existing order to settle. Provide this or quote_id."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email for the receipt."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional. Reuse on retry to avoid duplicate sessions."
    }
  },
  "required": []
}

Retrieve real delivery for an order: impressions served, clicks, audio completes, pacing, and settlement status.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID returned by create_ad_order."
    }
  },
  "required": [
    "order_id"
  ]
}

List slots with real unsold capacity right now, ordered by how close they are to selling out. Each carries list_cpm_usd (published rate), floor_cpm_usd (biddable hard floor), an indicative price at volume, and the exact estimate_ad_cost call to quote it.

{
  "type": "object",
  "properties": {
    "sport": {
      "type": "string",
      "enum": [
        "all",
        "gridiron",
        "fiba",
        "starsofsoccer",
        "fnba",
        "pitwall",
        "fifa"
      ],
      "description": "Optional sport filter."
    },
    "format": {
      "type": "string",
      "enum": [
        "leaderboard_728x90",
        "medium_rectangle_300x250",
        "mobile_banner_320x50",
        "voice_sponsor_read",
        "pregame_anthem_slot",
        "halftime_music_show"
      ],
      "description": "Optional format filter."
    },
    "limit": {
      "type": "number",
      "description": "Maximum tenders to return (default 8, max 50)."
    }
  },
  "required": []
}

Bid a CPM against a slot. The broker evaluates it against floor_cpm_usd (the hard floor) and the authorized discount band, then auto-accepts (returning a spendable quote_id), counters with a price, or rejects. Bid at or above min_acceptable_cpm_usd from check_neuron_inventory or a prior response to be accepted; no bid is ever accepted below floor_cpm_usd.

{
  "type": "object",
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "leaderboard_728x90",
        "medium_rectangle_300x250",
        "mobile_banner_320x50",
        "voice_sponsor_read",
        "pregame_anthem_slot",
        "halftime_music_show"
      ],
      "description": "Ad format being bid on."
    },
    "sport": {
      "type": "string",
      "enum": [
        "all",
        "gridiron",
        "fiba",
        "starsofsoccer",
        "fnba",
        "pitwall",
        "fifa"
      ],
      "description": "Target sports hub."
    },
    "bid_cpm_usd": {
      "type": "number",
      "description": "Proposed CPM in USD."
    },
    "impressions": {
      "type": "number",
      "description": "Impressions sought (minimum 5000)."
    },
    "bidder_name": {
      "type": "string",
      "description": "Bidding brand, DSP, or artist."
    },
    "tender_id": {
      "type": "string",
      "description": "Optional. Bid on a specific flagship event from list_open_tenders. Event floors are higher than the base rate, so omitting this judges the bid against base pricing."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional. Reuse on retry."
    }
  },
  "required": [
    "format",
    "sport",
    "bid_cpm_usd",
    "impressions",
    "bidder_name"
  ]
}