GRVT Account Management

When to Use

Use this skill when the user wants to:

• Check account balance or portfolio value
• View open positions and unrealized PnL
• Manage position margin (add margin, check limits)
• View trade/fill history
• Check funding payment history

Prerequisites

pip install grvt-pysdk

All account endpoints require authentication. GRVT has two types of API keys:

# Trading API Key — for balances, positions, trade history
export GRVT_TRADING_API_KEY="<Trading API Key from GRVT exchange UI>"
export GRVT_TRADING_PRIVATE_KEY="<private key associated with Trading API Key>"

# Funding API Key — for funding account transfers
export GRVT_FUNDING_API_KEY="<Funding API Key from GRVT exchange UI>"
export GRVT_FUNDING_PRIVATE_KEY="<private key associated with Funding API Key>"

export GRVT_ENV="testnet"  # or "prod"

Both key types can be created at:

• Production: https://exchange.grvt.io/exchange/account/api-keys
• Testnet: https://exchange.testnet.grvt.io/exchange/account/api-keys

This skill primarily uses GRVT_TRADING_API_KEY. Use GRVT_FUNDING_API_KEY only for funding account transfers.

SDK Setup

Login to auto-detect trading_account_id and funding_account_address:

import os
import requests
from pathlib import Path
from pysdk.grvt_ccxt import GrvtCcxt
from pysdk.grvt_ccxt_env import GrvtEnv

# Load .env file if present
env_file = Path(".env")
if env_file.exists():
    for line in env_file.read_text().splitlines():
        line = line.strip()
        if line and not line.startswith("#") and "=" in line:
            key, _, value = line.partition("=")
            os.environ.setdefault(key.strip(), value.strip())

env = os.getenv("GRVT_ENV", "testnet")
base = "edge.testnet.grvt.io" if env == "testnet" else "edge.grvt.io"

# Login with Trading API Key
login_resp = requests.post(
    f"https://{base}/auth/api_key/login",
    json={"api_key": os.getenv("GRVT_TRADING_API_KEY")},
).json()
trading_account_id = login_resp["sub_account_id"]
funding_account_address = login_resp["funding_account_address"]

api = GrvtCcxt(
    env=GrvtEnv.TESTNET if env == "testnet" else GrvtEnv.PRODUCTION,
    parameters={
        "api_key": os.getenv("GRVT_TRADING_API_KEY"),
        "trading_account_id": trading_account_id,
        "private_key": os.getenv("GRVT_TRADING_PRIVATE_KEY"),
    },
)

# For funding account operations, login with Funding API Key instead:
# login_resp = requests.post(
#     f"https://{base}/auth/api_key/login",
#     json={"api_key": os.getenv("GRVT_FUNDING_API_KEY")},
# ).json()

Account Balance

# Get account balance
balance = api.fetch_balance()
# Top-level keys: info, timestamp, datetime, total, free, used, USDT
print(f"USDT Total: {balance['total']['USDT']}")
print(f"USDT Free:  {balance['free']['USDT']}")
print(f"USDT Used:  {balance['used']['USDT']}")

# Detailed info per currency in balance["info"]
for entry in balance["info"]:
    print(f"{entry['currency']}: balance={entry['balance']}, unrealized_pnl={entry['unrealized_pnl']}")

Account Summary

# Sub-account summary — balances, margin usage, equity
summary = api.get_account_summary(type="sub-account")

# Aggregated summary across all sub-accounts
agg_summary = api.get_account_summary(type="aggregated")

Positions

# Fetch all open positions
positions = api.fetch_positions()

# Fetch positions for specific symbols
positions = api.fetch_positions(symbols=["BTC_USDT_Perp", "ETH_USDT_Perp"])

for pos in positions:
    side = "long" if float(pos["size"]) > 0 else "short"
    print(f"{pos['instrument']}: size={pos['size']} side={side}")
    print(f"  Entry: {pos['entry_price']}, Mark: {pos['mark_price']}")
    print(f"  Unrealized PnL: {pos['unrealized_pnl']}, ROI: {pos['roi']}%")
    print(f"  Leverage: {pos['leverage']}x, Margin: {pos['margin_type']}")

Position Margin Management

# Add margin to a position (reduce liquidation risk)
api.add_position_margin(
    symbol="BTC_USDT_Perp",
    amount=100,  # Additional USDT margin
)

# Check margin limits
limits = api.get_position_margin_limits(symbol="BTC_USDT_Perp")

Trade / Fill History

# Recent fills
fills = api.fetch_my_trades(symbol="BTC_USDT_Perp", limit=50)
for fill in fills:
    side = "buy" if fill.get("is_taker_buyer") else "sell"
    print(f"{side} {fill['size']} @ {fill['price']} — trade_id: {fill['trade_id']}")

Funding Payment History

# Check funding payments received/paid on perpetual positions
funding = api.fetch_funding_payment_history(symbol="BTC_USDT_Perp", limit=24)
for f in funding:
    print(f"Payment: {f['amount']} at {f['datetime']}")

Account History

# Full account history (deposits, withdrawals, transfers, settlements)
history = api.fetch_account_history()

Common Patterns

Portfolio Overview

def portfolio_overview(api):
    balance = api.fetch_balance()
    positions = api.fetch_positions()

    print(f"Account Balance: {balance['total']['USDT']} USDT")
    print(f"Available: {balance['free']['USDT']} USDT")
    print(f"\nOpen Positions ({len(positions)}):")
    total_pnl = 0
    for pos in positions:
        pnl = float(pos.get("unrealized_pnl", 0))
        total_pnl += pnl
        side = "long" if float(pos["size"]) > 0 else "short"
        print(f"  {pos['instrument']}: {pos['size']} ({side})")
        print(f"    Entry: {pos['entry_price']} | PnL: {pnl}")
    print(f"\nTotal Unrealized PnL: {total_pnl}")

Important Notes

• All account data requires authentication — ensure env vars are set
• Position PnL is calculated against current mark price
• Funding payments occur at regular intervals on perpetual positions (typically every 8 hours)
• Use GrvtEnv.TESTNET for testing before production