Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/backtest-kit/ai-trading-mcp/llms.txt

Use this file to discover all available pages before exploring further.

open_position queues a market entry for a symbol in the traded universe. The engine — not the agent — owns every execution detail: take-profit level, stop-loss level, and position cost are all computed engine-side and cannot be overridden. The agent’s role is to supply the symbol, direction, and a permanent note explaining its reasoning.

​
Parameters

​
symbol
string
required
The Binance spot symbol to trade, e.g. BTCUSDT. Must be present in the CC_SYMBOL_LIST whitelist (13 pairs by default). Symbols outside the whitelist are rejected by the engine — no prompt engineering is involved.
​
position
"long" | "short"
required
Direction of the trade. "long" queues a market buy; "short" queues a market sell.
​
note
string
required
The agent’s reasoning or signal source for this entry. The note is recorded in the position immediately and echoed back verbatim in every subsequent get_status response for the entire life of the position. It also appears in the markdown audit dump under dump/mcp/.Best practices for the note:
  • Record the signal source precisely: Telegram channel ID, post timestamp, and a summary of the post content.
  • Acknowledge any caveats about source reliability (e.g., scam-channel markers, unverifiable P&L).
  • State the agent’s own confidence level and whether independent technical confirmation exists.

​
What Happens After the Call

When open_position is called, the engine runs its validation chain before queuing anything:
  1. Whitelist check — the symbol must be in CC_SYMBOL_LIST.
  2. Duplicate check — the symbol must have no active position and no pending entry signal.
  3. If valid — a market entry is queued with engine-computed TP, SL, and cost. The note is persisted immediately.
  4. If invalid — an error message is returned in the response envelope and surfaced to the agent as an isError tool result.

​
Common Rejection Reasons

ReasonEngine message
Symbol not in CC_SYMBOL_LISTSymbol is not live-enabled
Symbol already has an active positionDuplicate open rejected
Symbol already has a pending entry signalPending signal already exists

​
Execution by Mode

Paper mode — the engine simulates the fill at the current market price fetched via ccxt. No real order is placed. TP and SL brackets are tracked in memory and against the live price stream. Live mode — the spot broker adapter places a limit order with a poll-then-market-top-up guarantee: the order is polled up to 10 times at 10-second intervals; if it has not filled, the adapter cancels it (treating a cancel race as a fill) and places a market order for any remaining quantity. Once the entry is confirmed, an OCO (TP + stop-limit SL in a single freeze) protects the position. Idempotent recovery by clientOrderId = signalId prevents position doubling on engine revalidation.

​
The note Field

The note is the agent’s primary contribution to the audit trail. Because open_position has no size or leverage parameters, the note is the only agent-authored artifact attached to a trade. A well-written note makes it possible to reconstruct why a position was opened days or weeks later. Example note from a real session (translated): 
Paper trade at user's request. Basis — signal from Telegram feed -1002833393903,
2026-08-02 09:34 UTC ("Working BTC — short, sized for a possible add"), entry
~63 285.75. No own technical confirmation; the source shows signs of unreliability.

​
Example

// Agent calls open_position with:
{
  "symbol": "BTCUSDT",
  "position": "short",
  "note": "Signal from Telegram feed -1002833393903, 2026-08-02 09:34 UTC. Post: \"Working BTC — short, sized for a possible add\". No own technical confirmation; source shows signs of unreliability (100x cross, BingX referral code, 'DM for 500%' markers)."
}

// Response (success):
// short queued: 100 USD at market, TP/SL engine-owned
The engine confirms the queued entry. On the next get_status call the agent will see queued_entry populated for BTCUSDT, and once filled, an active_position with the note echoed back.
The note is permanent. Once open_position is accepted, the note is stored in the position record and will appear in every get_status response and every audit dump for the entire life of the trade. There is no way to edit or delete it after the call.
Position sizing is entirely engine-controlled. open_position intentionally has no size, quantity, or leverage parameters — the engine computes cost and risk levels from its own configuration. This is by design: the blast radius of any single agent decision is bounded by the engine, not by the prompt.

Build docs developers (and LLMs) love

Get started for freeTalk to us