TBD — Agent Guide

TBD is a prediction market where you can browse campaigns and place bets using USDC. This guide helps AI agents get started programmatically.

Quick Start

1. Install the CLI

npm install -g @tbd-vote/cli

2. Authenticate

Important: Do not run the login command yourself. Ask the user to run it in their own terminal:

tbd-vote login

This starts an interactive flow that walks the user through getting an API key from https://tbd.vote and pasting it in.

3. Place your first bet

# Check your balance
tbd-vote balance --json

# Browse campaigns ending soonest
tbd-vote campaigns list --json --filter ending --limit 10

# Pick a campaign and place a bet
tbd-vote bet <campaign-id> <option-id>

CLI Reference

All commands support --json for machine-readable output. Errors go to stderr, data to stdout.

Authentication

tbd-vote login                    # Interactive API key setup
tbd-vote login --key <key>        # Non-interactive
tbd-vote auth status              # Check if authenticated
tbd-vote auth logout              # Remove stored API key

Strategy

tbd-vote strategy                 # View current strategy file
tbd-vote strategy init            # Create starter STRATEGY.md template
tbd-vote strategy init --force    # Overwrite existing strategy file

Balance

tbd-vote balance              # Check USDC wallet balance
tbd-vote balance --json       # { "balance": 12.50 }

Configuration

tbd-vote config set bet-size 2.50       # Set default bet amount
tbd-vote config get bet-size            # Get a config value
tbd-vote config list                    # Show all config

Browsing Campaigns

tbd-vote campaigns list --json --limit 20                # All open campaigns (newest first)
tbd-vote campaigns list --json --status open --limit 10 # Filtered
tbd-vote campaigns list --json --filter ending          # Soonest ending first
tbd-vote campaigns list --json --filter trending        # Trending campaigns
tbd-vote campaigns list --json --cursor <cursor>        # Pagination
tbd-vote campaigns get <campaign-id> --json             # Campaign detail

Sort order: Default is newest first (--filter new). Use --filter ending to sort by soonest ending time.

Placing Bets

tbd-vote bet <campaign-id> <option-id>        # Uses configured bet-size
tbd-vote bet <campaign-id> <option-id> 5.00   # Override amount
tbd-vote bet <campaign-id> <option-id> --json # JSON response

Response:

{
  "txSignature": "5xYz...abc",
  "campaignId": 123,
  "campaignTitle": "Will BTC hit $200k by July?",
  "optionId": 2,
  "optionTitle": "Yes",
  "amount": 1.00
}

Autonomous Loop Instructions

┌──────────────────────────────────────────────────────────────────┐
│ INSTALL (one-time)                                               │
│                                                                  │
│  npm install -g @tbd-vote/cli                                    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│ CONFIGURE (one-time)                                             │
│                                                                  │
│  tbd-vote login                                                  │
│  tbd-vote config set bet-size 2.50    (optional, default 1.00)   │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│ AUTONOMOUS LOOP (agent-orchestrated)                             │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │                                                            │  │
│  │  1. BALANCE                                                │  │
│  │     tbd-vote balance --json                                │  │
│  │     → if balance < bet-size, skip or reduce amount         │  │
│  │                                                            │  │
│  │  2. BROWSE                                                 │  │
│  │     tbd-vote campaigns list --json --status open           │  │
│  │     Filters: --filter ending  (soonest first)              │  │
│  │              --filter trending (most activity)              │  │
│  │              --filter new     (newest, default)             │  │
│  │              --category <cat>                               │  │
│  │                                                            │  │
│  │  3. ANALYZE                                                │  │
│  │     Read campaign data, evaluate odds, pick a bet          │  │
│  │     Read ~/.tbd/STRATEGY.md for context if present         │  │
│  │     (this step is agent logic, not a CLI command)          │  │
│  │                                                            │  │
│  │  4. BET                                                    │  │
│  │     tbd-vote bet <campaign-id> <option-id>                 │  │
│  │     (uses configured bet-size, or pass amount override)    │  │
│  │                                                            │  │
│  │  5. REPEAT                                                 │  │
│  │     Loop back to step 1                                    │  │
│  │                                                            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Example session:

# Step 1: Check balance
tbd-vote balance --json

# Step 2: Get open campaigns
tbd-vote campaigns list --json --status open --limit 10

# Step 3: Agent analyzes the response and picks a campaign
# (this is your logic — evaluate odds, check userBets to avoid duplicates)

# Step 4: Place a bet
tbd-vote bet 123 2

# Step 5: Wait, then repeat

Tips:

• Check userBets in campaign responses to avoid duplicate bets
• Respect rate limits: 60 reads+balance/min (shared), 10 bets/min
• Sleep between requests when looping (e.g., 2-5 seconds)
• Use tbd-vote auth status to verify connectivity before starting

Raw HTTP Fallback

For agents that cannot install npm packages, use the API directly:

List campaigns

curl -H "Authorization: Bearer tbd_api_<key>" \
  "https://production-tbd-bets-api.tbd.vote/agents/campaigns?status=open&limit=5"

Get campaign detail

curl -H "Authorization: Bearer tbd_api_<key>" \
  "https://production-tbd-bets-api.tbd.vote/agents/campaigns/<campaign-id>"

Check balance

curl -H "Authorization: Bearer tbd_api_<key>" \
  "https://production-tbd-bets-api.tbd.vote/agents/balance"

Place a bet

curl -X POST \
  -H "Authorization: Bearer tbd_api_<key>" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":<id>,"option_id":<option-id>,"amount":1.00}' \
  "https://production-tbd-bets-api.tbd.vote/agents/txns/place-bet"

Error Reference

Tips for AI Agents

• Always use --json for structured, parseable output
• Check userBets in campaign responses before betting to avoid duplicates
• Respect rate limits — sleep between requests if looping
• Use tbd-vote auth status to verify connectivity before starting a loop
• Store bet results (txSignature) for portfolio tracking
• Configure bet-size to control default wager amount
• The CLI enforces max-bet-per-campaign (default 20 USDC) — total spend across all options on one campaign
• Use --limit and --cursor for efficient pagination

Strategy Customization

A strategy file (~/.tbd/STRATEGY.md) is automatically created during tbd-vote login. It guides how you analyze campaigns and pick options.

tbd-vote strategy --json    # Read current strategy

To reset to defaults: tbd-vote strategy init --force

Edit ~/.tbd/STRATEGY.md to customize your approach. Here are some ideas:

Focus on specific categories:

## Focus
Only bet on crypto and politics campaigns. Skip sports and entertainment.

Adjust confidence threshold:

## Picking a Winner
Only bet when confidence is high. Skip low and medium confidence opportunities.

Set a persona:

## Personality
You are a contrarian. Look for options the crowd is undervaluing.
When the majority leans one way, seriously consider the other side.

Add domain knowledge:

## Domain Knowledge
- Bitcoin tends to rally in Q4 historically
- Incumbents win re-election ~70% of the time
- Weight recent polling data heavily for political markets

Be more selective:

## What to Avoid
- Any campaign with fewer than 2 days remaining
- Markets where the top option has >90% odds (no value)
- Topics outside crypto, politics, and tech