Quickstart: Place a Bet

This guide walks you through the complete process of placing a bet from start to finish using the recommended async v3 API.

Use /v3/place_bet. It returns in ~100 ms with a correlation_id and avoids the 30s timeouts that plague the legacy synchronous endpoints. See Async API (v3) for the full reference.

Prerequisites

• API key
• Active account with sufficient balance
• Basic familiarity with HTTP requests

Step 1: Get Active Sessions

First, retrieve your active sessions:

curl -X POST https://api.b337.ai/api/session_ids \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Save the session_id from the response. You'll need it for placing bets.

Step 2: Submit Your Bet (v3, async)

Submit a bet using the session. The response comes back in ~100 ms with a correlation_id you'll use to fetch the actual result.

curl -X POST https://api.b337.ai/v3/place_bet \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "uuid-string",
    "category": "racing",
    "stake": 10.0,
    "bet_type": "non_promo",
    "track": "Flemington",
    "race_num": 1,
    "race_type": "(R)",
    "date": "2026-01-15",
    "runner": "Horse Name",
    "target_odds": 3.5,
    "market": "win"
  }'

Response:

{
  "status": "pending",
  "correlation_id": "9b3c…uuid…",
  "session_id": "uuid-string",
  "bookie": "tab",
  "username": "user@example.com",
  "submitted_at": "...",
  "timeout_at": "..."
}

Step 3: Poll for the Result

Poll /api/bet_status with the correlation_id until status flips to completed:

curl -X POST https://api.b337.ai/api/bet_status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correlation_ids": ["9b3c…uuid…"]}'

When status === "completed", the actual bet result lives in statuses[0].result: result.success is placed/not, and the bookie receipt (bet_id, odds, stake) is nested under result.bet_result.

Complete Example: Python

Here's a complete Python example using v3 + polling:

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.b337.ai'
HEADERS = {'X-API-Key': API_KEY, 'Content-Type': 'application/json'}

def place_bet_complete():
    # Step 1: Get active sessions
    print('Getting active sessions...')
    session_response = requests.post(f'{BASE_URL}/api/session_ids', headers=HEADERS)
    session_response.raise_for_status()
    session_data = session_response.json()

    if not session_data.get('sessions'):
        raise Exception('No active sessions found')

    active_session = next((s for s in session_data['sessions'] if s.get('active')), None)
    if not active_session:
        raise Exception('No active session found')

    session_id = active_session['session_id']
    print(f'Using session: {session_id}')

    # Step 2: Submit bet (returns in ~100ms with correlation_id)
    print('Submitting bet...')
    submit = requests.post(
        f'{BASE_URL}/v3/place_bet',
        headers=HEADERS,
        json={
            'session_id': session_id,
            'category': 'racing',
            'stake': 10.0,
            'bet_type': 'non_promo',
            'track': 'Flemington',
            'race_num': 1,
            'race_type': '(R)',
            'date': '2026-01-15',
            'runner': 'Horse Name',
            'target_odds': 3.5,
            'market': 'win',
        },
        timeout=15,
    )
    submit.raise_for_status()
    correlation_id = submit.json()['correlation_id']
    print(f'Submitted: {correlation_id}')

    # Step 3: Poll until completed (or timeout after 60s)
    deadline = time.time() + 60.0
    while time.time() < deadline:
        status = requests.post(
            f'{BASE_URL}/api/bet_status',
            headers=HEADERS,
            json={'correlation_ids': [correlation_id]},
            timeout=10,
        )
        status.raise_for_status()
        entry = status.json()['statuses'][0]
        if entry['status'] == 'completed':
            result = entry['result']
            br = result.get('bet_result') or {}
            if not result.get('success'):
                raise Exception(f"Bet placement failed: {br.get('error', 'Unknown error')}")
            print('Bet placed successfully!')
            print('Bet ID:', br.get('bet_id'))
            print('Odds:', br.get('odds'))
            return result
        if entry['status'] in ('timeout', 'unknown'):
            raise Exception(f"Bet ended in state: {entry['status']}")
        time.sleep(1)

    raise Exception('Polled for 60s without a result')


place_bet_complete()

What's Next?

• Async API (v3) - Full v3 reference, including webhook callbacks
• Error Handling - Learn how to handle errors gracefully