MCP Paradex Server

Instructions

Get a snapshot of your account's current financial status and trading capacity.

Use this tool when you need to:
- Check your current available and total balance
- Understand your margin utilization and remaining trading capacity
- Verify your account health and distance from liquidation
- Get an overview of realized and unrealized P&L

This provides the essential financial information needed to make informed
trading decisions and manage risk appropriately.

Example use cases:
- Checking available balance before placing new orders
- Monitoring account health during volatile market conditions
- Assessing realized and unrealized P&L for performance tracking
- Verifying margin requirements and utilization

Implementation Reference

• src/mcp_paradex/tools/account.py:17-44 (handler)

  The handler function for paradex_account_summary tool. It fetches the account summary via Paradex API, validates the response using AccountSummary model, and formats the output with schema and results.

  @server.tool(name="paradex_account_summary")
  async def get_account_summary(ctx: Context) -> dict:
      """
      Get a snapshot of your account's current financial status and trading capacity.
  
      Use this tool when you need to:
      - Check your current available and total balance
      - Understand your margin utilization and remaining trading capacity
      - Verify your account health and distance from liquidation
      - Get an overview of realized and unrealized P&L
  
      This provides the essential financial information needed to make informed
      trading decisions and manage risk appropriately.
  
      Example use cases:
      - Checking available balance before placing new orders
      - Monitoring account health during volatile market conditions
      - Assessing realized and unrealized P&L for performance tracking
      - Verifying margin requirements and utilization
      """
      client = await get_authenticated_paradex_client()
      response = await api_call(client, "account")
      result = {
          "description": AccountSummary.__doc__.strip() if AccountSummary.__doc__ else None,
          "fields": AccountSummary.model_json_schema(),
          "results": account_summary_adapter.validate_python(response),
      }
      return result

• src/mcp_paradex/models.py:514-544 (schema)

  Pydantic BaseModel defining the schema for the account summary data, used for validation and JSON schema generation in the tool response.

  class AccountSummary(BaseModel):
      """Model representing an account summary response from Paradex."""
  
      account: Annotated[str, Field(description="User's starknet account")]
      account_value: Annotated[str, Field(description="Current account value [with unrealized P&Ls]")]
      free_collateral: Annotated[
          str,
          Field(
              description="Free collateral available (Account value in excess of Initial Margin required)"
          ),
      ]
      initial_margin_requirement: Annotated[
          str, Field(description="Amount required to open trade for the existing positions")
      ]
      maintenance_margin_requirement: Annotated[
          str, Field(description="Amount required to maintain exisiting positions")
      ]
      margin_cushion: Annotated[
          str, Field(description="Acc value in excess of maintenance margin required")
      ]
      seq_no: Annotated[
          int,
          Field(
              description="Unique increasing number (non-sequential) that is assigned to this account update. Can be used to deduplicate multiple feeds"
          ),
      ]
      settlement_asset: Annotated[str, Field(description="Settlement asset for the account")]
      status: Annotated[str, Field(description="Status of the acc - like ACTIVE, LIQUIDATION")]
      total_collateral: Annotated[str, Field(description="User's total collateral")]
      updated_at: Annotated[int, Field(description="Account last updated time")]

• src/mcp_paradex/tools/account.py:17-17 (registration)

  The @server.tool decorator registers the get_account_summary function as the 'paradex_account_summary' tool.

  @server.tool(name="paradex_account_summary")

• src/mcp_paradex/tools/account.py:14-14 (helper)

  TypeAdapter for AccountSummary used to validate the API response in the handler.

  account_summary_adapter = TypeAdapter(AccountSummary)