> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tide.ag/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Account Balances

> Returns balance data for a specific exchange and wallet address. Supports Hyperliquid, Lighter, Aster, and Avantis.

Retrieve account balances for a specific exchange and wallet address. This endpoint provides detailed balance information including available, locked, and total amounts for each asset.

## Features

* **Multi-exchange support**: Query balances from Hyperliquid, Lighter, Aster, and Avantis
* **Wallet-based queries**: Fetch balances for any EVM wallet address
* **Detailed balance breakdown**: Free, locked, and total amounts per asset
* **Exchange-specific fields**: Additional metadata like collateral, account index, and PnL

## Request

* **Method**: `GET`
* **Endpoint**: `/api/trading/{exchange}/balances`
* **Path Parameters**: `exchange` (required - hyperliquid, lighter, aster, or avantis)
* **Headers**: `x-wallet-id` (required for Hyperliquid - Wallet UUID)
* **Query Parameters**: `walletAddress` (required for Lighter/Aster - EVM wallet address)

### Hyperliquid

```bash theme={null}
curl -X GET "https://api.tide.ag/api/trading/hyperliquid/balances" \
  -H "x-wallet-id: a1e82339-29f8-41a6-a468-ce8d268a3261" \
  -H "Content-Type: application/json"
```

### Lighter / Aster

```bash theme={null}
curl -X GET "https://api.tide.ag/api/trading/lighter/balances?walletAddress=0xE7bECcEC683a6e141EaD23237088CfbC348b2295" \
  -H "Content-Type: application/json"
```

## Response Example

### Hyperliquid

```json theme={null}
{
  "success": true,
  "data": {
    "exchange": "hyperliquid",
    "address": "a1e82339-29f8-41a6-a468-ce8d268a3261",
    "balances": [
      {
        "asset": "USDC",
        "free": "7.083528",
        "locked": "0",
        "total": "7.083528"
      }
    ]
  },
  "timestamp": 1764687746160
}
```

### Lighter

```json theme={null}
{
  "success": true,
  "data": {
    "success": true,
    "exchange": "lighter",
    "address": "0xE7bECcEC683a6e141EaD23237088CfbC348b2295",
    "accountIndex": 316225,
    "balances": [
      {
        "asset": "USDC",
        "free": "5.014025",
        "total": "5.014025"
      }
    ],
    "collateral": "5.014025",
    "availableBalance": "0",
    "accountType": "standard"
  },
  "timestamp": 1762764977739
}
```

### Aster

```json theme={null}
{
  "success": true,
  "data": {
    "feeTier": 0,
    "canTrade": true,
    "canDeposit": true,
    "canWithdraw": true,
    "updateTime": 0,
    "totalInitialMargin": "0.00000000",
    "totalMaintMargin": "0.00000000",
    "totalWalletBalance": "4.52534689",
    "totalUnrealizedProfit": "0.00000000",
    "totalMarginBalance": "4.52534689",
    "totalPositionInitialMargin": "0.00000000",
    "totalOpenOrderInitialMargin": "0.00000000",
    "totalCrossWalletBalance": "4.52534689",
    "totalCrossUnPnl": "0.00000000",
    "availableBalance": "4.52444185",
    "maxWithdrawAmount": "4.52534689",
    "assets": []
  }
}
```

### Avantis

```bash theme={null}
curl -X GET "https://api.tide.ag/api/balances/0xabc123..." \
  -H "Content-Type: application/json"
```

### Avantis Response

```json theme={null}
{
  "success": true,
  "data": {
    "avantis": {
      "usdc": "500.00",
      "availableBalance": "350.00"
    }
  }
}
```

<Note>
  The Avantis balance endpoint uses `/api/balances/:walletAddress` (not the exchange-specific path). The `usdc` field represents total USDC on Base, while `availableBalance` is total minus deployed collateral.
</Note>

***

### Aster Endpoint

`GET /api/aster/perp/:walletId/account`

**Path Parameters:**

| Parameter  | Type   | Required | Description      |
| ---------- | ------ | -------- | ---------------- |
| `walletId` | string | Yes      | Wallet ID (UUID) |

**Example Request:**

```bash theme={null}
curl -X GET https://api.tide.ag/api/aster/perp/ee337309-3e77-4278-b21a-4681468168ba/account \
  -H "Content-Type: application/json"
```

## Use Cases

* Display account overview and portfolio value across exchanges
* Validate order placement against available balance
* Monitor asset distribution across multiple venues
* Track collateral and margin requirements

## Authentication

* **Hyperliquid**: No authentication required (public API)
* **Lighter**: No authentication required (public API)
* **Aster**: Requires HMAC-SHA256 credentials configured on the server
* **Avantis**: No authentication required (public API, wallet address only)

<Note>
  Aster requires `ASTER_API_KEY` and `ASTER_API_SECRET` environment variables to be configured on the API server.
</Note>

## Response Fields

### Common Fields (All Exchanges)

* `success` — Request status
* `exchange` — Exchange identifier
* `address` — Wallet address (checksum format)
* `balances` — Array of asset balances
* `timestamp` — Unix timestamp in milliseconds

### Balance Object Fields

* `asset` — Asset symbol (e.g., USDC)
* `free` — Available balance for trading
* `total` — Total balance (free + locked)
* `locked` — Balance locked in orders/positions (Aster only)

### Exchange-Specific Fields

**Hyperliquid:**

* `withdrawable` — Amount available for withdrawal
* `accountValue` — Total account value including positions

**Lighter:**

* `accountIndex` — Lighter account index
* `collateral` — Total collateral
* `availableBalance` — Available for new positions
* `accountType` — Account type (standard/isolated)

**Aster:**

* `accountType` — Account type (futures/spot)
* `crossWalletBalance` — Cross margin balance
* `crossUnPnl` — Unrealized PnL
* `maxWithdrawAmount` — Maximum withdrawable amount

**Avantis:**

* `usdc` — Total USDC balance on Base
* `availableBalance` — Available balance (total minus deployed collateral)

## Address Format

All wallet addresses are automatically converted to checksum format. You can provide addresses in any format:

* Lowercase: `0xe7beccec683a6e141ead23237088cfbc348b2295`
* Uppercase: `0xE7BECCEC683A6E141EAD23237088CFBC348B2295`
* Checksum: `0xE7bECcEC683a6e141EaD23237088CfbC348b2295`

<Tip>
  For real-time balance updates when orders execute or positions change, use the WebSocket `balances` topic.
</Tip>


## OpenAPI

````yaml GET /api/trading/{exchange}/balances
openapi: 3.1.0
info:
  title: Tide API
  description: >-
    Decentralized Perpetual Aggregator API for multi-exchange trading across
    Hyperliquid, Aster, Lighter, and Pacifica
  version: 1.0.0
  contact:
    name: Tide Support
    email: support@tide.ag
    url: https://tide.ag
  license:
    name: MIT
servers:
  - url: https://api.tide.ag
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Market Data
    description: Public market data endpoints
  - name: Trading
    description: Order placement and management
  - name: Positions
    description: Position management and history
  - name: Account
    description: Account and balance management
  - name: System
    description: System status and health
paths:
  /api/trading/{exchange}/balances:
    get:
      tags:
        - Account
      summary: Get Balance by Exchange
      description: >-
        Returns balance data for a specific exchange and wallet address.
        Supports Hyperliquid, Lighter, Aster, and Avantis.
      parameters:
        - name: exchange
          in: path
          required: true
          schema:
            type: string
            enum:
              - hyperliquid
              - lighter
              - aster
              - avantis
          description: Exchange name
        - name: walletAddress
          in: query
          required: true
          schema:
            type: string
          description: EVM wallet address (0x...)
      responses:
        '200':
          description: Balance data for the specified exchange
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/HyperliquidBalanceResponse'
                  - $ref: '#/components/schemas/LighterBalanceResponse'
                  - $ref: '#/components/schemas/AsterBalanceResponse'
        '400':
          description: Bad request - missing or invalid wallet address
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'Missing required query parameter: walletAddress'
                  timestamp:
                    type: integer
        '401':
          description: Missing credentials (Aster only)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      exchange:
                        type: string
                        example: aster
                      address:
                        type: string
                      error:
                        type: string
                        example: Aster API credentials not configured
                      hint:
                        type: string
                        example: >-
                          Set ASTER_API_KEY and ASTER_API_SECRET environment
                          variables
                  timestamp:
                    type: integer
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: false
                      exchange:
                        type: string
                      address:
                        type: string
                      error:
                        type: string
                        example: Account not found. Please register on Lighter first.
                      hint:
                        type: string
                        example: Visit https://app.lighter.xyz to create an account
                  timestamp:
                    type: integer
      security: []
components:
  schemas:
    HyperliquidBalanceResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            success:
              type: boolean
            exchange:
              type: string
              enum:
                - hyperliquid
            address:
              type: string
              description: Wallet address in checksum format
            balances:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
            withdrawable:
              type: string
              description: Amount available for withdrawal
            accountValue:
              type: string
              description: Total account value including positions
        timestamp:
          type: integer
          description: Unix timestamp in milliseconds
    LighterBalanceResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            success:
              type: boolean
            exchange:
              type: string
              enum:
                - lighter
            address:
              type: string
              description: Wallet address in checksum format
            accountIndex:
              type: integer
              description: Lighter account index
            balances:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
            collateral:
              type: string
              description: Total collateral
            availableBalance:
              type: string
              description: Available for new positions
            accountType:
              type: string
              enum:
                - standard
                - isolated
              description: Account type
        timestamp:
          type: integer
          description: Unix timestamp in milliseconds
    AsterBalanceResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            success:
              type: boolean
            exchange:
              type: string
              enum:
                - aster
            address:
              type: string
              description: Wallet address in checksum format
            balances:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
            accountType:
              type: string
              enum:
                - futures
                - spot
              description: Account type
        timestamp:
          type: integer
          description: Unix timestamp in milliseconds
    Balance:
      type: object
      properties:
        asset:
          type: string
          example: USDC
          description: Asset symbol
        free:
          type: string
          description: Available balance for trading
        locked:
          type: string
          description: Balance locked in orders/positions
        total:
          type: string
          description: Total balance (free + locked)
        crossWalletBalance:
          type: string
          description: Cross margin balance (Aster only)
        crossUnPnl:
          type: string
          description: Unrealized PnL (Aster only)
        maxWithdrawAmount:
          type: string
          description: Maximum withdrawable amount (Aster only)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key for authentication. Also requires X-API-SECRET, X-API-TIMESTAMP,
        and X-API-SIGNATURE headers for private endpoints.

````