feat(txodds): one-screen e2e demo — agents bid & settle a live World Cup edge

One "Start a market" click drives the whole thesis: real World Cup odds -> LLM
edge -> agents bid over CoralOS -> Solana escrow settles, all on one screen.

- coral-agents/seller-worldcup: a SERVICES=txline specialist persona (reuses the
  seller image, auto-registers from /agents/*).
- seller: txline `edge` now delivers the de-margined 1X2 market alongside the LLM
  value call; a bare fixture id means `edge`; two empty-string-default fixes
  (TXLINE_BASE_URL + INFERENCE_MODEL use `||` not `??`, since coral injects "" for
  unset options).
- marketplace/start.ts: launches seller-worldcup when TXLINE_API_KEY is set,
  forwards the token, passes BUYER_ARG.
- dashboard: WorldCupPanel renders the odds board + the edge call in RoundCard for
  txline-edge deliveries.
- docs: DEMO.md + E2E_DEMO.md runbooks.

Verified live on devnet end to end: WANT(txline) -> generalists decline ->
seller-worldcup wins -> DEPOSIT -> real odds + Claude value call -> RELEASE.
Croatia v Ghana: Home 37% / Draw 47% / Away 16%; settled with release tx 4jFAch89.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: trilltino

coral-agents/seller-agent/src/service.ts

@@ -48,7 +48,7 @@ export async function deliverService(request: string): Promise<string> {
 async function claudeInference(request: string): Promise<string> {
   const key = process.env.ANTHROPIC_API_KEY
   if (!key) return JSON.stringify({ error: 'ANTHROPIC_API_KEY not set' })
-  const model = process.env.INFERENCE_MODEL ?? 'claude-opus-4-8'
+  const model = process.env.INFERENCE_MODEL || 'claude-opus-4-8' // `||`: toml passes "" for unset options
 
   const res = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
@@ -140,7 +140,8 @@ async function newsHeadlines(request: string): Promise<string> {
 //   "edge <fixtureId>"  → odds + an LLM value call (the on-thesis, all-three-pillars product)
 // Verified live on devnet (2026-06): host txline-dev.txodds.com; odds path is /api/odds/snapshot/{id};
 // every call needs the guest JWT *and* the activated X-Api-Token.
-const TXLINE_BASE = process.env.TXLINE_BASE_URL ?? 'https://txline-dev.txodds.com'
+// `||` not `??`: coral passes an empty-string default for unset options, which `??` would not catch.
+const TXLINE_BASE = process.env.TXLINE_BASE_URL || 'https://txline-dev.txodds.com'
 
 async function txlineGet(path: string): Promise<unknown> {
   const apiToken = process.env.TXLINE_API_KEY
@@ -156,20 +157,27 @@ async function txlineGet(path: string): Promise<unknown> {
 }
 
 async function txlineService(request: string): Promise<string> {
-  const [verb, ...rest] = request.trim().split(/\s+/)
-  const fixtureId = rest[0]
-  switch ((verb || 'fixtures').toLowerCase()) {
+  const tokens = request.trim().split(/\s+/).filter(Boolean)
+  // A bare fixture id (single numeric token) is treated as `edge <id>` — the on-thesis product, and it
+  // survives the single-token WANT `arg` the marketplace broadcasts (e.g. BUYER_ARG=17588245).
+  let verb = (tokens[0] ?? 'fixtures').toLowerCase()
+  let fixtureId = tokens[1]
+  if (/^\d+$/.test(verb)) { fixtureId = verb; verb = 'edge' }
+  switch (verb) {
     case 'odds':
       return JSON.stringify({ service: 'txline-odds', fixtureId, odds: await txlineGet(`/api/odds/snapshot/${fixtureId}`) })
     case 'edge': {
       const odds = await txlineGet(`/api/odds/snapshot/${fixtureId}`)
+      // Pull the 1X2 de-margined market so the buyer/UI gets the odds board, not just the call.
+      const m = Array.isArray(odds) ? (odds as Array<Record<string, unknown>>).find((x) => String(x.SuperOddsType ?? '').includes('1X2')) : undefined
+      const market = m ? { names: m.PriceNames, pct: m.Pct } : undefined
       const raw = await claudeInference(
         'You are a football trading analyst. From these de-margined World Cup odds, return JSON ' +
           `{call, confidence} — a one-line value call and a 0-1 confidence. Odds: ${JSON.stringify(odds).slice(0, 1500)}`,
       )
       let analysis: unknown
       try { analysis = JSON.parse(raw).completion ?? raw } catch { analysis = raw }
-      return JSON.stringify({ service: 'txline-edge', fixtureId, analysis })
+      return JSON.stringify({ service: 'txline-edge', fixtureId, market, analysis })
     }
     case 'fixtures':
     default: {

coral-agents/seller-worldcup/coral-agent.toml

@@ -0,0 +1,34 @@
+edition = 4
+
+[agent]
+name = "seller-worldcup"
+version = "0.1.0"
+description = "Marketplace seller persona — World Cup oracle specialist. Reuses the seller-agent image; sells verified TxODDS World Cup data (the `txline` service) and an LLM value call."
+summary = "A specialist that bids only on World Cup data jobs and delivers an LLM-analysed edge."
+readme = "Bids in the shared market thread when the WANT is a `txline` service, wins because the generalists decline it, fetches de-margined World Cup odds from TxLINE, runs them through the LLM, and settles via escrow. Same image as seller-agent; SERVICES=txline + TXLINE_API_KEY shape it."
+
+[agent.license]
+type = "spdx"
+expression = "MIT"
+
+[options]
+SELLER_WALLET = { type = "string", description = "Devnet wallet pubkey that receives payments" }
+AGENT_NAME = { type = "string", default = "seller-worldcup", description = "Market identity (matches the registry name)" }
+SERVICES = { type = "string", default = "txline", description = "Inventory — this specialist bids only on txline (World Cup data)" }
+FLOOR_SOL = { type = "f64", default = 0.0005, description = "Cost floor — the LLM may never bid below this (the edge runs a real Claude call)" }
+PERSONA = { type = "string", default = "a World Cup trading specialist who sells verified TxODDS odds and a sharp one-line value call", description = "Bidding persona (LLM system prompt)" }
+SERVICE = { type = "string", default = "txline", description = "What deliverService returns: txline (fixtures | odds <id> | edge <id>)" }
+SOLANA_RPC_URL = { type = "string", default = "", description = "Solana RPC URL (devnet)" }
+ESCROW_DEADLINE_SECS = { type = "f64", default = 600, description = "Refund deadline for escrow deposits (seconds)" }
+TXLINE_API_KEY = { type = "string", default = "", description = "Activated TxLINE API token (from the one-time devnet subscribe — see examples/txodds)" }
+TXLINE_BASE_URL = { type = "string", default = "", description = "Override the TxLINE host (defaults to txline-dev.txodds.com)" }
+ANTHROPIC_API_KEY = { type = "string", default = "", description = "Anthropic key — the edge verb runs a Claude completion" }
+OPENAI_API_KEY = { type = "string", default = "", description = "OpenAI key — set with LLM_PROVIDER=openai to flip the brain" }
+LLM_PROVIDER = { type = "string", default = "", description = "anthropic (default) | openai" }
+LLM_MODEL = { type = "string", default = "", description = "Override the LLM model id" }
+INFERENCE_MODEL = { type = "string", default = "", description = "Model for the edge's Claude call (default claude-opus-4-8)" }
+TRACE = { type = "string", default = "", description = "Set to 1 to log CoralOS calls + on-chain steps" }
+
+# Reuses the already-built seller-agent image — no separate build needed.
+[runtimes.docker]
+image = "seller-agent:0.1.0"

examples/marketplace/start.ts

@@ -66,13 +66,28 @@ async function main() {
   const seller = (name: string) =>
     agent(name, { SELLER_WALLET: str(wallet), SOLANA_RPC_URL: str(rpc), AGENT_NAME: str(name), ...llmOpts })
 
+  // World Cup specialist — only joins when a TxLINE token is present (see examples/txodds/DEMO.md).
+  // It carries SERVICES=txline + the token; the generalist personas decline txline WANTs automatically.
+  const txlineKey = env.TXLINE_API_KEY
+  const worldcup = txlineKey
+    ? [agent('seller-worldcup', {
+        SELLER_WALLET: str(wallet), SOLANA_RPC_URL: str(rpc), AGENT_NAME: str('seller-worldcup'),
+        SERVICES: str('txline'), FLOOR_SOL: f64(Number(env.WORLDCUP_FLOOR_SOL ?? '0.0005')),
+        TXLINE_API_KEY: str(txlineKey),
+        ...(env.TXLINE_BASE_URL ? { TXLINE_BASE_URL: str(env.TXLINE_BASE_URL) } : {}),
+        ...llmOpts,
+      })]
+    : []
+
+  const sellers = ['seller-cheap', 'seller-premium', 'seller-lazy', ...(txlineKey ? ['seller-worldcup'] : [])]
   const buyerOpts: Record<string, unknown> = {
     BUYER_KEYPAIR_B58: str(keypair),
     AGENT_NAME: str('buyer-agent'),
     SOLANA_RPC_URL: str(rpc),
     BUYER_MAX_SOL: f64(Number(env.BUYER_MAX_SOL ?? '0.001')),
     BUYER_SERVICE: str(env.BUYER_SERVICE ?? 'coingecko'),
-    MARKET_SELLERS: str('seller-cheap,seller-premium,seller-lazy'),
+    BUYER_ARG: str(env.BUYER_ARG ?? 'SOL-USDC'),
+    MARKET_SELLERS: str(sellers.join(',')),
     ...llmOpts,
   }
 
@@ -85,6 +100,7 @@ async function main() {
           seller('seller-cheap'),
           seller('seller-premium'),
           seller('seller-lazy'),
+          ...worldcup,
         ],
       },
       namespaceProvider: { type: 'create_if_not_exists', namespaceRequest: { name: NS } },
@@ -94,7 +110,7 @@ async function main() {
   if (!sres.ok) throw new Error(`session create failed: ${sres.status} ${await sres.text()}`)
   const { sessionId } = await sres.json() as { sessionId: string }
 
-  console.log(`\n✅ Market session ${sessionId} — buyer + seller-cheap/-premium/-lazy.`)
+  console.log(`\n✅ Market session ${sessionId} — buyer + ${sellers.join(', ')}.`)
   console.log(`   receive wallet: ${wallet}`)
   console.log('   The buyer broadcasts a WANT; sellers bid; the winner settles via escrow.\n')
   console.log('   Watch the market:')

examples/marketplace/web/src/components/RoundCard.tsx

@@ -2,6 +2,7 @@ import type { Round } from '../types'
 import { StatusPill } from './StatusPill'
 import { BidRow, DeclinedRow } from './BidRow'
 import { SettlementBadge } from './SettlementBadge'
+import { WorldCupPanel } from './WorldCupPanel'
 
 /** One auction round: the need, the competing bids, the award + reasoning, and on-chain settlement. */
 export function RoundCard({ round }: { round: Round }) {
@@ -35,7 +36,9 @@ export function RoundCard({ round }: { round: Round }) {
       )}
 
       {round.delivered && (
-        <pre className="delivered" data-testid="delivered">{round.delivered.raw}</pre>
+        (round.delivered.data as { service?: string } | undefined)?.service === 'txline-edge'
+          ? <WorldCupPanel edge={round.delivered.data as Parameters<typeof WorldCupPanel>[0]['edge']} />
+          : <pre className="delivered" data-testid="delivered">{round.delivered.raw}</pre>
       )}
 
       <footer className="settle-row">

examples/marketplace/web/src/components/WorldCupPanel.tsx

@@ -0,0 +1,54 @@
+/** Renders a txline-edge delivery: the de-margined 1X2 odds board + the LLM value call. */
+interface Edge {
+  service: string
+  fixtureId?: string | number
+  market?: { names?: string[]; pct?: string[] }
+  analysis?: unknown
+}
+
+const LABEL: Record<string, string> = { part1: 'Home', draw: 'Draw', part2: 'Away' }
+
+/** The seller's `analysis` may be an object, a JSON string {call, confidence}, or plain prose. */
+function parseAnalysis(a: unknown): { call?: string; confidence?: number } {
+  if (a && typeof a === 'object') return a as { call?: string; confidence?: number }
+  if (typeof a === 'string') {
+    try {
+      const o = JSON.parse(a)
+      return o && typeof o === 'object' ? o : { call: a }
+    } catch {
+      return { call: a }
+    }
+  }
+  return {}
+}
+
+export function WorldCupPanel({ edge }: { edge: Edge }) {
+  const names = edge.market?.names ?? []
+  const pct = edge.market?.pct ?? []
+  const { call, confidence } = parseAnalysis(edge.analysis)
+  return (
+    <div className="wc-panel" data-testid="wc-edge">
+      <div className="wc-head">⚽ World Cup edge · fixture {edge.fixtureId}</div>
+      {names.length > 0 && (
+        <div className="wc-odds">
+          {names.map((name, i) => {
+            const p = Number(pct[i])
+            return (
+              <div className="wc-row" key={name}>
+                <span className="wc-sel">{LABEL[name] ?? name}</span>
+                <span className="wc-pct">{Number.isFinite(p) ? `${p.toFixed(0)}%` : '—'}</span>
+                <div className="wc-bar"><div className="wc-fill" style={{ width: `${Math.min(100, Number.isFinite(p) ? p : 0)}%` }} /></div>
+              </div>
+            )
+          })}
+        </div>
+      )}
+      {call && (
+        <p className="wc-call">
+          <strong>call:</strong> {call}
+          {confidence != null && <span className="wc-conf"> · {Math.round(Number(confidence) * 100)}% conf</span>}
+        </p>
+      )}
+    </div>
+  )
+}

examples/marketplace/web/src/styles.css

@@ -55,3 +55,16 @@ body { margin: 0; background: var(--bg); color: var(--txt); }
 .settle { color: var(--link); text-decoration: none; font-size: 12px; border: 1px solid var(--line); padding: 4px 8px; border-radius: 6px; }
 .settle:hover { border-color: var(--link); }
 .settle-refund { color: var(--refund); }
+
+/* World Cup edge panel (txline-edge deliveries) */
+.wc-panel { border: 1px solid var(--premium); border-radius: 10px; padding: 10px 12px; margin: 6px 0 10px; background: var(--bg); }
+.wc-head { font-size: 12px; color: var(--premium); margin-bottom: 10px; letter-spacing: .02em; }
+.wc-odds { display: flex; flex-direction: column; gap: 8px; }
+.wc-row { display: grid; grid-template-columns: 64px 40px 1fr; align-items: center; gap: 8px; }
+.wc-sel { font-size: 13px; font-weight: 600; }
+.wc-pct { font-size: 12px; color: var(--link); font-variant-numeric: tabular-nums; text-align: right; }
+.wc-bar { height: 6px; background: var(--panel); border-radius: 999px; overflow: hidden; }
+.wc-fill { height: 100%; background: linear-gradient(90deg, var(--link), var(--won)); border-radius: 999px; }
+.wc-call { margin: 12px 0 2px; font-size: 13px; color: var(--txt); border-top: 1px dashed var(--line); padding-top: 10px; }
+.wc-call strong { color: var(--premium); }
+.wc-conf { color: var(--dim); }

examples/txodds/DEMO.md

@@ -0,0 +1,55 @@
+# Live demo: an agent sells a World Cup edge for devnet SOL
+
+This is the "money shot" round — Demo A (the marketplace) settling Demo B (real TxODDS data) in
+**one live round**: the buyer wants a World Cup edge, a specialist seller fetches verified odds, an LLM
+turns them into a value call, and the buyer pays for it through the escrow. **Config only — no agent
+code changes** (the `txline` service is already in the seller image).
+
+## The pieces
+
+| Piece | What changes | Why |
+|---|---|---|
+| `coral-agents/seller-worldcup/coral-agent.toml` | **new persona** over the seller image, `SERVICES=txline` | a seller that bids on `txline` (auto-registered from `/agents/*`) |
+| `examples/marketplace/start.ts` | add `seller-worldcup` to the session, forward `TXLINE_API_KEY`, pass `BUYER_ARG` | so the persona launches with the token and the buyer's WANT carries the fixture |
+| `.env` | `TXLINE_API_KEY`, `BUYER_SERVICE=txline`, `BUYER_ARG=edge 17588245` | the token (one-time mint) + the WANT the buyer broadcasts |
+
+## How a round resolves
+
+```
+buyer        WANT service=txline arg="edge 17588245" budget=0.001
+seller-cheap   …silent (txline not in [jupiter,coingecko])      ← non-specialists decline
+seller-worldcup BID  price=0.0005  note="verified odds + edge"
+buyer        AWARD → seller-worldcup
+seller-worldcup ESCROW_REQUIRED → buyer DEPOSIT → on-chain
+seller-worldcup deliverService("txline edge 17588245")
+                 → fetch de-margined odds (txline-dev) → Claude value call
+                 → DELIVERED {"call":"…","confidence":…}
+buyer        RELEASED 0.0005 SOL → seller-worldcup   (real devnet tx)
+```
+
+The bidder's hard guard (`bidder.ts`: `!services.includes(want.service)`) makes the non-specialist
+personas sit out automatically, so the World Cup specialist wins — a clean "right agent for the job"
+story.
+
+## Run it
+
+```sh
+# 1. mint a fresh TXLINE_API_KEY into .env  (one-time subscribe+activate on devnet)
+#    — done by scripts in examples/txodds; the token is the only thing the seller needs
+# 2. set the WANT in .env:
+#    BUYER_SERVICE=txline
+#    BUYER_ARG=edge 17588245        # Croatia v Ghana
+# 3. rebuild not needed (txline already in the image). Fresh session:
+docker compose up -d coral
+cd examples/marketplace && npm start
+docker logs -f <buyer-container>   # WANT(txline) → AWARD seller-worldcup → DEPOSITED → RELEASED
+```
+
+## Notes
+
+- The activated API token is time-limited (tied to the 4-week free subscription) — mint it fresh
+  shortly before demoing.
+- `seller-worldcup` reuses the **already-built `seller-agent:0.1.0` image**; only its persona/options
+  differ, so there is no rebuild.
+- Fixture `17588245` is Croatia v Ghana; swap `BUYER_ARG` for any live fixture id from
+  `GET /api/fixtures/snapshot`.

examples/txodds/E2E_DEMO.md

@@ -0,0 +1,58 @@
+# Full e2e demo — one page, one button, the whole thesis
+
+Goal: a judge clicks **one button** and watches, on **one screen**, the complete loop:
+
+> **real World Cup odds → LLM edge → agents bid over CoralOS → Solana escrow settles → release**
+
+This reuses the kit's existing marketplace **dashboard** (which already has the button, the live round
+feed, bids, and Explorer-linked settlement) and makes it show the *World Cup* data the round trades.
+
+## Why this is small
+
+The dashboard already renders a live round from the feed: `WANT → BID → AWARD → DEPOSITED → DELIVERED
+→ RELEASED`, with deposit/release linked to the devnet Explorer. And the round object already carries
+`want.arg` (the fixture id) and `delivered.data` (the seller's edge JSON). Two changes make it the
+World Cup demo:
+
+| Change | File | Why |
+|---|---|---|
+| `edge` delivers the de-margined odds, not just the call | `coral-agents/seller-agent/src/service.ts` | so the round's `delivered.data` carries the 1X2 board |
+| RoundCard renders a World Cup panel for `txline-edge` | `examples/marketplace/web/src/components/RoundCard.tsx` | the odds bars + the LLM value call, in the same card as the settlement |
+
+No new backend: the feed's **Start** button already runs `start.ts`, which is World-Cup-configured
+(`seller-worldcup` + `BUYER_SERVICE=txline` + `BUYER_ARG=<fixture>` when `TXLINE_API_KEY` is set).
+
+## What the one screen shows
+
+```
+[ The Agent Marketplace ]                          (•) connected
+  ────────────────────────────────────────────────────────────
+  [ Start a market ]
+
+  Round 1 — WANT txline 17588245  (Croatia v Ghana)
+    seller-cheap     declined (not in inventory)
+    seller-worldcup  BID 0.0005  "verified odds + edge"      ← specialist wins
+    AWARD → seller-worldcup
+    ╔══ World Cup edge ═══════════════════════════════╗
+    ║ Croatia  ███████████ 36%                         ║   ← real de-margined odds
+    ║ Draw     ████████████████ 48%                    ║
+    ║ Ghana    █████ 16%                                ║
+    ║ call: "value on the draw"  · confidence 0.6       ║   ← the LLM edge
+    ╚══════════════════════════════════════════════════╝
+    deposit 0.0005 SOL ↗explorer   ·   release ↗explorer   ← real devnet txns
+```
+
+## Run it
+
+```sh
+# 0. one-time: TXLINE_API_KEY in .env (mint via examples/txodds) + BUYER_SERVICE=txline + BUYER_ARG=<id>
+docker compose up -d coral          # coordinator
+node scripts/dashboard.js           # feed (:4000) + dashboard (:5173), opens the browser
+# click "Start a market" → watch the World Cup round bid + settle live
+```
+
+## Robust fallback (no live devnet)
+
+The feed supports `FEED_FIXTURE=<recorded-extended-state.json>` — serve a recorded World Cup round so
+the dashboard renders the **real fold/parse path** deterministically, with no on-chain calls. Use this
+when demoing on flaky wifi.

examples/txodds/agent/service.ts

@@ -22,11 +22,16 @@ import { TxLineClient } from './txline.js'
 import { complete } from '@pay/agent-runtime'
 
 export async function deliverTxOdds(request: string): Promise<string> {
-  const [verb = 'fixtures', ...rest] = request.trim().split(/\s+/)
+  const tokens = request.trim().split(/\s+/).filter(Boolean)
+  // A bare fixture id (single numeric token) is treated as `edge <id>` — the on-thesis product, and it
+  // survives the single-token WANT `arg` the marketplace broadcasts (e.g. BUYER_ARG=17588245).
+  let verb = (tokens[0] ?? 'fixtures').toLowerCase()
+  let rest = tokens.slice(1)
+  if (/^\d+$/.test(verb)) { rest = [verb]; verb = 'edge' }
   const client = new TxLineClient()
 
   try {
-    switch (verb.toLowerCase()) {
+    switch (verb) {
       case 'fixtures': {
         const fixtures = await client.fixtures()
         return JSON.stringify({

examples/txodds/agent/txline.ts

@@ -41,7 +41,7 @@ export class TxLineClient {
   private jwt: string | undefined
 
   constructor(opts: TxLineOptions = {}) {
-    this.baseUrl = opts.baseUrl ?? process.env.TXLINE_BASE_URL ?? DEVNET_BASE
+    this.baseUrl = opts.baseUrl || process.env.TXLINE_BASE_URL || DEVNET_BASE
     this.apiToken = opts.apiToken ?? process.env.TXLINE_API_KEY
   }