# MagicMarkets

> Documentation for MagicMarkets, the prediction market for serious sports trading. How the exchange works, how to trade, the API and tools, and how to partner with us.

- [Welcome](https://docs.magicmarkets.com/index.md): MagicMarkets is the prediction market for serious sports trading. Zero fees, deep liquidity, and no limits on winners. Start here.
- [What is MagicMarkets?](https://docs.magicmarkets.com/platform/what-is-magicmarkets.md): A peer-to-peer sports exchange where you trade outcomes against other traders or aggregated liquidity, at zero commission, priced in USDT.
- [Apps and tools](https://docs.magicmarkets.com/platform/apps-and-tools.md): The web app, the mobile app, the Thumper browser extension, and the API and CLI. One account across all of them.
- [How the exchange works](https://docs.magicmarkets.com/platform/how-the-exchange-works.md): Making and taking, buying and selling, matching, partial fills, and where the liquidity in the book comes from.
- [Prices and ticks](https://docs.magicmarkets.com/platform/prices-and-ticks.md): Decimal prices, cents and implied probability, and the fixed tick schedule that every valid price sits on.
- [Zero commission](https://docs.magicmarkets.com/platform/zero-commission.md): What MagicMarkets charges, which is nothing at the point of trade, and the network costs that do apply.
- [Sports and markets](https://docs.magicmarkets.com/platform/sports-and-markets.md): Which sports are priced, which markets each one carries, period markets, handicap lines, and where the depth is.
- [Settlement](https://docs.magicmarkets.com/platform/settlement.md): When markets settle, what source decides the outcome, how voids work, and what to do if you think a result is wrong.
- [Company and licence](https://docs.magicmarkets.com/platform/company-and-licence.md): Who operates MagicMarkets, under which licence, where it is not available, and where the binding legal documents live.
- [Glossary](https://docs.magicmarkets.com/platform/glossary.md): The terms used across MagicMarkets and these docs, in one place.
- [Create an account](https://docs.magicmarkets.com/traders/getting-started/create-account.md): What you need to sign up, what happens at each step, and what you can do before you deposit.
- [Make your first deposit](https://docs.magicmarkets.com/traders/getting-started/first-deposit.md): How to fund a MagicMarkets account and what to check before you send.
- [Place your first trade](https://docs.magicmarkets.com/traders/getting-started/first-trade.md): A walkthrough of a single trade, from picking a market to reading the result.
- [Placing and managing orders](https://docs.magicmarkets.com/traders/trading/placing-orders.md): Order tickets, market and limit orders, cancelling, and what happens to the matched part of an order.
- [Order statuses](https://docs.magicmarkets.com/traders/trading/order-statuses.md): What each order status means, and why filled is not settled.
- [Closing a position](https://docs.magicmarkets.com/traders/trading/closing-positions.md): Trade out, cashout, why closing needs free cash for a moment, and how smart credit gives it back.
- [Combos](https://docs.magicmarkets.com/traders/trading/combos.md): Combining two to ten legs into one position, how the price is built, and how a combo settles.
- [MagicMarkets Pro](https://docs.magicmarkets.com/traders/trading/pro-mode.md): Normal mode and MagicMarkets Pro compared, turning Pro on, building a space, reading the grid, and trading from the grid.
- [Deposits](https://docs.magicmarkets.com/traders/account/deposits.md): Funding an account: the USDT deposit address, networks, tags and memos, minimums, other deposit options, and deposit limits.
- [Withdrawals](https://docs.magicmarkets.com/traders/account/withdrawals.md): Taking USDT out: network fees, confirmation steps, cancelling, and the reasons a withdrawal gets blocked.
- [Identity verification](https://docs.magicmarkets.com/traders/account/verification.md): When MagicMarkets asks you to verify, what you need, how review works, and what happens if you decline.
- [Security](https://docs.magicmarkets.com/traders/account/security.md): Two-step verification, sign-in options, protecting your email, API key hygiene, what to do if an account is compromised, and how to report a vulnerability.
- [Transaction history](https://docs.magicmarkets.com/traders/account/history.md): Reading your deposit and withdrawal record, transaction states, and how your balance breaks down.
- [Referral dividend](https://docs.magicmarkets.com/traders/referral-dividend.md): How the monthly referral dividend pool works, what counts, when it pays, and what does not qualify.
- [Responsible trading](https://docs.magicmarkets.com/traders/responsible-trading.md): Cooling-off, self-exclusion, deposit limits, and where to get help.
- [Deposit not showing](https://docs.magicmarkets.com/traders/troubleshooting/deposit-not-showing.md): Work through this in order. Most missing deposits are a pending confirmation or a network or asset mismatch.
- [Withdrawal delayed](https://docs.magicmarkets.com/traders/troubleshooting/withdrawal-delayed.md): Where a withdrawal can be held up, and how to tell whether it is us, you, or the network.
- [Cannot log in](https://docs.magicmarkets.com/traders/troubleshooting/cannot-log-in.md): Sign-in code, two-step code and too-many-attempts problems, in the order worth trying.
- [Order did not fill](https://docs.magicmarkets.com/traders/troubleshooting/order-did-not-fill.md): Why an order sat unmatched, filled partly, or filled at a different price from the one you expected.
- [Support](https://docs.magicmarkets.com/traders/support.md): How to reach a human, what to have ready, and what support will never ask you for.
- [Developer overview](https://docs.magicmarkets.com/developers/overview.md): What the MagicMarkets API covers, where it lives, how the pieces fit, and the fastest way to start.
- [Quickstart](https://docs.magicmarkets.com/developers/quickstart.md): From nothing to a live order book in a few minutes, with the CLI or with curl.
- [Getting started with an Agent](https://docs.magicmarkets.com/developers/learn-with-ai.md): New to code or to the API? Use Claude, ChatGPT, Gemini or Cursor to learn the concepts, write a first read-only script, and read live markets, with prompts you can copy.
- [CLI](https://docs.magicmarkets.com/developers/tools/cli.md): magicmarkets: one open-source binary for the whole v2 API. Markets, offers, betslips, orders, heartbeats, position, and an offline spec reference.
- [Authentication](https://docs.magicmarkets.com/developers/authentication.md): API keys: creating one, sending it on REST and on the WebSocket, what a key can and cannot do, and key hygiene.
- [Concepts](https://docs.magicmarkets.com/developers/concepts.md): Betslips, orders, offers, pmm messages, heartbeats, events and the sync snapshot. Read this before you write code.
- [Sports and bet types](https://docs.magicmarkets.com/developers/sports-and-bet-types.md): Sport codes, the bet type grammar, handicap line scaling, period tokens, tennis, multirunner events, and validation.
- [Prices and ticks](https://docs.magicmarkets.com/developers/prices-and-ticks.md): The tick schedule, which way an off-tick order limit moves on a normal or lay betslip, combo prices, and why feed prices are never re-rounded.
- [Errors and rate limits](https://docs.magicmarkets.com/developers/errors-and-rate-limits.md): The error envelope, every REST and WebSocket error code, the rate limit budgets, and how to retry.
- [Safety](https://docs.magicmarkets.com/developers/safety.md): Idempotent placement, heartbeats as a dead-man's switch, off-tick limits, the read-only default of the local MCP server, and what the API cannot do.
- [WebSocket stream](https://docs.magicmarkets.com/developers/websocket-stream.md): The wire format, the initial sync, commands, every message type, offers, account updates, errors, and reconnect discipline.
- [Place an order](https://docs.magicmarkets.com/developers/guides/place-an-order.md): From an API key to a placed order, in eight steps, with runnable Python.
- [Maintain a live price book](https://docs.magicmarkets.com/developers/guides/price-book.md): Register the events you care about and keep a correct book from offer, remove_offer and clear_events.
- [Market making with heartbeat protection](https://docs.magicmarkets.com/developers/guides/market-making.md): Run an unattended quoting loop inside a heartbeat so a crash cannot leave exposure resting on the book.
- [Bulk close](https://docs.magicmarkets.com/developers/guides/bulk-close.md): Inspect open orders and close one, a set, or everything. Look before you close.
- [Stream many events](https://docs.magicmarkets.com/developers/guides/multi-event-streaming.md): Register many events on one socket, respect the cap, read fast, and recover from a silent drop.
- [MCP server](https://docs.magicmarkets.com/developers/tools/mcp.md): Let Claude and other agents read and trade MagicMarkets markets, through the local server in the CLI or the hosted server at magicmarkets.com/mcp.
- [Claude skill](https://docs.magicmarkets.com/developers/tools/claude-skill.md): A drop-in skill that teaches Claude the MagicMarkets API, with references and runnable Python examples.
- [Machine-readable docs](https://docs.magicmarkets.com/developers/tools/machine-readable-docs.md): llms.txt, llms-full.txt, the OpenAPI spec, Markdown versions of every page, and the docs MCP server. Point an agent at one URL.
- [API reference](https://docs.magicmarkets.com/developers/api-reference/introduction.md): How to read the endpoint pages, the base URL, authentication, the response envelope, and a note on the playground.
- [List betslips](https://docs.magicmarkets.com/developers/api-reference/betslips/list-betslips.md): Returns all open betslip IDs for the authenticated customer.
- [Create betslip](https://docs.magicmarkets.com/developers/api-reference/betslips/create-betslip.md): Create a new betslip. For normal/lay bets supply `sport`, `event_id`, and `bet_type`. For parlays supply a `legs` array instead.
- [Get betslip](https://docs.magicmarkets.com/developers/api-reference/betslips/get-betslip.md): Returns a single betslip with prices and stakes in USDT. `price_list` may be empty until quotes arrive, or when nothing is currently quoting the selection.
- [Close betslip](https://docs.magicmarkets.com/developers/api-reference/betslips/close-betslip.md): Close an open betslip. Its quotes stop, and it no longer counts toward the open-betslip cap.
- [Refresh betslip](https://docs.magicmarkets.com/developers/api-reference/betslips/refresh-betslip.md): Extend the betslip expiration timeout.
- [List orders](https://docs.magicmarkets.com/developers/api-reference/orders/list-orders.md): Returns a paginated list of orders for the authenticated customer.
- [Create order](https://docs.magicmarkets.com/developers/api-reference/orders/create-order.md): Places a new order on an existing betslip.
- [Order updates](https://docs.magicmarkets.com/developers/api-reference/orders/order-updates.md): Returns orders updated within the given time range. Both `updated_at_from` and `updated_at_to` must be **at least 60 seconds in the past**, and the window (`updated_at_to - updated_at_from`) must not exceed **70 minutes**. For longer syncs, page through successive 70-minute windows.
- [Get order](https://docs.magicmarkets.com/developers/api-reference/orders/get-order.md): Returns a single order by ID with all stakes in USDT.
- [Get order by UUID](https://docs.magicmarkets.com/developers/api-reference/orders/get-order-by-uuid.md): Retrieve an order using the `request_uuid` from order creation instead of the order ID. Available for several days after placement (until the order is purged upstream).
- [Close an order](https://docs.magicmarkets.com/developers/api-reference/orders/close-an-order.md): Close (cancel) a single open order. The order's lifecycle update is delivered on the WebSocket as an `["order", ...]` entry with `closed: true` and `close_reason: "cancelled"`. The response `data` field is always `null`.
- [Close multiple orders](https://docs.magicmarkets.com/developers/api-reference/orders/close-multiple-orders.md): Close multiple orders synchronously. Maximum 500 order IDs per request.
- [Close all open orders](https://docs.magicmarkets.com/developers/api-reference/orders/close-all-open-orders.md): Request cancellation of all open orders. Optionally filter by sport and/or event.
- [Calculate position](https://docs.magicmarkets.com/developers/api-reference/orders/calculate-position.md): Calculate profit/loss position based on filtered orders. Accepts the same query parameters as the list orders endpoint.
- [Account balance](https://docs.magicmarkets.com/developers/api-reference/account/account-balance.md): Returns the authenticated user's current balance, total stake on open bets, and smart credit. All values are `["USDT", amount]` tuples. The same three figures are pushed on the stream as the `balance` message; `open_stake` is positive.
- [List heartbeats](https://docs.magicmarkets.com/developers/api-reference/heartbeats/list-heartbeats.md): Returns all currently open heartbeats. **Note:** unlike other list endpoints (`/v2/orders/`, `/v2/betslips/`) which return a flat array under `data`, this endpoint wraps the array under `data.heartbeats` for historical reasons. Clients must special-case this shape.
- [Create heartbeat](https://docs.magicmarkets.com/developers/api-reference/heartbeats/create-heartbeat.md): Open a new heartbeat timer. If the timer expires before being refreshed or cancelled, every open order on the account is closed, including orders placed by other sessions or API keys; only orders created after the expiry instant are spared. Closing cancels the unfilled stake and withdraws unmatched…
- [Get heartbeat](https://docs.magicmarkets.com/developers/api-reference/heartbeats/get-heartbeat.md): Returns information about a single heartbeat.
- [Cancel heartbeat](https://docs.magicmarkets.com/developers/api-reference/heartbeats/cancel-heartbeat.md): Cancel an active heartbeat. Cancelling disarms the timer without closing any orders; only expiry triggers the order close-out. The response `data` field is always `null`.
- [Refresh heartbeat](https://docs.magicmarkets.com/developers/api-reference/heartbeats/refresh-heartbeat.md): Extend the heartbeat expiration timeout. A heartbeat that has already expired cannot be refreshed - its close-out has been triggered; open a new heartbeat instead.
- [Exchange rates](https://docs.magicmarkets.com/developers/api-reference/reference/exchange-rates.md): Returns current exchange rates.
- [Bet type info](https://docs.magicmarkets.com/developers/api-reference/reference/bet-type-info.md): Returns information about a bet type including the win/loss payout grid.
- [List events](https://docs.magicmarkets.com/developers/api-reference/market-data/list-events.md): Lists the events that currently have prices. Each entry is the object the stream sends as `["event", {...}]`.
- [List offers for an event](https://docs.magicmarkets.com/developers/api-reference/market-data/list-offers-for-an-event.md): Returns the stake available at each price, for each market on the named events. Each entry is the object the stream sends as `["offer", {...}]`.
- [Changelog](https://docs.magicmarkets.com/developers/changelog.md): Dated changes to the MagicMarkets API and the developer tools.
- [Partners](https://docs.magicmarkets.com/partners/overview.md): Partners for price comparison sites, platforms, affiliates and data directories that bring users to MagicMarkets or display MagicMarkets prices.
- [Who we work with](https://docs.magicmarkets.com/partners/who-we-work-with.md): Example partner types, what each one needs, and the licensing and disintermediation notes.
- [How attribution works](https://docs.magicmarkets.com/partners/how-attribution-works.md): One partner code, bound once at signup. What a partner code is, where it goes, and what it does not do.
- [Dividend](https://docs.magicmarkets.com/partners/dividend.md): How the partner dividend accrues, when it pays, and the rules around it.
- [Support](https://docs.magicmarkets.com/partners/support.md): What partner support covers, and where developers find answers in the docs.
- [Apply](https://docs.magicmarkets.com/partners/apply.md): Tell us what you run and who uses it. We usually reply within a few working days.

## OpenAPI Specs

- [magicmarkets-v2](/openapi/magicmarkets-v2.json)

## Optional

- [Open MagicMarkets](https://magicmarkets.com)
- [GitHub](https://github.com/magicmarkets)
- [OpenAPI spec](https://magicmarkets.com/v2/openapi.yaml)


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