MCP Paradex Server

Instructions

Implementation Reference

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

  The core handler function for the 'paradex_markets' tool. Fetches all or specific market details from Paradex API using client.fetch_markets(), validates response with TypeAdapter(list[MarketDetails]), applies optional JMESPath filtering, sorts by symbol descending, applies limit/offset pagination, and returns a dictionary with schema info, results, 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 defining the structure and validation for individual market details returned by the tool. Used for response validation (via TypeAdapter(list[MarketDetails])) and JSON schema generation (model_json_schema()). Includes fields like symbol, tick sizes, limits, asset kind, etc.
  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 'paradex_markets' tool on the FastMCP server instance imported from mcp_paradex.server.server. Registration occurs upon module import.
  @server.tool(name="paradex_markets")
• src/mcp_paradex/tools/market.py:47-55 (schema)

  The paradex_filters_model tool provides the JSON schema for 'paradex_markets' input/output via MarketDetails.model_json_schema(), enabling clients to build precise JMESPath filters.
  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(), } return tool_descriptions[tool_name]
• src/mcp_paradex/tools/market.py:58-58 (helper)

  TypeAdapter for list[MarketDetails] used to validate the raw API response before processing.
  market_details_adapter = TypeAdapter(list[MarketDetails])