Placing a bet

This guide walks you through finding an event, checking the current price, and placing an order — from a quick market order to a precise limit order.

All examples use https://api.futuur.com/v2.0. Authenticated requests require HMAC headers. See the Authentication guide for how to generate them.

Find an event

Use GET /v2.0/events/ to browse available prediction markets. You can search by keyword or filter by category. This endpoint does not require authentication.

import requests

response = requests.get(
    "https://api.futuur.com/v2.0/events/",
    params={
        "search": "US election",
        "currency_mode": "play_money",
        "limit": 5,
    },
)

events = response.json()["results"]
for event in events:
    print(event["id"], event["title"])

curl -G "https://api.futuur.com/v2.0/events/" \
  --data-urlencode "search=US election" \
  --data-urlencode "currency_mode=play_money" \
  --data-urlencode "limit=5"

The response includes a results array of events. Each event has an id and a markets array containing individual outcomes you can bet on.

Set currency_mode=play_money while testing. Switch to real_money when you’re ready to trade with USDC, USDT, or USD.

Inspect the event's markets

Each event has one or more markets, each representing a possible outcome. Retrieve a single event to see its markets in detail.

response = requests.get(
    "https://api.futuur.com/v2.0/events/12345/",
    headers={
        "Key": "YOUR_PUBLIC_KEY",
        "Timestamp": "1712500000",
        "HMAC": "YOUR_HMAC_SIGNATURE",
    },
)

event = response.json()
print(f"Event: {event['title']}")
for market in event["markets"]:
    print(f"  Market {market['id']}: {market['title']} @ {market['price']}")

curl "https://api.futuur.com/v2.0/events/12345/" \
  -H "Key: YOUR_PUBLIC_KEY" \
  -H "Timestamp: 1712500000" \
  -H "HMAC: YOUR_HMAC_SIGNATURE"

Note the id of the market you want to bet on and its current price (implied probability between 0 and 1).

Place a market order

To buy shares immediately at the best available price, set price to null. This is a market order.

response = requests.post(
    "https://api.futuur.com/v2.0/orders/",
    headers={
        "Key": "YOUR_PUBLIC_KEY",
        "Timestamp": "1712500000",
        "HMAC": "YOUR_HMAC_SIGNATURE",
        "Content-Type": "application/json",
    },
    json={
        "market": 67890,
        "side": "bid",
        "position": "long",
        "amount": 100,
        "currency": "OOM",
        "price": None,
    },
)

print(response.json())

curl -X POST "https://api.futuur.com/v2.0/orders/" \
  -H "Key: YOUR_PUBLIC_KEY" \
  -H "Timestamp: 1712500000" \
  -H "HMAC: YOUR_HMAC_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "market": 67890,
    "side": "bid",
    "position": "long",
    "amount": 100,
    "currency": "OOM",
    "price": null
  }'

Place a limit order

To specify the exact price you’re willing to pay, include a price value between 0 and 1. The order will only fill when the market reaches your price.

response = requests.post(
    "https://api.futuur.com/v2.0/orders/",
    headers={
        "Key": "YOUR_PUBLIC_KEY",
        "Timestamp": "1712500000",
        "HMAC": "YOUR_HMAC_SIGNATURE",
        "Content-Type": "application/json",
    },
    json={
        "market": 67890,
        "side": "bid",
        "position": "long",
        "amount": 100,
        "currency": "OOM",
        "price": 0.45,
    },
)

print(response.json())

curl -X POST "https://api.futuur.com/v2.0/orders/" \
  -H "Key: YOUR_PUBLIC_KEY" \
  -H "Timestamp: 1712500000" \
  -H "HMAC: YOUR_HMAC_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "market": 67890,
    "side": "bid",
    "position": "long",
    "amount": 100,
    "currency": "OOM",
    "price": 0.45
  }'

If the current market price is above 0.45, your order will sit in the order book until someone is willing to sell at that price.

Next steps

Reading the order book — understand market depth before placing orders
Selling a position — exit or reduce your wager
Orders reference — full endpoint documentation

Get Started

Core Concepts

Guides

Next steps

​Next steps

Next steps