MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/orders.py:20-77 (handler)

  The core handler function for the paradex_open_orders tool, decorated with @server.tool. It fetches open orders from Paradex API using authenticated client, handles pagination (market filter, limit, offset), validates and sorts orders using OrderState model, and returns a standardized response with schema, results, and metadata.
  @server.tool(name="paradex_open_orders", annotations=ToolAnnotations(readOnlyHint=True)) async def get_open_orders( market_id: Annotated[str, Field(default="ALL", description="Filter by market.")], limit: Annotated[ int, Field( default=10, gt=0, le=100, description="Limit the number of results to the specified number.", ), ], offset: Annotated[ int, Field( default=0, ge=0, description="Offset the results to the specified number.", ), ], ctx: Context = None, ) -> dict: """ Monitor your active orders to track execution status and manage your trading strategy. Use this tool when you need to: - Check which of your orders are still pending execution - Verify limit order prices and remaining quantities - Determine which orders might need cancellation or modification - Get a complete picture of your current market exposure Keeping track of your open orders is essential for effective order management and avoiding duplicate or conflicting trades. Example use cases: - Checking if your limit orders have been partially filled - Verifying that a recently placed order was accepted by the exchange - Identifying stale orders that should be canceled or modified - Getting a consolidated view of all pending orders across markets """ client = await get_authenticated_paradex_client() params = {"market": market_id} if market_id != "" and market_id != "ALL" else None response = client.fetch_orders(params=params) if "error" in response: ctx.error(f"Error fetching open orders: {response['error']}") raise Exception(response["error"]) orders = order_state_adapter.validate_python(response["results"]) sorted_orders = sorted(orders, key=lambda x: x.created_at) result_orders = sorted_orders[offset : offset + limit] result = { "description": OrderState.__doc__.strip() if OrderState.__doc__ else None, "fields": OrderState.model_json_schema(), "results": result_orders, "total": len(sorted_orders), "limit": limit, "offset": offset, } return result
• src/mcp_paradex/models.py:169-209 (schema)

  Pydantic BaseModel defining the OrderState schema used for validating API responses and providing JSON schema in tool outputs for paradex_open_orders.
  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/orders.py:20-20 (registration)

  The @server.tool decorator registers the get_open_orders function as the MCP tool named 'paradex_open_orders' with read-only hint.
  @server.tool(name="paradex_open_orders", annotations=ToolAnnotations(readOnlyHint=True))
• src/mcp_paradex/tools/market.py:47-54 (schema)

  References OrderState.model_json_schema() in the tool_descriptions dict used by paradex_filters_model tool to provide schema information for paradex_open_orders.
  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(), }
• src/mcp_paradex/tools/orders.py:17-17 (helper)

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