MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/orders.py:231-259 (handler)

  The main execution handler for the 'paradex_orders_history' tool. Fetches historical order data from Paradex API within specified time range and market, validates with OrderState model, and returns structured results including schema.
  @server.tool(name="paradex_orders_history") async def get_orders_history( market_id: Annotated[str, Field(description="Filter by market.")], start_unix_ms: Annotated[int, Field(description="Start time in unix milliseconds.")], end_unix_ms: Annotated[int, Field(description="End time in unix milliseconds.")], ctx: Context = None, ) -> dict: """ Get historical orders. Retrieves the history of orders for the account, including filled, canceled, and expired orders. This is useful for analyzing past trading activity and performance. """ client = await get_authenticated_paradex_client() params = {"market": market_id, "start_at": start_unix_ms, "end_at": end_unix_ms} # Remove None values from params params = {k: v for k, v in params.items() if v is not None} response = client.fetch_orders_history(params=params) if "error" in response: await ctx.error(response) raise Exception(response["error"]) orders_raw: list[dict[str, Any]] = response["results"] orders = order_state_adapter.validate_python(orders_raw) result = { "description": OrderState.__doc__.strip() if OrderState.__doc__ else None, "fields": OrderState.model_json_schema(), "results": orders, } return result
• src/mcp_paradex/models.py:169-209 (schema)

  Pydantic model 'OrderState' defining the structure and validation for individual order records returned in the tool's results. Used for input/output schema via model_json_schema().
  class OrderState(BaseModel): """Order state model representing the current state of an order on Paradex.""" id: Annotated[str, Field(description="Unique order identifier generated by Paradex")] account: Annotated[str, Field(description="Paradex Account")] market: Annotated[str, Field(description="Market")] side: Annotated[str, Field(description="Order side")] type: Annotated[str, Field(description="Order type")] size: Annotated[float, Field(description="Order size")] remaining_size: Annotated[float, Field(description="Remaining size of the order")] price: Annotated[float, Field(description="Order price. 0 for MARKET orders")] status: Annotated[str, Field(description="Order status")] created_at: Annotated[int, Field(description="Order creation time")] last_updated_at: Annotated[ int, Field(description="Order last update time. No changes once status=CLOSED") ] timestamp: Annotated[int, Field(description="Order signature timestamp")] cancel_reason: Annotated[ str, Field(description="Reason for order cancellation if it was closed by cancel") ] client_id: Annotated[ str, Field(description="Client order id provided by the client at order creation") ] seq_no: Annotated[ int, Field( description="Unique increasing number that is assigned to this order update and changes on every order update" ), ] instruction: Annotated[str, Field(description="Execution instruction for order matching")] avg_fill_price: Annotated[str, Field(description="Average fill price of the order")] stp: Annotated[str, Field(description="Self Trade Prevention mode")] received_at: Annotated[ int, Field(description="Timestamp in milliseconds when order was received by API service") ] published_at: Annotated[ int, Field(description="Timestamp in milliseconds when order was sent to the client") ] flags: Annotated[list[str], Field(description="Order flags, allow flag: REDUCE_ONLY")] trigger_price: Annotated[str, Field(description="Trigger price for stop order")]
• src/mcp_paradex/tools/market.py:47-55 (schema)

  Schema mapping in 'get_filters_model' tool that provides the JSON schema for 'paradex_orders_history' output using OrderState.model_json_schema() for client-side validation/filtering.
  tool_descriptions = { "paradex_markets": models.MarketDetails.model_json_schema(), "paradex_market_summaries": models.MarketSummary.model_json_schema(), "paradex_open_orders": models.OrderState.model_json_schema(), "paradex_orders_history": models.OrderState.model_json_schema(), "paradex_vaults": models.Vault.model_json_schema(), "paradex_vault_summary": models.VaultSummary.model_json_schema(), } return tool_descriptions[tool_name]
• src/mcp_paradex/tools/orders.py:17-17 (helper)

  TypeAdapter for list[OrderState] used in the handler to validate the raw API response into typed order list.
  order_state_adapter = TypeAdapter(list[OrderState])