API Reference

{ "debate_id": "550e8400-e29b-41d4-a716-446655440000" }

curl -X POST https://api.stockdebate.ai/v1/debates \
  -H "Authorization: Bearer sdai_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker":"NVDA","market":"us","format":"text","length":"short"}'

curl https://api.stockdebate.ai/v1/debates/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sdai_YOUR_KEY"

const es = new EventSource(
  `https://api.stockdebate.ai/v1/debates/${debateId}/stream`,
  { headers: { Authorization: "Bearer sdai_YOUR_KEY" } }
);

es.addEventListener("round_ready", (e) => {
  const round = JSON.parse(e.data);
  console.log(`Round ${round.round_number}:`, round.moderator_text);
});

es.addEventListener("done", () => {
  console.log("Debate complete");
  es.close();
});

{ "ok": true }

curl -X POST https://api.stockdebate.ai/v1/debates/DEBATE_ID/convert-to-audio \
  -H "Authorization: Bearer sdai_YOUR_KEY"

curl -o debate.mp3 \
  https://api.stockdebate.ai/v1/debates/DEBATE_ID/audio/merged \
  -H "Authorization: Bearer sdai_YOUR_KEY"

import requests, sseclient, json

API_KEY = "sdai_YOUR_KEY"
BASE    = "https://api.stockdebate.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. Create debate
r = requests.post(f"{BASE}/debates", headers=HEADERS, json={
    "ticker": "NVDA", "market": "us", "language": "en",
    "format": "text", "length": "short"
})
r.raise_for_status()
debate_id = r.json()["debate_id"]
print(f"Created: {debate_id}")

# 2. Stream rounds in real-time (pip install sseclient-py)
stream = requests.get(
    f"{BASE}/debates/{debate_id}/stream",
    headers={**HEADERS, "Accept": "text/event-stream"},
    stream=True
)
client = sseclient.SSEClient(stream)
for event in client.events():
    if event.event == "round_ready":
        rnd = json.loads(event.data)
        print(f"\n── Round {rnd['round_number']} ──")
        print(f"Moderator : {rnd['moderator_text'][:200]}...")
        print(f"Bull      : {rnd['pitcher_text'][:200]}...")
        print(f"Bear      : {rnd['doubter_text'][:200]}...")
    elif event.event == "done":
        print("\nDebate complete.")
        break

// npm install @microsoft/fetch-event-source
import { fetchEventSource } from "@microsoft/fetch-event-source";

const API_KEY = "sdai_YOUR_KEY";
const BASE    = "https://api.stockdebate.ai/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 1. Create debate
const { debate_id } = await fetch(`${BASE}/debates`, {
  method: "POST",
  headers,
  body: JSON.stringify({ ticker: "AAPL", market: "us", format: "text", length: "short" }),
}).then(r => r.json());

// 2. Stream in real-time
await fetchEventSource(`${BASE}/debates/${debate_id}/stream`, {
  headers,
  onmessage(ev) {
    if (ev.event === "round_ready") {
      const round = JSON.parse(ev.data);
      console.log(`Round ${round.round_number}:`, round.moderator_text);
    }
    if (ev.event === "done") console.log("Debate complete!");
  },
});

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmountRequired": "500000",
    "resource": "https://api.stockdebate.ai/v1/a2a/debates",
    "description": "StockDebate AI — Text Debate ($0.50 USDC)",
    "mimeType": "application/json",
    "payTo": "0x<server-wallet>",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USDC", "version": "2" }
  }]
}

curl https://api.stockdebate.ai/.well-known/payment-manifest.json

{ "debate_id": "550e8400-e29b-41d4-a716-446655440000" }

# With API key
curl https://api.stockdebate.ai/v1/a2a/debates/DEBATE_ID \
  -H "Authorization: Bearer sdai_YOUR_KEY"

# With x402 client (Python) — auth handled automatically
debate = client.get(f"https://api.stockdebate.ai/v1/a2a/debates/{debate_id}").json()

curl -o debate.mp3 \
  https://api.stockdebate.ai/v1/debates/DEBATE_ID/audio/merged

curl -o round1_bull.mp3 \
  https://api.stockdebate.ai/v1/debates/DEBATE_ID/audio/1/pitcher

# pip install x402
from x402.client import X402Client
import time

client = X402Client(wallet_private_key="0xYOUR_PRIVATE_KEY")
BASE = "https://api.stockdebate.ai/v1"

# 1. Create debate (x402 handles the 402 challenge and payment automatically)
response = client.post(
    f"{BASE}/a2a/debates",
    json={"ticker": "NVDA", "market": "us", "format": "text", "length": "short"}
)
response.raise_for_status()
debate_id = response.json()["debate_id"]
print(f"Debate created: {debate_id}")

# 2. Poll until done
while True:
    r = client.get(f"{BASE}/a2a/debates/{debate_id}")
    debate = r.json()
    if debate["status"] == "done":
        break
    if debate["status"] == "failed":
        raise RuntimeError("Generation failed")
    print(f"Status: {debate['status']} ({len(debate.get('rounds', []))} rounds so far)")
    time.sleep(5)

# 3. Print rounds
for rnd in debate["rounds"]:
    print(f"\n── Round {rnd['round_number']} ──")
    print(f"Moderator : {rnd['moderator_text'][:200]}...")
    print(f"Bull      : {rnd['pitcher_text'][:200]}...")
    print(f"Bear      : {rnd['doubter_text'][:200]}...")