MCP Paradex Server

Instructions

Check the detailed status of a specific order for execution monitoring.

Use this tool when you need to:
- Confirm if a particular order was accepted and is active
- Check if an order has been filled, partially filled, or canceled
- Get execution details for a specific order
- Diagnose issues with order placement
- Track the status of important orders individually

Order status tracking is essential for verifying execution status
and troubleshooting any issues with specific orders.

Example use cases:
- Checking if a recently placed limit order is active in the book
- Verifying fill details of a specific order
- Determining why an order might have been rejected
- Confirming cancellation status of an order you attempted to cancel
- Getting execution timestamps for order lifecycle analysis

Implementation Reference

• src/mcp_paradex/tools/orders.py:189-189 (registration)

  Decorator that registers the get_order_status function as the MCP tool named 'paradex_order_status'.

  @server.tool(name="paradex_order_status")

• src/mcp_paradex/tools/orders.py:190-228 (handler)

  The core handler function that implements the paradex_order_status tool logic. It authenticates the Paradex client, fetches the order by ID or client ID, validates the response using OrderState, and returns a standardized dictionary with schema and results.

  async def get_order_status(
      order_id: Annotated[str, Field(description="Order identifier.")],
      client_id: Annotated[str, Field(description="Client-specified order ID.")],
      ctx: Context = None,
  ) -> dict:
      """
      Check the detailed status of a specific order for execution monitoring.
  
      Use this tool when you need to:
      - Confirm if a particular order was accepted and is active
      - Check if an order has been filled, partially filled, or canceled
      - Get execution details for a specific order
      - Diagnose issues with order placement
      - Track the status of important orders individually
  
      Order status tracking is essential for verifying execution status
      and troubleshooting any issues with specific orders.
  
      Example use cases:
      - Checking if a recently placed limit order is active in the book
      - Verifying fill details of a specific order
      - Determining why an order might have been rejected
      - Confirming cancellation status of an order you attempted to cancel
      - Getting execution timestamps for order lifecycle analysis
      """
      client = await get_authenticated_paradex_client()
      if order_id:
          response = client.fetch_order(order_id)
      elif client_id:
          response = client.fetch_order_by_client_id(client_id)
      else:
          raise Exception("Either order_id or client_id must be provided.")
      order: OrderState = OrderState.model_validate(response)
      result = {
          "description": OrderState.__doc__.strip() if OrderState.__doc__ else None,
          "fields": OrderState.model_json_schema(),
          "results": order,
      }
      return result

• src/mcp_paradex/models.py:169-209 (schema)

  Pydantic BaseModel defining the structure and validation for order status data returned by the Paradex API. Used for input validation and output schema generation in the tool response.

  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/utils/paradex_client.py:68-81 (helper)

  Utility function that provides the authenticated ParadexApiClient instance used by the tool handler to make API calls like fetch_order.

  async def get_authenticated_paradex_client() -> ParadexApiClient:
      """
      Get or initialize the authenticated Paradex client.
  
      Returns:
          Paradex: The initialized Paradex client.
  
      Raises:
          ValueError: If the required configuration is not set.
      """
      client = await get_paradex_client()
      if client.account is None:
          raise ValueError("Paradex client is not authenticated")
      return client