Quickstart

The magicmarkets CLI (command line interface) walks the same flow in a few commands: check your key, list markets, read the book, quote a betslip and place an order.

Create an API key

Sign in at magicmarkets.com, go to Settings, then API, and click Add API Key. API access needs a minimum deposit of 10 USDT. The value is shown once. Store it somewhere safe. See Authentication.

Check the key over REST

Do this before you open the stream. The WebSocket handshake refuses a bad key with only a status code and a one-word body. REST returns a full error envelope.

curl https://magicmarkets.com/v2/balance/ -H "X-Api-Key: $MAGICMARKETS_API_KEY"

A 200 with {"status": "ok", ...} means the key works. 401 auth_error means the server did not accept a key. Check the header name and the key value.

Pick your path

The CLI is the fastest start. REST and WebSocket work from any language.

Path A: the CLI

magicmarkets is a single Go binary for the whole v2 API, with a built-in MCP server. It is open source under the MIT licence at github.com/magicmarkets/magicmarkets-cli. You need a recent Go toolchain. There are no prebuilt binaries yet. If the shell cannot find magicmarkets after install, run make where and add that directory to your PATH.

git clone https://github.com/magicmarkets/magicmarkets-cli
cd magicmarkets-cli
make install
export MAGICMARKETS_API_KEY=your-key

magicmarkets status                        # key, base URL, version
magicmarkets markets                       # every event with live prices
magicmarkets offers fb <event-id>          # the book for one event, both sides; copy an id from markets

To let an agent read the same book:

claude mcp add magicmarkets -e MAGICMARKETS_API_KEY=your-key -- magicmarkets mcp

Trading tools stay off until you set MAGICMARKETS_ALLOW_TRADING=1. See CLI and MCP server.

Path B: REST and WebSocket

REST lists events, returns a snapshot of an event’s offers, and commits betslips and orders. The WebSocket pushes live offers, your private betslip quotes (pmm) and order updates. You normally hold one socket open and call REST alongside it.

GET /v2/balance/                      verify the key over REST first
connect wss://.../v2/stream           collect ["event", ...] until ["sync", ...]
["register_event", sport, event_id]   -> ["offer", ...] snapshot
pick an offer                         its sport, event_id and bet_type are all you need
POST /v2/betslips/                    -> betslip_id
wait for ["pmm", ...] on the socket   the quote for your betslip
POST /v2/orders/                      -> order_id, with a request_uuid
watch ["order", ...] until done or failed

The Place an order guide walks every step in runnable Python.

Events and offers with curl

Lines 2 and 3 of the flow above also work over REST, when a snapshot is enough. List football events that start after now:

curl "https://magicmarkets.com/v2/events/?sport=fb&start_time_from=$(date -u +%Y-%m-%dT%H:%M:%SZ)&limit=5" \
  -H "X-Api-Key: $MAGICMARKETS_API_KEY"

{"status": "ok", "data": [{"event_type": "normal", "sport": "fb",
  "event_id": "2026-09-13,1001,2002", "competition_id": 1,
  "competition_name": "England Premier League", "competition_country": "XE",
  "home": "Arsenal", "away": "Chelsea", "event_name": "Arsenal vs. Chelsea",
  "ir_status": "pre_event", "start_time": "2026-09-13T15:00:00Z"}]}

Each entry is the object the stream sends as ["event", ...]. limit defaults to 500 and goes up to 5000. To read the next page, pass the last entry’s "{sport},{event_id}" as after. A page shorter than limit is the last one. Filtering by event_id or competition_id needs sport as well. ir_status can stay pre_event after start_time passes. Check start_time before you treat an event as not started. Read the offers on that event:

curl "https://magicmarkets.com/v2/offers/?sport=fb&event_id=2026-09-13,1001,2002&market_type=wdw" \
  -H "X-Api-Key: $MAGICMARKETS_API_KEY"

sport and event_id are required. event_id is a repeated query parameter: repeat it to price up to 20 events in one call. bet_type, market_type and min_liquidity (USDT, summed across the price_list) narrow the result. Each entry is the object the stream sends as ["offer", ...], and its bet_type goes into POST /v2/betslips/ unchanged. The reply is paged. limit defaults to 500 (max 5000). Pass the last entry’s "{event_id},{bet_type}" as after for the next page. A page shorter than limit is the last one. A reply can be about 4 seconds behind live prices. Register the event on the stream when you need each change as it happens. The quote for your betslip arrives as pmm on the socket, or you poll the betslip.

A first request with curl

Every response uses one envelope. Check status before reading data.

curl https://magicmarkets.com/v2/xrates/ -H "X-Api-Key: $MAGICMARKETS_API_KEY"

{"status": "ok", "data": [{"ccy": "USDT", "rate": ...}, {"ccy": "EUR", "rate": ...}]}

Concepts

Betslips, orders, offers, pmm, heartbeats, and the two-step flow.

WebSocket stream

The wire format and every message type.

Errors and rate limits

The error envelope, every code, and the budgets.

Start here

Concepts

Streaming

Guides

Tools

API reference

Endpoints

Updates

Path A: the CLI

Path B: REST and WebSocket

Events and offers with curl

A first request with curl

What to read next

Concepts

WebSocket stream

Errors and rate limits

​Path A: the CLI

​Path B: REST and WebSocket

​Events and offers with curl

​A first request with curl

​What to read next

Concepts

WebSocket stream

Errors and rate limits

Path A: the CLI

Path B: REST and WebSocket

Events and offers with curl

A first request with curl

What to read next