CLI

magicmarkets is the MagicMarkets CLI (command line interface) for the v2 API, written in Go and released under the MIT licence. It is the quickest way to start with the API: install it, add your key, and run magicmarkets status. It streams live prices, quotes selections, places and manages orders, runs heartbeats, and inspects your position. The same binary is an MCP server. Source: github.com/magicmarkets/magicmarkets-cli

Install

git clone https://github.com/magicmarkets/magicmarkets-cli
cd magicmarkets-cli
make install          # installs `magicmarkets` into your Go bin directory

make build produces ./build/magicmarkets without installing, and make where prints where make install puts the binary. If magicmarkets is not found afterwards, add $(go env GOPATH)/bin to your PATH. You need Go 1.25.10 or later. There are no releases or prebuilt binaries yet, and go install against the GitHub URL does not work because the module path is not a URL.

Configure

The CLI reads its configuration from environment variables, then ./.env, then ~/.magicmarkets/.env, then ~/.env.

Variable	Default	Purpose
`MAGICMARKETS_API_KEY`	required	Your API key
`MAGICMARKETS_API_URL`	`https://magicmarkets.com/v2`	REST base URL
`MAGICMARKETS_WS_URL`	derived	WebSocket URL
`MAGICMARKETS_LANG`	`en`	`en`, `ko`, or `zh-hans`
`MAGICMARKETS_TIMEOUT`	`30s`	Request timeout
`MAGICMARKETS_ALLOW_TRADING`	unset	Enables trading tools in the MCP server only

Global flags: --json for machine-readable output, --verbose or -v, --api-key, --api-url, --ws-url.

export MAGICMARKETS_API_KEY=your-key
magicmarkets status

Commands

Account
Discovery
Trading
Risk
Reference

magicmarkets status              # key, base URL, version
magicmarkets balance
magicmarkets xrates
magicmarkets position --sport fb --event 2026-09-13,1001,2002   # one event; add --grid for the payoff grid

magicmarkets markets                          # events with live prices, 50 by default (--limit 0 for all)
magicmarkets markets --sport fb --in-play     # filter by sport, in-play only
magicmarkets markets --search arsenal --limit 10
magicmarkets offers fb 2026-09-13,1001,2002   # the book for one event
magicmarkets offers fb 2026-09-13,1001,2002 --market ah --depth 5
magicmarkets stream --register fb:2026-09-13,1001,2002 --type offer

magicmarkets betslip create fb 2026-09-13,1001,2002 for,h --wait 8s
magicmarkets betslip create ... --lay             # lay betslip: lay price, lower is better
magicmarkets betslip create --leg fb:...:for,h --leg basket:...:for,ml,a   # combo, 2 to 10 legs (betslip_type "parlay")
magicmarkets betslip get <id> | list | refresh <id>
magicmarkets order place --betslip <id> --price 2.02 --stake 5 --request-uuid "$(uuidgen)"
magicmarkets orders                               # or: order list
magicmarkets order get <id> | tracked <uuid> | updates
magicmarkets order close <id> | close-many <id> <id> | close-all
magicmarkets order close-all --sport fb --event 2026-09-13,1001,2002   # narrow to one event

magicmarkets heartbeat run --timeout 60      # refreshes until you stop it; Ctrl-C cancels it and leaves orders open
magicmarkets heartbeat create | list | get <id> | refresh <id> | cancel <id>

The api and ticks commands work offline, with no key. bet-type calls the API.

magicmarkets bet-type fb for,ah,h,-4         # explain a bet type (needs a key)
magicmarkets ticks 2.51                      # snap a price to the tick schedule; --lay for a lay betslip
magicmarkets api endpoints
magicmarkets api show /v2/orders/ post
magicmarkets api schema OrderResponse
magicmarkets api curl post /v2/betslips/
magicmarkets api search heartbeat
magicmarkets api spec

Safety features

Order placement takes --request-uuid, so a retry cannot double-place.
Order placement snaps an off-tick price before it sends it. Check the snapped price in the confirmation.
order place, order close-many and order close-all ask for confirmation unless you pass --yes. order close for a single order does not ask.
heartbeat run keeps a heartbeat alive while it runs. If the process or the machine dies, every open order on the account closes.
The client identifies itself as User-Agent: magicmarkets-cli/<version>.

JSON output

Every command accepts --json. Pipe it into jq or into your own tooling.

magicmarkets markets --sport fb --json | jq '.[] | {event_id, event_name, start_time}'

Contributing

The repository carries a contributing guide, a security policy, and a contract test that compares the hand-written types with the vendored OpenAPI spec in both directions. When a maintainer refreshes the spec with make update-spec, any field the API added, removed or renamed fails the tests. Issues and pull requests are welcome.

Start here

Concepts

Streaming

Guides

Tools

API reference

Endpoints

Updates

Install

Configure

Commands

Safety features

JSON output

Contributing

​Install

​Configure

​Commands

​Safety features

​JSON output

​Contributing

Install

Configure

Commands

Safety features

JSON output

Contributing