MCP Paradex Server

Instructions

Implementation Reference

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

  The handler function for paradex_order_status tool. It retrieves the status of a specific order using either order_id or client_id via the Paradex client API. Includes registration via @server.tool decorator.
  @server.tool(name="paradex_order_status") 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 model OrderState defining the structure and validation for order status data returned by the tool.
  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-82 (helper)

  Helper function that provides an authenticated instance of the ParadexApiClient, essential for making authenticated API calls in the tool handler.
  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