paradex_vault_balance

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])