MCP Paradex Server

Instructions

Implementation Reference

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

  The main handler function `get_markets` that executes the tool logic: fetches all markets or specific ones via Paradex client, validates and filters using MarketDetails model and JMESPath, applies pagination, and returns structured results with schema.
  @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 `MarketDetails` model used for input/output validation, schema generation (`model_json_schema()`), and data parsing (`TypeAdapter`) in the paradex_markets tool.
  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)

  MCP tool registration decorator binding the `get_markets` handler to the 'paradex_markets' tool name on the FastMCP server.
  @server.tool(name="paradex_markets")
• src/mcp_paradex/tools/market.py:58-58 (helper)

  TypeAdapter for validating lists of MarketDetails objects from API responses.
  market_details_adapter = TypeAdapter(list[MarketDetails])
• src/mcp_paradex/tools/market.py:47-54 (schema)

  Schema dictionary in `paradex_filters_model` tool that exposes JSON schema for paradex_markets and other tools.
  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(), }