paradex_funding_data

Instructions

Analyze funding rates for potential funding arbitrage or to understand holding costs.

Use this tool when you need to:
- Calculate expected funding payments for a position
- Find markets with extreme funding rates for potential arbitrage
- Understand historical funding patterns for a market
- Evaluate the cost of holding a position over time

This data is critical for perpetual futures traders to assess the carrying cost
of positions and identify potential funding arbitrage opportunities.

Example use cases:
- Finding markets with negative funding for "paid to hold" opportunities
- Calculating the funding component of a trade's P&L
- Comparing funding rates across different assets for relative value trades
- Analyzing funding rate volatility to predict potential rate changes

Implementation Reference

• src/mcp_paradex/tools/market.py:257-300 (handler)

  The main tool handler function that fetches and returns funding data for a specified market over a time range using the Paradex API client. Includes input parameter definitions and output formatting with schema.

  @server.tool(name="paradex_funding_data")
  async def get_funding_data(
      market_id: Annotated[str, Field(description="Market symbol to get funding data for.")],
      start_unix_ms: Annotated[int, Field(description="Start time in unix milliseconds.")],
      end_unix_ms: Annotated[int, Field(description="End time in unix milliseconds.")],
      ctx: Context = None,
  ) -> dict[str, Any]:
      """
      Analyze funding rates for potential funding arbitrage or to understand holding costs.
  
      Use this tool when you need to:
      - Calculate expected funding payments for a position
      - Find markets with extreme funding rates for potential arbitrage
      - Understand historical funding patterns for a market
      - Evaluate the cost of holding a position over time
  
      This data is critical for perpetual futures traders to assess the carrying cost
      of positions and identify potential funding arbitrage opportunities.
  
      Example use cases:
      - Finding markets with negative funding for "paid to hold" opportunities
      - Calculating the funding component of a trade's P&L
      - Comparing funding rates across different assets for relative value trades
      - Analyzing funding rate volatility to predict potential rate changes
      """
      try:
          # Get funding data from Paradex
          client = await get_paradex_client()
          response = client.fetch_funding_data(
              params={"market": market_id, "start_at": start_unix_ms, "end_at": end_unix_ms}
          )
          if "error" in response:
              await ctx.error(response)
              raise Exception(response["error"])
          funding_data = funding_data_adapter.validate_python(response["results"])
          results = {
              "description": FundingData.__doc__.strip() if FundingData.__doc__ else None,
              "fields": FundingData.model_json_schema(),
              "results": funding_data,
          }
          return results
      except Exception as e:
          await ctx.error(f"Error fetching funding data for {market_id}: {e!s}")
          raise e

• src/mcp_paradex/models.py:546-574 (schema)

  Pydantic BaseModel defining the structure and fields for FundingData used in the tool's output validation and schema description.

  class FundingData(BaseModel):
      """
      Model representing funding data for a perpetual market.
      https://docs.paradex.trade/documentation/risk-system/funding-mechanism
      """
  
      market: Annotated[str, Field(description="Market represents the market identifier")]
      created_at: Annotated[
          int, Field(description="Timestamp in milliseconds when the funding data was calculated")
      ]
      funding_index: Annotated[
          str,
          Field(
              description="Funding Index is accrued funding for 1 unit of the asset since market launchs and is calculated as a time-weighted sum of the Funding Premium. This value expressed in the settlement asset of the instrument (USDC)"
          ),
      ]
      funding_premium: Annotated[
          str,
          Field(
              description="Funding Premium represents the 8h amount paid by long positions to short positions. This value expressed in the settlement asset of the instrument (USDC)"
          ),
      ]
      funding_rate: Annotated[
          str,
          Field(
              description="Clamped [mark price]/[spot price] - 1. Full details - https://docs.paradex.trade/documentation/risk-system/funding-mechanism#funding-rate"
          ),
      ]

• src/mcp_paradex/tools/market.py:257-257 (registration)

  The @server.tool decorator that registers the paradex_funding_data tool with the MCP server.

  @server.tool(name="paradex_funding_data")