> ## 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.

# CLI

> magicmarkets: one open-source binary for the whole v2 API. Markets, offers, betslips, orders, heartbeats, position, and an offline spec reference.

`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](/developers/tools/mcp).

Source: [github.com/magicmarkets/magicmarkets-cli](https://github.com/magicmarkets/magicmarkets-cli)

## Install

```bash theme={"dark"}
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`.

```bash theme={"dark"}
export MAGICMARKETS_API_KEY=your-key
magicmarkets status
```

## Commands

<Tabs>
  <Tab title="Account">
    ```bash theme={"dark"}
    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
    ```
  </Tab>

  <Tab title="Discovery">
    ```bash theme={"dark"}
    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
    ```
  </Tab>

  <Tab title="Trading">
    ```bash theme={"dark"}
    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
    ```
  </Tab>

  <Tab title="Risk">
    ```bash theme={"dark"}
    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>
    ```
  </Tab>

  <Tab title="Reference">
    The `api` and `ticks` commands work offline, with no key. `bet-type` calls the API.

    ```bash theme={"dark"}
    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
    ```
  </Tab>
</Tabs>

## 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.

```bash theme={"dark"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.