Prediction Bridge Search

Use this skill when the user wants to find relevant prediction markets/events for:

• a short text query (topic, question, headline)
• a URL to an article
• an X (Twitter) status link (the backend resolves and extracts the tweet text)

Usage scenarios (when to use)

Use this skill when the user asks:

• “Find prediction markets for this topic/headline”
• “What markets match this tweet/X link?”
• “Search Polymarket/Kalshi for events about …”

This skill is best for:

• turning unstructured text (or an X URL) into ranked, actionable event links
• quickly surfacing the top 5–10 matches with a brief market snapshot

Not a good fit when the user wants:

• full market orderbooks or historical candles (use the market-data endpoints instead)
• deep-dive sentiment/timeline generation (use the event deep-dive endpoints instead)

This skill calls the existing Prediction Bridge backend endpoint:

• POST /api/v1/search/unified

It returns matched events (prediction market events) and optionally matched news.

Configuration

API base (defaults to production):

• PREDICTION_BRIDGE_API_URL

Defaults:

• Production: https://prediction-bridge.onrender.com/api/v1
• Local dev (if you run the backend locally): http://localhost:8000/api/v1

How to run

1. Build the query text

• If the user provides an X status link, pass the URL as text unchanged. The backend will resolve it.
• If the user provides plain text, pass it as-is.

2. Call unified search

Use exec with curl:

API_URL="${PREDICTION_BRIDGE_API_URL:-https://prediction-bridge.onrender.com/api/v1}"

curl -sS -X POST "$API_URL/search/unified" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: pb-$(date +%s)" \
  --data-binary @- <<'JSON'
{
  "text": "<USER_TEXT_OR_X_URL>",
  "limit": 10,
  "offset": 0,
  "include_inactive": false,
  "include_markets": true,
  "markets_per_event": 1,
  "include_translations": false
}
JSON

Notes:

• Use markets_per_event: 1 to keep payload small but still show the leading market.
• If the user explicitly asks for more markets per event, increase markets_per_event.

API response format (what you will receive)

POST /search/unified returns JSON with this shape (fields may be omitted or null depending on data availability):

{
  "source": {
    "type": "x" ,
    "url": "https://x.com/.../status/...",
    "text": "resolved tweet text (optional)",
    "id": "optional"
  },
  "events": [
    {
      "score": 0.82,
      "event": {
        "id": 123,
        "title": "...",
        "description": "...",
        "source": "polymarket",
        "source_url": "https://polymarket.com/event/...",
        "status": "active",
        "volume_usd": 12345.67,
        "liquidity_usd": 2345.0,
        "end_date": "2026-12-31T00:00:00Z",
        "markets": [
          {
            "id": 999,
            "question": "...",
            "outcomes": ["Yes", "No"],
            "outcome_prices": {"Yes": 0.61, "No": 0.39},
            "volume": 1000.0,
            "active": true,
            "closed": false
          }
        ]
      }
    }
  ],
  "news": [
    {
      "score": 0.74,
      "news": {
        "id": 456,
        "title": "...",
        "summary": "...",
        "url": "https://...",
        "image_url": "https://...",
        "source": "...",
        "published_at": "2026-02-01T12:34:56Z"
      }
    }
  ]
}

Key points:

• events[] is the primary output. Each item has { score, event }.
• score is a relevance score; higher is better.
• event.markets is present when you requested include_markets: true.
  • When you set markets_per_event, the backend may return only a preview subset.
• news[] is optional supporting context; do not let it crowd out event results.

How the agent should parse + handle results

Important:

• Do NOT show the raw JSON response to the user.
• Always parse/validate the response first, then present the matched events as a clean, human-readable list.

1. Validate payload shape

• Treat missing/invalid JSON as a failure and retry once (or ask the user to retry).
• If events is missing or not an array, treat it as empty.

2. Rank and select

• Sort events by score descending (even if the backend already sorted).
• Default to presenting top 5 results; show up to 10 if the user asked for “more”.

3. Extract a “market snapshot” per event (best-effort)

• Prefer event.source_url as the click-through link.
• If event.source_url is missing, fall back to the frontend detail page:
  • https://www.predictionbridge.xyz/event/<event.id>
• If event.markets[0].outcome_prices exists:
  • show the YES/Long price if present: outcome_prices.Yes or outcome_prices.Long
  • otherwise show the first available outcome price

4. Present concise output

• For each event, output:
  • Title
  • Source/platform (event.source)
  • Relevance score (rounded, e.g. 0.82)
  • Link (event.source_url preferred)
  • 1-line snapshot: probability (if available) + volume/liquidity (if available)

5. Optional: include related news

• If news exists, include at most 1–3 items with title + URL as extra context.

6. Empty results

• If events is empty:
  • say no strong matches found
  • ask for 1 clarifying detail (timeframe, geography, person/org name, or paste the text instead of a shortened link)

How to present results

After you receive JSON:

• If events is empty, say no matches were found and ask for a more specific query.
• Otherwise list the top results (usually 5–10):
  • event title
  • platform/source (e.g. Polymarket, Kalshi)
  • score (higher is better)
  • a link to the event (event.source_url when present)
  • quick market snapshot (from the first market in event.markets, if present)

If news is present, optionally show 1–3 related news items as context.

Error handling

• HTTP 400: invalid input or X resolve error → ask the user to paste a different link or provide plain text.
• HTTP 503: backend DB unavailable → suggest retrying later.
• Any network error: confirm PREDICTION_BRIDGE_API_URL and whether the API is reachable.