Betfair Exchange API Documentation

AI-friendly, structured reference docs for the Betfair Exchange API, converted from the official Atlassian wiki.

Structure

docs/
├── guides/                   # Authentication, best practices
│   ├── authentication.md     # Login flows, sessions, Keep Alive
│   └── best-practices.md     # HTTP config, error handling, rate limits
└── api-reference/            # API reference (55 pages)
    ├── README.md             # Master index — start here
    ├── AGENT_GUIDE.md        # How AI agents should read these docs
    ├── betting/              # Betting API — 17 operations + types/enums/exceptions
    ├── accounts/             # Accounts API — 6 operations + types/enums/exceptions
    ├── vendor/               # Vendor Services API — 14 operations
    ├── login/                # Authentication flows
    ├── stream-api.md         # Exchange Stream API
    ├── navigation-data.md    # Navigation data endpoint
    ├── race-status-api.md    # Race Status API
    └── heartbeat-api.md      # Heartbeat API

Quick navigation

Section	Description
API Reference	Complete API reference — operations, types, enums, exceptions
Agent Guide	Retrieval order & conventions for AI/LLM consumption
Authentication	Login flows, session management, Keep Alive
Best Practices	HTTP config, error handling, rate limits

API families

Family	Ops	Directory
Betting	17	docs/api-reference/betting/
Accounts	6	docs/api-reference/accounts/
Vendor	14	docs/api-reference/vendor/
Stream	—	docs/api-reference/stream-api.md

Key operations

Operation	Family	Purpose
placeOrders	Betting	Place bets on a market
listMarketBook	Betting	Get live prices and market status
listMarketCatalogue	Betting	Get market metadata (names, runners, event info)
listCurrentOrders	Betting	Your unmatched/matched orders
listClearedOrders	Betting	Settled bet history & P&L
cancelOrders	Betting	Cancel unmatched bets
getAccountDetails	Accounts	Account info, discount rate, points
getAccountFunds	Accounts	Balance, exposure, commission
getAccountStatement	Accounts	Transaction history (90 days)

AI-first design

• Front matter on every page with source_page_id, source_version, source URL
• Relative links — fully traversable offline, no network needed
• Tables for parameters, types, enums, exceptions
• JSON-RPC examples in json code blocks
• Preserved Betfair casing — identifiers match wire format
• Operation-per-file — reduces retrieval noise for AI agents

Conventions

See AGENT_GUIDE.md for the full list. Key ones:

• Set<T>, List<T>, Map<K,V> describe API semantics, not language specifics
• Blank Required → optional; Yes in Required → mandatory
• All links relative, all times UTC, all money values as strings in JSON-RPC

How agents use these docs

Three ways, from simplest to most powerful:

1. Clone the repo

Any AI coding agent (Claude Code, VS Code Copilot, Cursor) can read the Markdown files directly. The betfair-docs skill teaches the agent the retrieval order and conventions.

2. GitHub Pages (URL-addressable)

Enable GitHub Pages on this repo (Settings → Pages → source: docs/). Then any agent with web access can fetch:

https://<user>.github.io/Betfair.docs/api-reference/betting/operations/placeOrders.md

3. MCP Server (queryable API)

The included MCP server lets any MCP-compatible agent query the docs semantically — find operations, get endpoint info, read full operation docs — without reading files manually.

VS Code Copilot — already configured via .vscode/mcp.json: the betfair-docs server starts automatically when you open the workspace.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "betfair-docs": {
      "command": "python3",
      "args": ["/path/to/Betfair.docs/scripts/mcp_server.py"]
    }
  }
}

Available tools:

Tool	What it does
search_operations("order")	Find operations by keyword
list_operations("betting")	List all ops in a family
get_operation("placeOrders")	Full doc with params, types, examples
get_endpoint("betting")	Endpoint URL, JSON-RPC prefix, headers

Available resources: betfair-docs://operations/{name}, betfair-docs://types/{family}/{name}, betfair-docs://index

Source & license

• API content (docs/api-reference/) — © The Sporting Exchange Limited (Betfair). Reproduced for reference from the public developer wiki.
• IDD XML files (scripts/idd/) — © Betfair, publicly available attachments.
• Tooling, guides, structure — MIT. See LICENSE for full terms.