OKX MCP Server

Instructions

Implementation Reference

• mcp_okx/trading.py:207-232 (handler)

  The handler function for the 'get_orders_history' tool. It defines the input parameters using Pydantic Fields and proxies the call to the OKX TradeAPI's get_orders_history method.
  def get_orders_history( instType: str = Field(description="Instrument type: `SPOT/MARGIN/SWAP/FUTURES/OPTION`"), instFamily: str = Field("", description="Instrument family. Applicable to `FUTURES/SWAP/OPTION`"), instId: str = Field("", description="Instrument ID, e.g. BTC-USDT"), state: str = Field("", description="State: `canceled`/`filled`/`mmp_canceled`: Order canceled automatically due to Market Maker Protection"), category: str = Field("", description="Category: `twap/adl/full_liquidation/partial_liquidation/delivery`/`ddh`: Delta dynamic hedge"), ordType: str = Field("", description="Order type. " "\n`market`: Market order" "\n`limit`: Limit order" "\n`post_only`: Post-only order" "\n`fok`: Fill-or-kill order" "\n`ioc`: Immediate-or-cancel order" "\n`optimal_limit_ioc`: Market order with immediate-or-cancel order" "\n`mmp`: Market Maker Protection (only applicable to Option in Portfolio Margin mode)" "\n`mmp_and_post_only`: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode)" "\n`op_fok`: Simple options (fok)"), limit: str | int = Field(20, description="Number of results per request. [1-100]. Default: 20"), ): return ACCOUNT.get_orders_history( instType=instType, instFamily=instFamily, instId=instId, state=state, ordType=ordType, limit=str(limit), )
• mcp_okx/__init__.py:26-26 (registration)

  Registers the tools from the trading module, including 'get_orders_history', by calling trading.add_tools(mcp) on the FastMCP server instance.
  trading.add_tools(mcp)
• mcp_okx/trading.py:262-382 (schema)

  Defines the output schema for trade orders via an MCP resource, referenced in the tool's description as `schema://trade/order`.
  @mcp.resource( uri="schema://trade/order", description="This resource is used to describe the schema of the trade order on OKX", ) def schema_trade_order(): return """ instType String Instrument type `MARGIN/SWAP/FUTURES/OPTION` instId String Instrument ID tgtCcy String Order quantity unit setting for sz base_ccy: Base currency ,quote_ccy: Quote currency Only applicable to SPOT Market Orders Default is quote_ccy for buy, base_ccy for sell ccy String Margin currency Applicable to all isolated MARGIN orders and cross MARGIN orders in Futures mode, FUTURES and SWAP contracts. ordId String Order ID clOrdId String Client Order ID as assigned by the client tag String Order tag px String Price. For options, use coin as unit (e.g. BTC, ETH) pxUsd String Options price in USDOnly applicable to options; return "" for other instrument types pxVol String Implied volatility of the options orderOnly applicable to options; return "" for other instrument types pxType String Price type of options px: Place an order based on price, in the unit of coin (the unit for the request parameter px is BTC or ETH) pxVol: Place an order based on pxVol pxUsd: Place an order based on pxUsd, in the unit of USD (the unit for the request parameter px is USD) sz String Quantity to buy or sell pnl String Profit and loss (excluding the fee). Applicable to orders which have a trade and aim to close position. It always is 0 in other conditions ordType String Order type market: Market order limit: Limit order post_only: Post-only order fok: Fill-or-kill order ioc: Immediate-or-cancel order optimal_limit_ioc: Market order with immediate-or-cancel order mmp: Market Maker Protection (only applicable to Option in Portfolio Margin mode) mmp_and_post_only: Market Maker Protection and Post-only order(only applicable to Option in Portfolio Margin mode) op_fok: Simple options (fok) side String Order side posSide String Position side tdMode String Trade mode accFillSz String Accumulated fill quantity The unit is base_ccy for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is base_ccy when the tgtCcy is base_ccy or quote_ccy; The unit is contract for FUTURES/SWAP/OPTION fillPx String Last filled price. If none is filled, it will return "". tradeId String Last traded ID fillSz String Last filled quantity The unit is base_ccy for SPOT and MARGIN, e.g. BTC-USDT, the unit is BTC; For market orders, the unit both is base_ccy when the tgtCcy is base_ccy or quote_ccy; The unit is contract for FUTURES/SWAP/OPTION fillTime String Last filled time avgPx String Average filled price. If none is filled, it will return "". state String State. canceled/live/partially_filled/filled/mmp_canceled lever String Leverage, from 0.01 to 125. Only applicable to MARGIN/FUTURES/SWAP stpMode String Self trade prevention mode attachAlgoClOrdId String Client-supplied Algo ID when placing order attaching TP/SL. tpTriggerPx String Take-profit trigger price. tpTriggerPxType String Take-profit trigger price type. last: last price index: index price mark: mark price tpOrdPx String Take-profit order price. slTriggerPx String Stop-loss trigger price. slTriggerPxType String Stop-loss trigger price type. last: last price index: index price mark: mark price slOrdPx String Stop-loss order price. attachAlgoOrds Array of objects TP/SL information attached when placing order > attachAlgoId String The order ID of attached TP/SL order. It can be used to identity the TP/SL order when amending. It will not be posted to algoId when placing TP/SL order after the general order is filled completely. > attachAlgoClOrdId String Client-supplied Algo ID when placing order attaching TP/SL A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. It will be posted to algoClOrdId when placing TP/SL order once the general order is filled completely. > tpOrdKind String TP order kind. condition/limit > tpTriggerPx String Take-profit trigger price. > tpTriggerPxType String Take-profit trigger price type. last: last price index: index price mark: mark price > tpOrdPx String Take-profit order price. > slTriggerPx String Stop-loss trigger price. > slTriggerPxType String Stop-loss trigger price type. last: last price index: index price mark: mark price > slOrdPx String Stop-loss order price. > sz String Size. Only applicable to TP order of split TPs > amendPxOnTriggerType String Whether to enable Cost-price SL. Only applicable to SL order of split TPs. 0: disable, the default value 1: Enable > amendPxOnTriggerType String Whether to enable Cost-price SL. Only applicable to SL order of split TPs. 0: disable, the default value 1: Enable > failCode String The error code when failing to place TP/SL order, e.g. 51020. The default is "" > failReason String The error reason when failing to place TP/SL order. The default is "" linkedAlgoOrd Object Linked SL order detail, only applicable to the order that is placed by one-cancels-the-other (OCO) order that contains the TP limit order. > algoId String Algo ID feeCcy String Fee currency For maker sell orders of Spot and Margin, this represents the quote currency. For all other cases, it represents the currency in which fees are charged. fee String Fee amount For Spot and Margin (excluding maker sell orders): accumulated fee charged by the platform, always negative For maker sell orders in Spot and Margin, Expiry Futures, Perpetual Futures and Options: accumulated fee and rebate (always in quote currency for maker sell orders in Spot and Margin) rebateCcy String Rebate currency For maker sell orders of Spot and Margin, this represents the base currency. For all other cases, it represents the currency in which rebates are paid. rebate String Rebate amount, only applicable to Spot and Margin For maker sell orders: Accumulated fee and rebate amount in base currency. For all other cases, it represents the maker rebate amount, always positive, return "" if no rebate. source String Order source 6: The normal order triggered by the trigger order 7: The normal order triggered by the TP/SL order 13: The normal order triggered by the algo order 25: The normal order triggered by the trailing stop order 34: The normal order triggered by the chase order category String Category. normal/twap/adl/full_liquidation/partial_liquidation/delivery/ddh(Delta dynamic hedge)/auto_conversion reduceOnly String Whether the order can only reduce the position size. Valid options: true or false. isTpLimit String Whether it is TP limit order. true or false cancelSource String Code of the cancellation source. cancelSourceReason String Reason for the cancellation. quickMgnType String Quick Margin type, Only applicable to Quick Margin Mode of isolated margin. manual/auto_borrow/auto_repay algoClOrdId String Client-supplied Algo ID. There will be a value when algo order attaching algoClOrdId is triggered, or it will be "". algoId String Algo ID. There will be a value when algo order is triggered, or it will be "". tradeQuoteCcy String The quote currency used for trading. """
• mcp_okx/trading.py:201-206 (registration)

  The @mcp.tool decorator registers the get_orders_history function as a tool on the FastMCP instance inside add_tools.
  @mcp.tool( title="Get Order History", description="Get completed orders on OKX which are placed in the last 7 days, including those placed 7 days ago but completed in the last 7 days." "The incomplete orders that have been canceled are only reserved for 2 hours. " "For a detailed schema of the output object, please read the resource at: `schema://trade/order`", )