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

# Getting started with an Agent

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

You do not need to be a programmer to start. An AI assistant can explain how the exchange works, write a script for you, and read live prices. This page takes you there in three steps. Each step adds one thing, and nothing on this page places an order.

<Warning>
  **Keep your API key out of every chat.** A key can trade your balance. Never paste it into a prompt, a screenshot or a shared file. Put it in an environment variable, as shown in step 2. If a key leaks, revoke it at once on [magicmarkets.com](https://magicmarkets.com) under **Settings**, then **API**.
</Warning>

AI assistants make mistakes. Check what they tell you against these docs, and read any code before you run it. You are responsible for every order your account places.

## Step 1: Learn the concepts

You need no key and no install. Give the assistant the full API reference, then ask questions.

The reference is one file: `https://magicmarkets.com/llms-full.txt`. Paste this into Claude, ChatGPT, Gemini or any other assistant:

```text theme={"dark"}
Read https://magicmarkets.com/llms-full.txt. It is the full reference for the
MagicMarkets API. Answer only from that file, and tell me when the file does
not cover something. I am new to programming and to sports exchanges, so
explain in plain language.

My first question: what are the steps to go from "I want to trade this match"
to an order, and what does each step do?
```

If the assistant cannot open links, download the file and attach it. Every page on this site also has a menu at the top to copy the page, or to open it in ChatGPT or Claude.

Questions to ask next:

* What is a betslip, and why do I need one before an order?
* What does a decimal price of 2.50 mean? How does it relate to a price in cents?
* What is the difference between a `for` and an `against` bet type?
* What is the tick schedule, and what happens if my price is not on it?
* What happens to my open orders if my program crashes?
* Why should every order carry a `request_uuid`?

## Step 2: Write a first script

This script only reads. It checks your key, lists upcoming football matches, and shows the best price for each outcome of one match.

You need:

* An API key. Sign in at [magicmarkets.com](https://magicmarkets.com), go to **Settings**, then **API**, and click **Add API Key**. API access needs a minimum deposit of 10 USDT. See [Authentication](/developers/authentication).
* Python 3. Check with `python3 --version`.

<Steps>
  <Step title="Put the key in an environment variable">
    Run this in the terminal where you will run the script. Replace `your-key` with your key.

    <CodeGroup>
      ```bash macOS and Linux theme={"dark"}
      export MAGICMARKETS_API_KEY="your-key"
      ```

      ```powershell Windows theme={"dark"}
      ```
    </CodeGroup>

    The variable lasts until you close that terminal.
  </Step>

  <Step title="Ask the assistant for the script">
    ```text theme={"dark"}
    Using https://magicmarkets.com/llms-full.txt as the only reference, write a
    short Python script for a beginner. Rules:
    - It only reads data. It never creates a betslip or places an order.
    - It reads my API key from the MAGICMARKETS_API_KEY environment variable.
      Never put the key in the code.
    - It checks the key with GET /v2/balance/.
    - It lists the next five football matches that have live prices.
    - For the first match, it prints the best price for home, draw and away.
    Explain each line with a comment.
    ```

    Or start from this version, which we tested against the live API:

    ```python first_look.py theme={"dark"}
    import os
    from datetime import datetime, timezone

    import requests

    API = "https://magicmarkets.com/v2"
    HEADERS = {"X-Api-Key": os.environ["MAGICMARKETS_API_KEY"]}

    # 1. Check the key by reading your balance
    balance = requests.get(f"{API}/balance/", headers=HEADERS).json()
    print("Balance:", balance["data"])

    # 2. Upcoming football matches with live prices
    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    events = requests.get(f"{API}/events/", headers=HEADERS, params={
        "sport": "fb", "start_time_from": now, "limit": 50}).json()["data"]
    matches = [e for e in events if e["event_type"] == "normal"][:5]
    for e in matches:
        print(e["start_time"], e["event_name"])

    # 3. The best price for home (h), draw (d) and away (a) in the first match
    first = matches[0]
    offers = requests.get(f"{API}/offers/", headers=HEADERS, params={
        "sport": "fb", "event_id": first["event_id"]}).json()["data"]
    print("\n" + first["event_name"])
    for o in offers:
        if o["bet_type"] in ("for,h", "for,d", "for,a") and o["price_list"]:
            best = o["price_list"][0]["effective"]
            print(f'{o["bet_type"]}: {best["price"]} for up to {best["max"][1]:.2f} USDT')
    ```
  </Step>

  <Step title="Run it">
    ```bash theme={"dark"}
    pip install requests
    python3 first_look.py
    ```

    You see your balance, five matches with their start times, then three lines such as `for,h: 1.64 for up to 2.13 USDT`. A price of 1.64 on `for,h` means a 1 USDT position on the home team returns 1.64 USDT if the home team wins.
  </Step>
</Steps>

### Change it one step at a time

Ask for one change, run the script, then ask for the next. Good next prompts:

* "Show only matches that start in the next 24 hours, sorted by start time."
* "Next to each price, print the price in cents: 100 divided by the decimal price."
* "Print home, draw and away for all five matches as one table."
* "Save the prices to a CSV file every 60 seconds for one hour. Stay well inside the rate limits in llms-full.txt."

When something fails, paste the full error message back to the assistant. Remove your key from anything you paste.

| You see | What it means |
| - | - |
| `KeyError: 'MAGICMARKETS_API_KEY'` | The variable is not set in this terminal. Repeat the first step in the same window |
| `401` with `auth_error` | The server did not accept a key. Check that you copied the whole key |
| `ModuleNotFoundError: No module named 'requests'` | Run `pip install requests` |
| `IndexError: list index out of range` | No match had live prices at that moment. Try again later, or change `fb` to another sport |
| `429` with `throttled` | Too many requests. Wait for the number of seconds in `retry_after`. See [Errors and rate limits](/developers/errors-and-rate-limits) |

## Step 3: Connect an Agent to live markets

The Model Context Protocol (MCP) lets an assistant call MagicMarkets directly, so you can ask about live markets in plain language. You choose between two servers:

| | Hosted server | Local server |
| - | - | - |
| Install | Nothing | The [CLI](/developers/tools/cli), which needs a Go toolchain |
| Works with | Claude (web, desktop and Claude Code) and other MCP clients | Claude Code, Claude Desktop, Cursor and other MCP clients |
| Sign-in | Your MagicMarkets account, or an API key | An API key |
| Trading tools | **Always on.** An assistant can place orders | Off until you set `MAGICMARKETS_ALLOW_TRADING=1` |

For learning, the local server is the safer choice, because it cannot trade unless you switch trading on. The hosted server is quicker to set up.

<Tabs>
  <Tab title="Claude, hosted">
    In Claude on the web or desktop, open **Settings**, then **Connectors**, and add a custom connector with this URL:

    ```text theme={"dark"}
    https://magicmarkets.com/mcp
    ```

    Claude asks you to sign in with your MagicMarkets account.

    In Claude Code:

    ```bash theme={"dark"}
    claude mcp add --transport http magicmarkets https://magicmarkets.com/mcp
    ```

    <Warning>
      The hosted server gives the assistant trading tools from the start, and `place_order` spends real money. Set your client to ask before each tool call, and approve only tools that read.
    </Warning>
  </Tab>

  <Tab title="Local, read-only">
    Install the CLI, then add its server to Claude Code:

    ```bash theme={"dark"}
    git clone https://github.com/magicmarkets/magicmarkets-cli
    cd magicmarkets-cli && make install
    claude mcp add magicmarkets -e MAGICMARKETS_API_KEY="$MAGICMARKETS_API_KEY" -- magicmarkets mcp
    ```

    The command reads the key from the variable you set in step 2, so the key does not appear in your shell history. For Claude Desktop, Cursor and other clients, see [MCP server](/developers/tools/mcp).
  </Tab>
</Tabs>

Start each session with this prompt:

```text theme={"dark"}
Use the MagicMarkets tools in read-only mode. Do not create betslips, place
orders, close orders or start heartbeats. If a question needs one of those,
stop and tell me what you would do.
```

Then ask:

* "List the football matches that start in the next three hours, with the best home, draw and away prices."
* "Show the full book for the first match, both sides, and explain what the depth tells me."
* "What is my balance, and how much is in open stakes?"
* "Snap a price of 2.345 to the tick schedule and explain the result."
* "Check this bet type for me and explain when it wins: `for,ah,h,-2`."

## When you are ready to trade

There is no separate test environment. Every order is real and uses real USDT, so move slowly:

1. Read [Safety](/developers/safety) first: idempotent orders, heartbeats, and how limits are honoured.
2. Follow [Place an order in Python](/developers/guides/place-an-order) with the smallest amount the market accepts.
3. Prefer tools that ask before they commit. The CLI asks for confirmation before each order, and the [Claude skill](/developers/tools/claude-skill) examples run as a dry run unless you add `--live`.
4. Ask the assistant to explain any code that places or closes orders before you run it.

## Tips for better answers

* **Name the source.** "Using llms-full.txt" keeps the assistant on the current API and away from guesses.
* **Say what it must not do.** "Read only" and "never place an order" are worth repeating in every new chat.
* **Ask for one change at a time,** and run the code between changes.
* **Ask it to explain.** "Explain each line" teaches you the API as you go.
* **For Claude Code,** install the [Claude skill](/developers/tools/claude-skill). It gives Claude the guide, the references and tested examples.


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