paradex_vault_balance

Retrieve current balance information for a specific vault on the Paradex platform, including available funds, locked funds, and total balance to assess financial state before trades or withdrawals.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`vault_address`	Yes	The address of the vault to get balance for.

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

MCP Paradex Server