Getting started with an Agent

​

Step 1: Learn the concepts

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?

• 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

• An API key. Sign in at magicmarkets.com, go to Settings, then API, and click Add API Key. API access needs a minimum deposit of 10 USDT. See Authentication.
• Python 3. Check with python3 --version.

export MAGICMARKETS_API_KEY="your-key"

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.

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')

pip install requests
python3 first_look.py

​

Change it one step at a time

• “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.”

​

Step 3: Connect an Agent to live markets

https://magicmarkets.com/mcp

claude mcp add --transport http magicmarkets https://magicmarkets.com/mcp

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

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.

• “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

1. Read Safety first: idempotent orders, heartbeats, and how limits are honoured.
2. Follow Place an order in Python 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 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. It gives Claude the guide, the references and tested examples.