MCP Paradex Server

Instructions

Get a comprehensive overview of a vault's trading account status.

Use this tool when you need to:
- Check account health and available margin
- Monitor total exposure and leverage
- Understand risk metrics and account status
- Assess trading capacity before placing new orders
- Get a consolidated view of account performance

This provides essential information about account standing and
trading capacity to inform risk management decisions.

Example use cases:
- Checking available margin before placing new orders
- Monitoring account health during market volatility
- Assessing total exposure across all markets
- Understanding maintenance margin requirements
- Planning position adjustments based on account metrics

Implementation Reference

• src/mcp_paradex/tools/vaults.py:319-357 (handler)

  The primary handler function for the paradex_vault_account_summary tool. It accepts a vault_address parameter, calls the Paradex API via api_call to retrieve the account summary, validates the JSON response using a Pydantic TypeAdapter for list[VaultAccountSummary], handles errors, and returns the validated summary list.

  @server.tool(name="paradex_vault_account_summary")
  async def get_vault_account_summary(
      vault_address: Annotated[
          str, Field(description="The address of the vault to get account summary for.")
      ],
  ) -> list[VaultAccountSummary]:
      """
      Get a comprehensive overview of a vault's trading account status.
  
      Use this tool when you need to:
      - Check account health and available margin
      - Monitor total exposure and leverage
      - Understand risk metrics and account status
      - Assess trading capacity before placing new orders
      - Get a consolidated view of account performance
  
      This provides essential information about account standing and
      trading capacity to inform risk management decisions.
  
      Example use cases:
      - Checking available margin before placing new orders
      - Monitoring account health during market volatility
      - Assessing total exposure across all markets
      - Understanding maintenance margin requirements
      - Planning position adjustments based on account metrics
      """
      try:
          client = await get_paradex_client()
          response = await api_call(
              client, "vaults/account-summary", params={"address": vault_address}
          )
          if "error" in response:
              raise Exception(response["error"])
          results = response["results"]
          summary = vault_account_summary_adapter.validate_python(results)
          return summary
      except Exception as e:
          logger.error(f"Error fetching account summary for vault {vault_address}: {e!s}")
          raise e

• src/mcp_paradex/models.py:385-399 (schema)

  Pydantic BaseModel defining the output schema for the tool response. Specifies fields like address, deposited_amount, vtoken_amount, total_roi, total_pnl, and created_at with descriptions and types.

  class VaultAccountSummary(BaseModel):
      """Model representing an account summary for a vault."""
  
      address: Annotated[str, Field(description="Contract address of the vault")]
      deposited_amount: Annotated[
          str, Field(description="Amount deposited on the vault by the user in USDC")
      ]
      vtoken_amount: Annotated[str, Field(description="Amount of vault tokens owned by the user")]
      total_roi: Annotated[
          str, Field(description="Total ROI realized by the user in percentage, i.e. 0.1 means 10%")
      ]
      total_pnl: Annotated[str, Field(description="Total P&L realized by the user in USD")]
      created_at: Annotated[
          int, Field(description="Unix timestamp in milliseconds of when the user joined the vault")
      ]

• src/mcp_paradex/tools/vaults.py:316-316 (helper)

  Pydantic TypeAdapter used in the handler to validate the API response as a list of VaultAccountSummary objects.

  vault_account_summary_adapter = TypeAdapter(list[VaultAccountSummary])

• src/mcp_paradex/tools/vaults.py:319-319 (registration)

  Decorator that registers the get_vault_account_summary function as an MCP tool with the specified name.

  @server.tool(name="paradex_vault_account_summary")