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])