> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magicmarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> From nothing to a live order book in a few minutes, with the CLI or with curl.
The `magicmarkets` [CLI](/developers/tools/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.
Sign in at [magicmarkets.com](https://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](/developers/authentication).
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.
```bash theme={"dark"}
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.
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](https://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`.
```bash theme={"dark"}
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 # the book for one event, both sides; copy an id from markets
```
To let an agent read the same book:
```bash theme={"dark"}
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](/developers/tools/cli) and [MCP server](/developers/tools/mcp).
## 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.
```
1. GET /v2/balance/ verify the key over REST first
2. connect wss://.../v2/stream collect ["event", ...] until ["sync", ...]
3. ["register_event", sport, event_id] -> ["offer", ...] snapshot
4. pick an offer its sport, event_id and bet_type are all you need
5. POST /v2/betslips/ -> betslip_id
6. wait for ["pmm", ...] on the socket the quote for your betslip
7. POST /v2/orders/ -> order_id, with a request_uuid
8. watch ["order", ...] until done or failed
```
The [Place an order](/developers/guides/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:
```bash theme={"dark"}
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"
```
```json theme={"dark"}
{"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:
```bash theme={"dark"}
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`.
```bash theme={"dark"}
curl https://magicmarkets.com/v2/xrates/ -H "X-Api-Key: $MAGICMARKETS_API_KEY"
```
```json theme={"dark"}
{"status": "ok", "data": [{"ccy": "USDT", "rate": ...}, {"ccy": "EUR", "rate": ...}]}
```
## What to read next
Betslips, orders, offers, pmm, heartbeats, and the two-step flow.
The wire format and every message type.
The error envelope, every code, and the budgets.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.