MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/market.py:61-152 (handler)

  The main handler function for the paradex_markets tool, decorated with @server.tool(name="paradex_markets"). Fetches market details from Paradex API, applies filtering by market IDs, JMESPath expressions, pagination (limit/offset), validates with Pydantic, sorts results, and returns a structured dictionary including schema and metadata.
  @server.tool(name="paradex_markets") async def get_markets( market_ids: Annotated[ list[str], Field(description="Market symbols to get details for.", default=["ALL"]) ], jmespath_filter: Annotated[ str, Field( description="JMESPath expression to filter, sort, or limit the results.", default="", ), ], 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: """ Find markets that match your trading criteria or get detailed market specifications. Use this tool when you need to: - Understand exact tick sizes and minimum order sizes before placing trades - Find all markets for a specific asset (e.g., all BTC-based markets) - Compare contract specifications across different markets - Identify markets with specific characteristics for your trading strategy Retrieves comprehensive details about specified markets, including base and quote assets, tick size, minimum order size, and other trading parameters. If "ALL" is specified or no market IDs are provided, returns details for all available markets. Example use cases: - Finding the minimum order size for a new trade - Identifying markets with the smallest tick size for precise entries - Checking which assets are available for trading `asset_kind` is the type of asset in the market. It can be `PERP` or `PERP_OPTION`. You can use JMESPath expressions (https://jmespath.org/specification.html) to filter, sort, or limit the results. Use the `paradex_filters_model` tool to get the filters for a tool. Examples: - Filter by base asset: "[?base_asset=='BTC']" - Sort by 24h volume: "sort_by([*], &volume_24h)" - Limit to top 5 by volume: "[sort_by([*], &to_number(volume_24h))[-5:]]" """ try: client = await get_paradex_client() response = client.fetch_markets() if "error" in response: await ctx.error(response) raise Exception(response["error"]) details = market_details_adapter.validate_python(response["results"]) if market_ids and "ALL" not in market_ids: details = [detail for detail in details if detail.symbol in market_ids] # Apply JMESPath filter if provided if jmespath_filter: details = apply_jmespath_filter( data=details, jmespath_filter=jmespath_filter, type_adapter=market_details_adapter, error_logger=ctx.error if ctx else None, ) sorted_details = sorted(details, key=lambda x: x.symbol, reverse=True) result_details = sorted_details[offset : offset + limit] result = { "description": MarketDetails.__doc__.strip() if MarketDetails.__doc__ else None, "fields": MarketDetails.model_json_schema(), "results": result_details, "total": len(sorted_details), "limit": limit, "offset": offset, } return result except Exception as e: await ctx.error(f"Error fetching market details: {e!s}") raise e
• src/mcp_paradex/models.py:446-512 (schema)

  Pydantic BaseModel MarketDetails used for input validation of API responses and defining the output schema structure for market details in the paradex_markets tool results. Referenced via MarketDetails.model_json_schema() in the handler.
  class MarketDetails(BaseModel): """Model representing the details of a market.""" symbol: Annotated[str, Field(default="", description="Market symbol")] base_currency: Annotated[str, Field(default="", description="Base currency of the market")] quote_currency: Annotated[str, Field(default="", description="Quote currency of the market")] settlement_currency: Annotated[ str, Field(default="", description="Settlement currency of the market") ] order_size_increment: Annotated[ str, Field(default="", description="Minimum size increment for base currency") ] price_tick_size: Annotated[ float, Field(default=0.0, description="Minimum price increment of the market in USD") ] min_notional: Annotated[float, Field(default=0.0, description="Minimum order size in USD")] open_at: Annotated[int, Field(default=0, description="Market open time in milliseconds")] expiry_at: Annotated[int, Field(default=0, description="Market expiry time")] asset_kind: Annotated[ str, Field(default="", description="Type of asset", examples=["PERP", "PERP_OPTION"]) ] market_kind: Annotated[str, Field(default="", description="Type of market - always 'cross'")] position_limit: Annotated[float, Field(default=0.0, description="Position limit")] price_bands_width: Annotated[ float, Field( default=0.0, description="Price Bands Width, 0.05 means 5% price deviation allowed from mark price", ), ] max_open_orders: Annotated[int, Field(default=0, description="Max open orders")] max_funding_rate: Annotated[float, Field(default=0.0, description="Max funding rate")] delta1_cross_margin_params: Annotated[ dict[str, float], Field(default_factory=dict, description="Delta1 Cross margin parameters") ] option_cross_margin_params: Annotated[ dict[str, dict[str, float]], Field(default_factory=dict, description="Option Cross margin parameters"), ] price_feed_id: Annotated[ str, Field( default="", description="Price feed id. Pyth price account used to price underlying asset", ), ] oracle_ewma_factor: Annotated[float, Field(default=0.0, description="Oracle EWMA factor")] max_order_size: Annotated[ float, Field(default=0.0, description="Maximum order size in base currency") ] max_funding_rate_change: Annotated[ float, Field(default=0.0, description="Max funding rate change") ] max_tob_spread: Annotated[ float, Field( default=0.0, description="The maximum TOB spread allowed to apply funding rate changes" ), ] interest_rate: Annotated[float, Field(default=0.0, description="Interest rate")] clamp_rate: Annotated[float, Field(default=0.0, description="Clamp rate")] funding_period_hours: Annotated[int, Field(default=0, description="Funding period in hours")] tags: Annotated[list[str], Field(default_factory=list, description="Market tags")] option_type: Annotated[str, Field(default="", description="Type of option (PUT or CALL)")] strike_price: Annotated[float, Field(default=0.0, description="Strike price for option market")] iv_bands_width: Annotated[float, Field(default=0.0, description="IV Bands Width")]
• src/mcp_paradex/tools/market.py:61-61 (registration)

  The @server.tool decorator registers the get_markets function as the MCP tool named 'paradex_markets'.
  @server.tool(name="paradex_markets")
• src/mcp_paradex/tools/market.py:58-58 (helper)

  TypeAdapter for list[MarketDetails] used to validate the raw API response data in the handler.
  market_details_adapter = TypeAdapter(list[MarketDetails])
• src/mcp_paradex/tools/market.py:48-48 (schema)

  Reference to MarketDetails.model_json_schema() in the get_filters_model tool, providing the output schema for paradex_markets.
  "paradex_markets": models.MarketDetails.model_json_schema(),