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

# Claude skill

> A drop-in skill that teaches Claude the MagicMarkets API, with references and runnable Python examples.

The `magicmarkets-magic-api` skill packages what Claude needs to build against the API: the working guide, the REST and streaming references, task-shaped recipes, and runnable examples. It tells Claude to fetch the live `llms-full.txt` and OpenAPI spec as the source of truth rather than trusting memory.

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

## Install

```bash theme={"dark"}
mkdir -p ~/.claude/skills
git clone https://github.com/magicmarkets/magic-api.git ~/.claude/skills/magicmarkets-magic-api
```

Claude Code loads the skill automatically. Mention MagicMarkets, betslips, orders or the price stream and it activates.

To update an existing install:

```bash theme={"dark"}
git -C ~/.claude/skills/magicmarkets-magic-api pull
```

If you cloned the skill before 29 September 2026, the old URL redirects, so `git pull` still works.

## What is inside

| Path | Contents |
| - | - |
| `SKILL.md` | The working guide: auth, REST market data, the trading flow, the wire format, ticks, errors, rate limits, common mistakes |
| `references/rest.md` | REST endpoints, including `GET /v2/events/` and `GET /v2/offers/`, betslip and order shapes, heartbeats, errors and limits |
| `references/streaming.md` | The full WebSocket protocol, including handshake errors and dropped connections |
| `references/recipes.md` | Task-shaped patterns: discovery, placing, a live book, market making, bulk close, multi-event streaming, a REST price snapshot |
| `examples/` | Runnable Python scripts |

## The examples

The examples read your key from `MAGIC_API_KEY`.

```bash theme={"dark"}
cd ~/.claude/skills/magicmarkets-magic-api/examples
pip install -r requirements.txt
export MAGIC_API_KEY="your-key"
python 01-discover.py
```

| Script | What it does |
| - | - |
| `01-discover.py` | List everything currently priced, via `GET /v2/events/` or the stream's sync snapshot |
| `02-price-book.py` | Maintain a correct live price book from `offer`, `remove_offer` and `clear_events` |
| `03-market-making.py` | The full betslip, quote, order flow under heartbeat protection |
| `04-bulk-close.py` | Inspect and bulk-close open orders, across every page of the order list |
| `05-rest-offers.py` | Read prices over REST with `GET /v2/offers/`, up to 20 events per call |
| `06-multi-stream.py` | Many events on one socket, with reconnect and re-registration |

<Warning>
  `03` and `04` are dry-run by default. They print what they would do and exit, and the dry run only reads. Pass `--live` to place or close for real, which commits real USDT. `04 --all --live` calls `close_all` with no filter, which closes every open order on the account.
</Warning>

The repository also has offline tests and read-only live tests, which check the skill against the published OpenAPI spec. See the README for how to run them.

## Skill and MCP server together

The skill teaches Claude the protocol. The [MCP server](/developers/tools/mcp) gives Claude tools to call it. Use both: the skill for building integrations, the MCP server for asking questions about live markets.


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