MagicMarkets

magicmarkets-cli

A command-line interface for the Magic Markets v2 API — stream live sports prices, quote selections, place and manage orders, and inspect your position. The same API is also available as MCP tools: the easiest path is the hosted, OAuth-authenticated endpoint at https://magicmarkets.com/mcp — no install required. This binary also serves the same tools locally, over stdio (a client launches magicmarkets mcp as a subprocess) or the streamable HTTP transport on localhost.

Single static binary, authenticated with one API key. No request signing, no private keys.

magicmarkets markets --sport fb                     # find events with live prices

magicmarkets offers fb 2026-06-15,1001,2002 # list priced bet types magicmarkets betslip create fb 2026-06-15,1001,2002 for,h --wait 5s magicmarkets order place --betslip bs-123 --price 2.10 --stake 50

• [Setup](#setup) — install, authenticate, first commands
• [Using it](#using-it) — the bet flow, command reference, MCP, prices, errors
• [Development](#development) — layout, code generation, conventions, contributing

---

Setup

1. Install

From a clone:

git clone https://github.com/magicmarkets/magicmarkets-cli

cd magicmarkets-cli make install # installs magicmarkets into your Go bin directory

make where prints exactly where that landed. If magicmarkets is not found afterwards, that directory is not on your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"      # add to ~/.zshrc or ~/.bashrc

Prefer not to install? make build produces ./build/magicmarkets and leaves your PATH alone.

go install directly

Note the /cmd/magicmarkets path — installing the module root would build a binary called magicmarkets-cli:

go install ./cmd/magicmarkets

The Go module path is magicmarkets-cli, not a GitHub URL, so go install github.com/…/magicmarkets-cli@latest will not work. Cloning and make install is the supported path.

2. Add your API key

Create a key at magicmarkets.com under Settings → API. It is shown once at creation, so store it immediately.

Put it in ~/.magicmarkets/.env so it works from any directory:

mkdir -p ~/.magicmarkets

echo 'MAGICMARKETS_API_KEY=your-key-here' > ~/.magicmarkets/.env chmod 600 ~/.magicmarkets/.env

An env var or a project-local .env works too — cp env.example .env and fill it in.

3. Verify

$ magicmarkets status

version v1.0.0 api url https://magicmarkets.com/v2 ws url wss://magicmarkets.com/v2/stream lang en api key ***********1234 env files [/Users/you/.magicmarkets/.env] authenticated yes

Always check this before opening a stream — the WebSocket rejects a bad key at the handshake without a useful error.

That's the whole setup. Everything below is optional.

Try it

magicmarkets balance                          # money position

magicmarkets xrates # exchange rates to USDT magicmarkets markets --sport fb --limit 5 # events that currently have prices magicmarkets offers fb --depth 2 # priced bet types on one event magicmarkets orders --open # your open orders magicmarkets ticks 2.345 # where a price lands on the tick schedule magicmarkets api endpoints # every endpoint (no key, no network)

Add --json to any command to pipe it into jq.

Configuration

Resolved in this order, first match winning:

Global flags: --json, --verbose/-v, --api-key, --api-url, --ws-url.

--api-url re-derives the stream endpoint from it (matching MAGICMARKETS_WS_URL's own derivation), unless MAGICMARKETS_WS_URL or --ws-url pins it explicitly — so --api-url https://staging... doesn't leave stream reading production prices while every other command reaches staging.

---

Using it

The two-step bet flow

Placing a bet always takes two steps:

1. A betslip registers interest in one selection and receives a live quote. It costs nothing and commits nothing.
2. An order commits a stake against that quote.

Betslips are short-lived and carry no price when created — the quote arrives asynchronously, over the WebSocket as a pmm message or by polling. Hence --wait:

# 1. find an event that has prices

$ magicmarkets markets --sport fb --limit 5 SPORT EVENT ID EVENT COMPETITION STATUS START

---

fb 2026-06-15,1001,2002 Arsenal v Chelsea England Premier League pre_event 2026-06-15 16:00:00

2. read a bet_type straight off the feed

$ magicmarkets offers fb 2026-06-15,1001,2002 --depth 2 BET TYPE MARKET IR PRICES (stake @ price) TOTAL

---

for,h 1x2 - 150.00@2.10 80.00@2.08 230.00 for,ah,h,-4 ah - 200.00@1.95 120.00@1.94 320.00

3. quote it, waiting for the price to land

$ magicmarkets betslip create fb 2026-06-15,1001,2002 for,h --wait 5s betslip id bs-abc123 bet type for,h description Home expires 2026-06-15 15:42:10 (28s) total available 230.00 USDT

Prices: PRICE MIN MAX

---

2.10 5.00 150.00 2.08 - 80.00

4. commit a stake (asks for confirmation)

$ magicmarkets order place --betslip bs-abc123 --price 2.10 --stake 50

Never construct a `bet_type` by hand. Copy it verbatim from magicmarkets offers or the stream — it encodes the market, handicap, outcome and direction in one string.

Command reference

Account

Discovery

markets and offers are plain REST calls (GET /v2/events/, GET /v2/offers/). Sport, competition, in-play status, start window, market type, bet type and minimum liquidity are filtered by the API; --search is matched locally. REST offers can trail the live market by a few seconds — use stream --register when every tick matters.

magicmarkets markets --sport fb,tennis --limit 20

magicmarkets markets --sport fb --from 2026-06-15 --to 2026-06-16 magicmarkets markets --search arsenal magicmarkets markets --in-play magicmarkets offers fb 2026-06-15,1001,2002 --market ah --depth 3 magicmarkets offers fb 2026-06-15,1001,2002 2026-06-15,1003,2004 --min-liquidity 500 magicmarkets stream --register fb:2026-06-15,1001,2002 magicmarkets stream --type order,bet # only order activity

Trading

Lay bets and parlays:

# lay (against) a selection

magicmarkets betslip create --lay fb 2026-06-15,1001,2002 for,over,2.5

a 2-leg accumulator

magicmarkets betslip create \ --leg fb:2026-06-15,1001,2002:for,h \ --leg fb:2026-06-16,1003,2004:for,over,2.5 --wait 5s

Risk

A heartbeat is a dead-man's switch: if it is not refreshed before it expires, every open order is closed automatically. Run one alongside an automated strategy so a crash cannot leave orders live.

$ magicmarkets heartbeat run --timeout 60

heartbeat hb-xyz created, expires 2026-06-15 15:43:10; refreshing every 20s press Ctrl-C to cancel it and leave orders open

On Ctrl-C the heartbeat is cancelled cleanly, leaving orders open. If the process dies, the switch fires.

MCP

Reference

| magicmarkets api schema [name] | Componen