Spot Balances

Description

Returns all (token, available, frozen) rows the authenticated user holds in the spot wallet. Includes every token the wallet has ever credited — both base (DF) and quote (USDT) — even if the balance is zero.

HTTP Request

GET /spot/balances (JWT or API Key)

Weight

0 — no per-IP weight limit today (MVP).

Response Example

200 OK

{
  "balances": [
    { "token": "DF",   "available": "1234.5",  "frozen": "0"   },
    { "token": "USDT", "available": "5000",    "frozen": "100" }
  ]
}

Field	Notes
balances	One entry per token the user has ever held. May be empty.
balances[].token	Token symbol — currently DF or USDT.
balances[].available	Withdrawable / transferable balance. Decimal string — never scientific notation. Trailing zeros are stripped (1234.50000000000000 → 1234.5).
balances[].frozen	Amount reserved for in-flight withdrawals. Decimal string.

Error Responses

HTTP	error
401	(empty body) — missing or invalid credential.
500	internal error — unexpected database error.

Full list: Error Codes.

Code Examples

cURL (JWT)

JWT="your_jwt_token"

curl -s "https://api-sepolia.p99.world/api/v1/spot/balances" \
  -H "Authorization: Bearer ${JWT}"

cURL (HMAC API Key)

API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s%3N)
PAYLOAD="timestamp=${TIMESTAMP}"
SIGNATURE=$(echo -n "${PAYLOAD}" | openssl dgst -sha256 -hmac "${API_SECRET}" | awk '{print $2}')

curl -s \
  -H "X-MBX-APIKEY: ${API_KEY}" \
  "https://api-sepolia.p99.world/api/v1/spot/balances?timestamp=${TIMESTAMP}&signature=${SIGNATURE}"

Python

import time, hmac, hashlib, requests

API_KEY    = "your_api_key"
API_SECRET = "your_api_secret"
BASE_URL   = "https://api-sepolia.p99.world/api/v1"

def signed_get(path: str) -> dict:
    ts = int(time.time() * 1000)
    payload = f"timestamp={ts}"
    sig = hmac.new(API_SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()
    r = requests.get(
        f"{BASE_URL}{path}?timestamp={ts}&signature={sig}",
        headers={"X-MBX-APIKEY": API_KEY},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

data = signed_get("/spot/balances")
for b in data["balances"]:
    print(f"  {b['token']:5}  available={b['available']:>14}  frozen={b['frozen']}")