Skip to main content

AI-Assisted Development

If you're using an AI coding assistant (Claude Code, Cursor, GitHub Copilot, Continue, Cline, Aider) to build against the CrossTrade API, this page is your starting point.

The short version, today:

  1. Best path: install the Python or TypeScript SDK so generated code is typed and the AI gets autocomplete.
  2. Second best: paste llms-full.txt (or its URL) into your chat so the AI has the entire API surface in one fetch.
  3. At minimum: drop the CLAUDE.md template into your project root so the AI knows the path conventions.

If your AI gets endpoints wrong (/api/order instead of /v1/api/accounts/{account}/orders/place), it's because nothing in the conversation taught it our path scheme. Each tool below fixes that in a different way.

A native MCP server is in development; see Coming soon.

Coming soon: MCP server​

We're building a Model Context Protocol (MCP) server that will let your AI client call the CrossTrade API directly, without copy-paste. Once shipped it will load the OpenAPI spec at startup and expose every public endpoint as a typed tool, so an interaction like this just works:

You:  Flatten everything in Sim101 and tell me what's left.
AI:   [calls flatten_everything]
       [calls list_positions account=Sim101]
       Done. Sim101 is flat. Last close: ES 03-26 short -2 @ 4521.25.

Three flavors are planned:

  • xtrade-mcp (PyPI): a local stdio MCP server for Claude Desktop, Claude Code, Cursor, Continue, Cline, and other IDE/desktop clients.
  • Hosted MCP at mcp.crosstrade.io: an HTTP+SSE MCP server with OAuth, for web AI clients (claude.ai, ChatGPT, Cloudflare AI Gateway). Will publish the standard /.well-known/mcp/server-card.json discovery document.
  • @crosstrade/webmcp (npm): a browser SDK that exposes trading tools through the WebMCP navigator.modelContext API for in-page agents.

Until those land, the rest of this page is what's available right now, and it's enough to get most AI workflows productive.

Python SDK​

pip install xtrade
from xtrade import XTradeClient

client = XTradeClient()  # reads XTRADE_TOKEN env var

accounts = client.list_accounts()
client.place_order("Sim101", instrument="ES 03-26", action="Buy", quantity=1)

client.cancel_and_bracket(
    "Sim101",
    instrument="ES 03-26",
    action="Sell",
    quantity=1,
    take_profit=4550.0,
    stop_loss=4450.0,
)

bars = client.get_bars(instrument="ES 03-26", period_type="minute", period=5, limit=300)

Async flavor:

from xtrade import AsyncXTradeClient

async with AsyncXTradeClient() as client:
    positions = await client.get_all_positions()

Typed errors:

from xtrade import XTradeAuthError, XTradeAddonOfflineError, XTradeNotFoundError, XTradeError

try:
    client.place_order(...)
except XTradeAddonOfflineError:
    # NT8 isn't running or the add-on disconnected
    ...
except XTradeAuthError:
    # 401, bad token or non-Pro account
    ...

Source on GitHub →

TypeScript SDK​

npm install @crosstrade/sdk
import { XTradeClient } from '@crosstrade/sdk';

const client = new XTradeClient();  // reads XTRADE_TOKEN env var

const accounts = await client.listAccounts();

await client.placeOrder('Sim101', {
  instrument: 'ES 03-26',
  action: 'Buy',
  quantity: 1,
});

await client.cancelAndBracket('Sim101', {
  instrument: 'ES 03-26',
  action: 'Sell',
  quantity: 1,
  takeProfit: 4550,
  stopLoss: 4450,
});

Works in Node 18+, Bun, Deno, and modern browsers (CORS permitting).

Source on GitHub →

OpenAPI spec​

Machine-readable surface, fed live from the deployed API:

Drop the URL into Postman, Insomnia, or any OpenAPI-aware editor for a typed client and a request explorer. Use openapi-generator if you need an SDK in a language we don't ship one for.

Endpoint catalog​

A flatter alternative to the full OpenAPI spec, one row per endpoint with method, path, parameters, and the underlying RPC name. Useful when you just want the AI to know "what endpoints exist":

GET https://app.crosstrade.io/v1/api/_endpoints

This is also the URL that the smart 404 (see below) points AI tools at when they guess wrong.

llms.txt and llms-full.txt​

The llms.txt convention is an emerging standard for AI-readable single-file documentation. Both files are served live:

The full version contains every endpoint, parameters, body shapes, and runnable examples in a single Markdown file you can paste (or link) into any AI chat. Until the MCP server ships, this is the closest thing to giving an AI the entire API surface in one shot.

Smart 404 responses​

When an AI tool guesses a wrong endpoint (/api/order, /v1/api/orders, /api/v1/place), the API doesn't just return an empty 404. It returns:

{
  "success": false,
  "error": "unknown_endpoint",
  "detail": "No route matches POST /api/order.",
  "request": {
    "method": "POST",
    "path": "/api/order"
  },
  "did_you_mean": [
    "POST /v1/api/accounts/{account}/orders/place",
    "POST /v1/api/accounts/{account}/orders/flatplace",
    "POST /v1/api/orders/cancelall"
  ],
  "discovery": {
    "endpoints_catalog": "https://app.crosstrade.io/v1/api/_endpoints",
    "openapi_json": "https://app.crosstrade.io/v1/api/openapi.json",
    "llms_full_txt": "https://app.crosstrade.io/v1/api/llms-full.txt",
    "documentation": "https://crosstrade.io/docs/api/overview"
  }
}

Most AI agents read error response bodies and self-correct on the next call. You usually don't need to do anything, but if you're debugging, the did_you_mean array is the fastest way to find the right path.

Drop-in rules template​

Dropping a rules file in your project root teaches the AI the conventions before it generates any code. Three flavors:

  • CLAUDE.md for Claude Code, Cursor (when reading CLAUDE.md), Aider, Continue.
  • AGENTS.md universal, picked up by most AGENTS-aware tools.
  • .cursorrules Cursor-specific (rename to .cursorrules).

Each one captures the must-know rules: base path, auth, response shape, instrument formats, common gotchas (e.g. POST/PUT bodies are JSON, NT8 must be connected, the order ID path param is {id} but the body field for change/replace is orderId).

Pasting context into a chat​

If you just want to drop a single URL into a chat to give the AI the whole API surface:

https://app.crosstrade.io/v1/api/llms-full.txt

That's the everything-file. Every public endpoint, every parameter, every example, in one fetchable document.

Choosing the right approach​

ToolStatusSetupPowerMaintenance
MCP serverComing soon(will be) one-time client configHighest, AI calls the API directlyAuto-syncs with live spec
Typed SDKAvailablepip install / npm installHigh, typed methods, error mappingTracks breaking changes
OpenAPI specAvailablePaste URL into editor / generatorMedium, typed client in any languageAuto-syncs with live spec
llms-full.txtAvailablePaste URL into chatMedium, AI gets full surface, no integrationAuto-syncs with live spec
Drop-in rulesAvailableSave file in project rootLow, prevents path mistakesUpdate if conventions change

Use as many as fit your workflow. They're complementary: the SDK makes generated code typed, the rules file keeps the AI on-convention when it's writing free-form code, and llms-full.txt gives chat-only contexts the entire API surface in one paste.

When something doesn't work​

  • AI hits 401: XTRADE_TOKEN missing or wrong, or the user doesn't have a Pro subscription. Token is at app.crosstrade.io/user/my-account.
  • AI hits 408: NinjaTrader isn't running with the add-on connected. The user needs to fix that. No amount of retrying will help.
  • AI keeps inventing endpoints: the rules file isn't being read. Verify it's in the project root, not a subdirectory. Some tools cache, restart the client. If it keeps happening, also paste llms-full.txt into the conversation.
  • AI's request body doesn't match what the endpoint expects: point it at /v1/api/openapi.json, or have it re-read the endpoint's section in llms-full.txt. The spec is the source of truth.

For anything else, ping Discord.