get_order_history

Retrieve detailed order history from Bybit by specifying category, symbol, order ID, and time range. Use this tool to monitor past orders, analyze trading activity, and manage portfolio performance.

Instructions

Get order history

Args:
    category (str): Category (spot, linear, inverse, etc.)
    symbol (Optional[str]): Symbol (e.g., BTCUSDT)
    orderId (Optional[str]): Order ID
    orderLinkId (Optional[str]): Order link ID
    orderFilter (Optional[str]): Order filter
    orderStatus (Optional[str]): Order status
    startTime (Optional[int]): Start time in milliseconds
    endTime (Optional[int]): End time in milliseconds
    limit (int): Number of orders to retrieve

Returns:
    Dict: Order history

Example:
    get_order_history("spot", "BTCUSDT", "123456789", "link123", "Order", "Created", 1625097600000, 1625184000000, 10)

Reference:
    https://bybit-exchange.github.io/docs/v5/order/order-list

Input Schema

TableJSON Schema

Name	Required	Description
`category`	Yes	Category (spot, linear, inverse, etc.)
`endTime`	No	End time in milliseconds
`limit`	No	Number of orders to retrieve
`orderFilter`	No	Order filter
`orderId`	No	Order ID
`orderLinkId`	No	Order link ID
`orderStatus`	No	Order status
`startTime`	No	Start time in milliseconds
`symbol`	No	Symbol (e.g., BTCUSDT)

Implementation Reference

src/server.py:393-439 (handler)

MCP tool handler for get_order_history: decorated with @mcp.tool(), defines input schema via Pydantic Field, delegates to BybitService.get_order_history, handles errors and logging.

@mcp.tool()
def get_order_history(
    category: str = Field(description="Category (spot, linear, inverse, etc.)"),
    symbol: Optional[str] = Field(default=None, description="Symbol (e.g., BTCUSDT)"),
    orderId: Optional[str] = Field(default=None, description="Order ID"),
    orderLinkId: Optional[str] = Field(default=None, description="Order link ID"),
    orderFilter: Optional[str] = Field(default=None, description="Order filter"),
    orderStatus: Optional[str] = Field(default=None, description="Order status"),
    startTime: Optional[int] = Field(default=None, description="Start time in milliseconds"),
    endTime: Optional[int] = Field(default=None, description="End time in milliseconds"),
    limit: int = Field(default=50, description="Number of orders to retrieve")
) -> Dict:
    """
    Get order history

    Args:
        category (str): Category (spot, linear, inverse, etc.)
        symbol (Optional[str]): Symbol (e.g., BTCUSDT)
        orderId (Optional[str]): Order ID
        orderLinkId (Optional[str]): Order link ID
        orderFilter (Optional[str]): Order filter
        orderStatus (Optional[str]): Order status
        startTime (Optional[int]): Start time in milliseconds
        endTime (Optional[int]): End time in milliseconds
        limit (int): Number of orders to retrieve

    Returns:
        Dict: Order history

    Example:
        get_order_history("spot", "BTCUSDT", "123456789", "link123", "Order", "Created", 1625097600000, 1625184000000, 10)

    Reference:
        https://bybit-exchange.github.io/docs/v5/order/order-list
    """
    try:
        result = bybit_service.get_order_history(
            category, symbol, orderId, orderLinkId,
            orderFilter, orderStatus, startTime, endTime, limit
        )
        if result.get("retCode") != 0:
            logger.error(f"Failed to get order history: {result.get('retMsg')}")
            return {"error": result.get("retMsg")}
        return result
    except Exception as e:
        logger.error(f"Failed to get order history: {e}", exc_info=True)
        return {"error": str(e)}

src/service.py:345-377 (helper)

BybitService helper method that directly calls the pybit.unified_trading.HTTP client.get_order_history API.

def get_order_history(self, category: str, symbol: Optional[str] = None,
                      orderId: Optional[str] = None, orderLinkId: Optional[str] = None,
                      orderFilter: Optional[str] = None, orderStatus: Optional[str] = None,
                      startTime: Optional[int] = None, endTime: Optional[int] = None,
                      limit: int = 50) -> Dict:
    """
    Get order history

    Args:
        category (str): Category (spot, linear, inverse, etc.)
        symbol (Optional[str]): Symbol (e.g., BTCUSDT)
        orderId (Optional[str]): Order ID
        orderLinkId (Optional[str]): Order link ID
        orderFilter (Optional[str]): Order filter
        orderStatus (Optional[str]): Order status
        startTime (Optional[int]): Start time in milliseconds
        endTime (Optional[int]): End time in milliseconds
        limit (int): Number of orders to retrieve

    Returns:
        Dict: Order history
    """
    return self.client.get_order_history(
        category=category,
        symbol=symbol,
        orderId=orderId,
        orderLinkId=orderLinkId,
        orderFilter=orderFilter,
        orderStatus=orderStatus,
        startTime=startTime,
        endTime=endTime,
        limit=limit
    )

Bybit Server