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.

close_position queues a market close for an active position on a symbol. It is the agent’s tool for acting on new signal information — a close/fix post in the Telegram feed, an adverse move, or a reached loss limit. Take-profit and stop-loss levels are managed by the engine automatically; close_position is for agent-initiated, signal-driven exits.

​
Parameters

​
symbol
string
required
The Binance spot symbol whose position should be closed, e.g. BTCUSDT. The symbol must currently hold an active position. If there is nothing to close, the call fails immediately.
​
note
string
required
The agent’s reason for closing the position. Recorded in the close event and persisted in the audit dump under dump/report/. Good notes include the signal source (Telegram post timestamp and content), whether it was a TP/SL hit or a manual decision, and any relevant market context.

​
What Happens After the Call

  1. Validation — the engine checks that the symbol has an active position to close.
  2. If valid — a market close is queued. The engine will execute it on the next cycle.
  3. If invalid — the call returns an error immediately, surfaced to the agent as an isError tool result with the message nothing to close.

​
Execution by Mode

Paper mode — the engine simulates a market fill at the current price. PnL is calculated by comparing the close price against the recorded entry price. The position disappears from get_status on the next call. Live mode — the spot broker adapter uses a commit_cancel methodology designed to handle every real-world failure mode:
  1. Cancel-sweep — all open orders for the symbol (TP, SL, any partials) are cancelled in up to 10 rounds.
  2. Book verification — a second loop confirms the order book is empty before selling. Selling over a live sell order would cause InsufficientFunds; the verification step prevents this.
  3. Sell entire free balance — the adapter sells the full free balance of the coin, sweeping any orphan tranches. Dust below minNotional is treated as a confirmed close.
The original engine error always reaches the agent typed — network hiccups (NetworkError → OrderTransientError, bounded retry) are distinguished from exchange verdicts (ExchangeError → OrderRejectedError, permanent).

​
After the Close

Once the close executes:
  • The position disappears from get_status for that symbol.
  • The closed trade is appended to dump/report/live.jsonl and dump/report/performance.jsonl.
  • The symbol returns to a clean state — a new open_position call for the same symbol becomes valid again.

​
The note Field

The close note completes the audit trail for a trade. It is stored alongside the close event in the report files and should be specific enough to reconstruct the decision independently. Good close note content:
  • The Telegram post that triggered the close (timestamp + content summary)
  • Whether it was a target reached, a fix/close instruction from the feed, or a risk-management decision
  • Any discrepancy between the expected and actual outcome

​
Example

// Agent calls close_position with:
{
  "symbol": "BTCUSDT",
  "note": "Closing short: Telegram feed -1002833393903 shows fix/close signal at 2026-08-02 14:22 UTC. Post indicates author is taking profit. Taking profit on short position opened at ~63 285."
}

// Response (success):
// close queued for BTCUSDT
On the next get_status call the agent will see queued_close populated for BTCUSDT. Once executed, the position will be gone and the realized PnL will be recorded in the report files.
TP and SL levels are managed entirely by the engine. close_position is for manual, agent-initiated closes based on new information from the Telegram feed or other signal sources. If the engine’s TP or SL is hit, the position closes automatically without any close_position call.
After calling close_position, call get_status on the next tick to confirm the position has closed and to read the final unrealized PnL before it disappears. Once closed, the PnL figure is only available in dump/report/performance.jsonl.

Build docs developers (and LLMs) love

Get started for freeTalk to us