MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/vaults.py:123-148 (handler)

  The main execution logic for the 'paradex_vault_balance' tool. Fetches vault balance data from Paradex API, validates it using Pydantic TypeAdapter, and returns list of VaultBalance objects.
  @server.tool(name="paradex_vault_balance") async def get_vault_balance( vault_address: Annotated[ str, Field(description="The address of the vault to get balance for.") ], ) -> list[VaultBalance]: """ Get the current balance of a specific vault. Retrieves the current balance information for a specific vault, including available funds, locked funds, and total balance. This is essential for understanding the financial state of a vault before executing trades or withdrawals. """ try: client = await get_paradex_client() response = await api_call(client, "vaults/balance", params={"address": vault_address}) if "error" in response: raise Exception(response["error"]) results = response["results"] balances = vault_balance_adapter.validate_python(results) return balances except Exception as e: logger.error(f"Error fetching balance for vault {vault_address}: {e!s}") raise e
• src/mcp_paradex/models.py:265-271 (schema)

  Pydantic BaseModel defining the structure and validation for VaultBalance output objects returned by the tool.
  class VaultBalance(BaseModel): """Model representing the balance of a vault.""" token: Annotated[str, Field(description="Name of the token")] size: Annotated[str, Field(description="Balance amount of settlement token")] last_updated_at: Annotated[int, Field(description="Balance last updated time")]
• src/mcp_paradex/tools/vaults.py:123-123 (registration)

  The @server.tool decorator registers the get_vault_balance function as the MCP tool named 'paradex_vault_balance'.
  @server.tool(name="paradex_vault_balance")
• src/mcp_paradex/resources/vaults.py:85-113 (helper)

  Supporting resource endpoint that performs the actual API call to Paradex for vault balance data, invoked indirectly by the tool handler.
  @server.resource("paradex://vaults/balance/{vault_id}") async def get_vault_balance(vault_id: str) -> dict[str, Any]: """ Get a summary of market information for a specific trading pair. This endpoint requires authentication and provides detailed information about the market, including order book, ticker, and market statistics. Args: market_id (str): The ID of the trading pair to get summary for. Returns: Dict[str, Any]: Summary of market information. """ try: # Get market summary from Paradex client = await get_paradex_client() summary = await api_call(client, "vaults/balance", params={"address": vault_id}) return summary except Exception as e: logger.error(f"Error fetching market summary: {e!s}") return { "success": False, "timestamp": datetime.now().isoformat(), "environment": config.ENVIRONMENT, "error": str(e), "summary": None, }
• src/mcp_paradex/tools/vaults.py:120-120 (schema)

  TypeAdapter for list[VaultBalance] used for input validation/parsing of the API response in the handler.
  vault_balance_adapter = TypeAdapter(list[VaultBalance])