AI Coding Agents

Docs for AI coding agents

Claude Code, Cursor, Codex and GitHub Copilot write working FxSocket code when they read the docs, and plausible-looking broken code when they guess. Everything on this page exists so your agent reads instead: a rules file for your project, every docs page as Markdown, the whole reference in one file, and a read-only MCP server for your live accounts.

1. Add the rules file to your project

A short AGENTS.md section covering what agents get wrong without it: broker-specific symbol names, checking retcode instead of the HTTP status, broker server time, and never retrying an order blindly. Codex, Cursor, GitHub Copilot, Windsurf and Zed read AGENTS.md from the project root. Claude Code reads CLAUDE.md, so import the same file there.

Append to AGENTS.md

curl -s https://fxsocket.com/docs/ai-agents/rules.md >> AGENTS.md

Claude Code

echo "@AGENTS.md" >> CLAUDE.md

What it adds, also served on its own at /docs/ai-agents/rules.md:

AGENTS.md

# FxSocket

This project uses FxSocket, a cloud API for MetaTrader 4 and MetaTrader 5. Every linked broker account runs in its own MT4 or MT5 terminal in FxSocket's cloud and is controlled over REST and WebSocket. Read the docs instead of guessing endpoints or field names:

- All docs in one file: https://fxsocket.com/llms-full.txt
- Any docs page as Markdown: append .md to its URL, e.g. https://fxsocket.com/docs/mt5/trading.md

## SDKs and keys

- Prefer the official SDKs over raw HTTP. Python: `pip install fxsocket` (`Client`, `AsyncClient`). Node.js / TypeScript: `npm install @fxsocket/sdk` (`FxSocket`). One interface covers MT4 and MT5.
- Both SDKs read the key from the `FXSOCKET_API_KEY` environment variable. Never hardcode an API key or commit one.
- `fxs_live_` keys can trade. `fxs_ro_` keys are read-only: GET endpoints only, and they can be limited to selected accounts. Use a read-only key for anything that only reads.

## URLs and auth

- Platform API: https://api.fxsocket.com/v1 (accounts, multi-account orders, wallet). OpenAPI spec: https://api.fxsocket.com/v1/schema
- Per-account terminal API: https://api.fxsocket.com/mt5/{account_id}/... or https://api.fxsocket.com/mt4/{account_id}/... where {account_id} is the UUID from GET /v1/accounts. Each account serves its own OpenAPI spec at .../api-doc/openapi.json (no key needed).
- Send the key in the `X-API-Key` header. Terminal routes do not accept `Authorization: Bearer`; /v1 and the MCP server do.
- WebSocket: wss://api.fxsocket.com/mt5/{account_id}/ws?api_key=... (the query parameter is the only auth WebSocket supports). One socket per account, topics prices, bars, account, positions, trades, terminal. Prefer it over polling REST.

## Before sending orders

- A new account reads `connecting` for 1 to 3 minutes. Wait for `connected` on GET /v1/accounts/{account_id} and `ready` on GET /status before trading.
- Symbol names are broker-specific (EURUSD, EURUSD.sd, EURUSDm). Get the exact name from GET /symbols; never assume the plain name.
- Read GET /SymbolInfo first: keep volume within volumeMin, volumeMax and volumeStep, and round prices to `digits`.
- Timestamps are broker server time even though they end in Z. Convert with GET /ServerTimezone: utc = serverTime - utcOffsetSeconds.

## Order results

- HTTP 200 from OrderSend, OrderModify or OrderClose only means the terminal answered. Check `success` and `retcode`: 10009 is done, 10008 is placed, anything else is a rejection (report `retcodeDescription`). 10025 on a modify means nothing changed because the values were already set.
- A 500 or 504 with an error envelope can still mean the order executed. Check GET /OpenedOrders before sending again; never retry an order blindly.
- To trade many accounts at once use POST /v1/orders and POST /v1/orders/close (at most 20 legs or accounts, snake_case fields, unknown fields are a 400). Send an `Idempotency-Key` header so a retry cannot trade twice.

## Errors

- 401 `MRPC_UNAUTHORIZED`: missing or wrong key. 404: unknown account_id or path.
- Other errors use `{"error", "message", "command_id"}`. A 5xx without that envelope means the terminal is restarting (for example right after a key rotation): retry with backoff. Trading routes can return 503 briefly after a terminal starts.
- /v1 answers 429 with a `Retry-After` header when rate limited. Wait that long.

## Safety

- Build and test against a demo account.
- Do not place, modify or close orders on a live account unless the user explicitly asks for it.

2. Give it the docs as Markdown

Every docs page has a Markdown twin: add .md to the URL, for example /docs/mt5/trading.md. Agents that send Accept: text/markdown get it from the normal URL.
The Copy page menu at the top of every docs page copies that Markdown, or opens the page in ChatGPT or Claude to ask about it.
/llms.txt is the index. /llms-full.txt is the whole reference in one file (MT5, MT4, platform API and MCP) for agents that should read everything up front. Cursor can also index it as a docs source for @Docs.

Markdown from the normal URL

curl -H "Accept: text/markdown" https://fxsocket.com/docs/mt5/trading

3. Generate clients from OpenAPI

For exact field names and generated types: the platform API spec at https://api.fxsocket.com/v1/schema, and each account’s own spec at https://api.fxsocket.com/mt5/{account_id}/api-doc/openapi.json (or /mt4/). Neither needs a key.

4. Let it see your accounts

The docs tell an agent how the API works. The MCP server shows it your actual accounts: which symbols your broker lists and how they are spelled, what is open, recent trades and prices. It is read-only, so an agent can explore while it builds without being able to trade.

Claude Code

claude mcp add --transport http fxsocket https://mcp.fxsocket.com/mcp \
  --header "X-API-Key: fxs_ro_xxx"

Keep it on a short leash

The rules tell the agent to build against a demo account and never to trade a live account unless you ask. Give it a read-only fxs_ro_ key from the API Key page unless the code it writes has to trade: a read-only key cannot place an order however hard the agent tries.

Try it

Paste this into your agent to check it is set up:

Prompt

Read https://fxsocket.com/llms-full.txt first. Then write a Python script with the fxsocket SDK that lists my accounts and prints balance and equity for each one. Read the API key from the FXSOCKET_API_KEY environment variable. Do not place any orders.

Get Your API Key