mcp-binance-futures

Instructions

Implementation Reference

• src/mcp_binance_futures/server.py:575-604 (handler)

  The main cancel_order tool handler function decorated with @mcp.tool. Cancels a single open order by orderId or clientOrderId. Handles both regular orders and algo (conditional) orders via the is_algo parameter. Uses delete_signed API calls to Binance endpoints.

  @mcp.tool
  async def cancel_order(
      ctx: Context,
      symbol: Annotated[str, Field(description="Trading pair, e.g. 'BTCUSDT'")],
      order_id: Annotated[int | None, Field(description="Binance order ID to cancel")] = None,
      client_order_id: Annotated[str | None, Field(description="Client order ID to cancel")] = None,
      is_algo: Annotated[
          bool,
          Field(
              description=(
                  "Set True for conditional orders (STOP_MARKET/TAKE_PROFIT_MARKET/etc.). "
                  "Read '_isAlgo' from get_open_orders results to determine this."
              )
          ),
      ] = False,
  ) -> dict:
      """Cancel a single open order by orderId or clientOrderId.
  
      For algo (conditional) orders returned by get_open_orders with '_isAlgo': True,
      set is_algo=True — this routes to the Algo API using algoId.
      """
      if order_id is None and client_order_id is None:
          raise ValueError("Provide either order_id or client_order_id")
      if is_algo:
          params = _strip_none({"algoId": order_id, "clientAlgoId": client_order_id})
          return _format_algo_order(await _client(ctx).delete_signed("/fapi/v1/algoOrder", params))
      params = _strip_none(
          {"symbol": symbol, "orderId": order_id, "origClientOrderId": client_order_id}
      )
      return _format_order(await _client(ctx).delete_signed("/fapi/v1/order", params))

• src/mcp_binance_futures/server.py:578-589 (schema)

  Input schema definition for cancel_order using Pydantic Field annotations with Annotated types. Defines symbol (required), order_id (optional), client_order_id (optional), and is_algo (boolean flag for conditional orders) parameters with descriptions.

  symbol: Annotated[str, Field(description="Trading pair, e.g. 'BTCUSDT'")],
  order_id: Annotated[int | None, Field(description="Binance order ID to cancel")] = None,
  client_order_id: Annotated[str | None, Field(description="Client order ID to cancel")] = None,
  is_algo: Annotated[
      bool,
      Field(
          description=(
              "Set True for conditional orders (STOP_MARKET/TAKE_PROFIT_MARKET/etc.). "
              "Read '_isAlgo' from get_open_orders results to determine this."
          )
      ),
  ] = False,

• src/mcp_binance_futures/server.py:771-790 (helper)

  _format_order helper function that normalizes order response dicts to a consistent shape with useful fields like orderId, status, type, side, price, etc. Used by cancel_order to format the API response.

  def _format_order(o: dict) -> dict:
      """Normalize an order dict to the fields most useful for decision-making."""
      return {
          "orderId": o.get("orderId"),
          "clientOrderId": o.get("clientOrderId"),
          "symbol": o.get("symbol"),
          "status": o.get("status"),
          "type": o.get("type"),
          "side": o.get("side"),
          "positionSide": o.get("positionSide"),
          "price": o.get("price"),
          "origQty": o.get("origQty"),
          "executedQty": o.get("executedQty"),
          "avgPrice": o.get("avgPrice"),
          "stopPrice": o.get("stopPrice"),
          "timeInForce": o.get("timeInForce"),
          "reduceOnly": o.get("reduceOnly"),
          "closePosition": o.get("closePosition"),
          "updateTime": o.get("updateTime"),
      }

• src/mcp_binance_futures/server.py:793-813 (helper)

  _format_algo_order helper function that normalizes algo (conditional) order responses to match the same shape as _format_order. Used when is_algo=True to format algo order cancellation responses.

  def _format_algo_order(o: dict) -> dict:
      """Normalize an algo order response (algoId-based) to the same shape as _format_order."""
      return {
          "orderId": o.get("algoId"),
          "clientOrderId": o.get("clientAlgoId"),
          "symbol": o.get("symbol"),
          "status": o.get("algoStatus"),
          "type": o.get("orderType"),
          "side": o.get("side"),
          "positionSide": o.get("positionSide"),
          "price": o.get("price"),
          "origQty": o.get("quantity"),
          "executedQty": None,
          "avgPrice": None,
          "stopPrice": o.get("triggerPrice"),
          "timeInForce": o.get("timeInForce"),
          "reduceOnly": o.get("reduceOnly"),
          "closePosition": o.get("closePosition"),
          "updateTime": o.get("updateTime"),
          "_isAlgo": True,
      }

• src/mcp_binance_futures/server.py:57-59 (helper)

  _strip_none helper function that removes keys with None values from params dict. Used by cancel_order to clean up optional parameters before sending to the Binance API.

  def _strip_none(d: dict[str, Any]) -> dict[str, Any]:
      """Remove keys whose value is None so they are not sent to Binance."""
      return {k: v for k, v in d.items() if v is not None}