Get Balance by Exchange
curl --request GET \
--url https://api.tide.ag/api/trading/{exchange}/balances \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.tide.ag/api/trading/{exchange}/balances"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.tide.ag/api/trading/{exchange}/balances', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tide.ag/api/trading/{exchange}/balances",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tide.ag/api/trading/{exchange}/balances"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tide.ag/api/trading/{exchange}/balances")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tide.ag/api/trading/{exchange}/balances")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"success": true,
"exchange": "hyperliquid",
"address": "<string>",
"balances": [
{
"asset": "USDC",
"free": "<string>",
"locked": "<string>",
"total": "<string>",
"crossWalletBalance": "<string>",
"crossUnPnl": "<string>",
"maxWithdrawAmount": "<string>"
}
],
"withdrawable": "<string>",
"accountValue": "<string>"
},
"timestamp": 123
}{
"success": false,
"error": "Missing required query parameter: walletAddress",
"timestamp": 123
}{
"success": false,
"data": {
"success": false,
"exchange": "aster",
"address": "<string>",
"error": "Aster API credentials not configured",
"hint": "Set ASTER_API_KEY and ASTER_API_SECRET environment variables"
},
"timestamp": 123
}{
"success": false,
"data": {
"success": false,
"exchange": "<string>",
"address": "<string>",
"error": "Account not found. Please register on Lighter first.",
"hint": "Visit https://app.lighter.xyz to create an account"
},
"timestamp": 123
}Account
Get Account Balances
Returns balance data for a specific exchange and wallet address. Supports Hyperliquid, Lighter, Aster, and Avantis.
GET
/
api
/
trading
/
{exchange}
/
balances
Get Balance by Exchange
curl --request GET \
--url https://api.tide.ag/api/trading/{exchange}/balances \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.tide.ag/api/trading/{exchange}/balances"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.tide.ag/api/trading/{exchange}/balances', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tide.ag/api/trading/{exchange}/balances",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tide.ag/api/trading/{exchange}/balances"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tide.ag/api/trading/{exchange}/balances")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tide.ag/api/trading/{exchange}/balances")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"success": true,
"exchange": "hyperliquid",
"address": "<string>",
"balances": [
{
"asset": "USDC",
"free": "<string>",
"locked": "<string>",
"total": "<string>",
"crossWalletBalance": "<string>",
"crossUnPnl": "<string>",
"maxWithdrawAmount": "<string>"
}
],
"withdrawable": "<string>",
"accountValue": "<string>"
},
"timestamp": 123
}{
"success": false,
"error": "Missing required query parameter: walletAddress",
"timestamp": 123
}{
"success": false,
"data": {
"success": false,
"exchange": "aster",
"address": "<string>",
"error": "Aster API credentials not configured",
"hint": "Set ASTER_API_KEY and ASTER_API_SECRET environment variables"
},
"timestamp": 123
}{
"success": false,
"data": {
"success": false,
"exchange": "<string>",
"address": "<string>",
"error": "Account not found. Please register on Lighter first.",
"hint": "Visit https://app.lighter.xyz to create an account"
},
"timestamp": 123
}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.
Example Request:
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
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
curl -X GET "https://api.tide.ag/api/trading/lighter/balances?walletAddress=0xE7bECcEC683a6e141EaD23237088CfbC348b2295" \
-H "Content-Type: application/json"
Response Example
Hyperliquid
{
"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
{
"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
{
"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
curl -X GET "https://api.tide.ag/api/balances/0xabc123..." \
-H "Content-Type: application/json"
Avantis Response
{
"success": true,
"data": {
"avantis": {
"usdc": "500.00",
"availableBalance": "350.00"
}
}
}
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.Aster Endpoint
GET /api/aster/perp/:walletId/account
Path Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
walletId | string | Yes | Wallet ID (UUID) |
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)
Aster requires
ASTER_API_KEY and ASTER_API_SECRET environment variables to be configured on the API server.Response Fields
Common Fields (All Exchanges)
success— Request statusexchange— Exchange identifieraddress— Wallet address (checksum format)balances— Array of asset balancestimestamp— Unix timestamp in milliseconds
Balance Object Fields
asset— Asset symbol (e.g., USDC)free— Available balance for tradingtotal— Total balance (free + locked)locked— Balance locked in orders/positions (Aster only)
Exchange-Specific Fields
Hyperliquid:withdrawable— Amount available for withdrawalaccountValue— Total account value including positions
accountIndex— Lighter account indexcollateral— Total collateralavailableBalance— Available for new positionsaccountType— Account type (standard/isolated)
accountType— Account type (futures/spot)crossWalletBalance— Cross margin balancecrossUnPnl— Unrealized PnLmaxWithdrawAmount— Maximum withdrawable amount
usdc— Total USDC balance on BaseavailableBalance— 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
For real-time balance updates when orders execute or positions change, use the WebSocket
balances topic.Authorizations
Path Parameters
Exchange name
Available options:
hyperliquid, lighter, aster, avantis Query Parameters
EVM wallet address (0x...)