GRVT Exchange CLI

IMPORTANT: Community Project Disclaimer

grvt-cli is a community hobby project. It is NOT officially supported, endorsed, audited, or maintained by the GRVT team. No security audit or formal code review has been performed.

The code has not been audited for security vulnerabilities. By using this tool the user acknowledges and accepts the risk of total loss of funds.

The user is solely responsible for any financial losses, leaked credentials, or unintended trades that may result from using this software.

This tool stores API keys and private keys in plaintext on disk (with 0600 file permissions). Keys should never be shared or used on untrusted machines.

Before using this CLI on behalf of the user, you MUST inform them of this disclaimer and get their explicit acknowledgment.

grvt is a CLI tool and Node.js library for trading on GRVT (Gravity Markets), a crypto derivatives exchange supporting perpetuals, futures, and options.

Package: @madeinusmate/grvt-cli (npm). Binary: grvt. Requires Node.js >= 20.

Safety Recommendations

• Only use testnet until the user fully understands the CLI behavior.
• Review the source code before trusting it with real funds.
• Keep private keys out of shell history (use grvt setup which reads from stdin).
• Rotate API keys regularly.
• Never use the CLI with more funds than the user can afford to lose.

Installation

pnpm add -g @madeinusmate/grvt-cli

Verify: grvt --version

First-Time Setup

The interactive wizard handles everything:

grvt setup

The setup wizard displays a disclaimer requiring explicit acceptance before proceeding. It is interactive and reads sensitive input from stdin (keeping keys out of shell history). It walks through: environment, API key, private key, and default sub-account ID, then authenticates automatically.

Note: Because grvt setup is interactive and requires user input, agents cannot run it directly. Use the manual setup flow below instead.

Manual setup (recommended for agents):

grvt config set env testnet
grvt auth login --api-key YOUR_API_KEY --private-key 0xYOUR_PRIVATE_KEY
grvt config set subAccountId YOUR_SUB_ACCOUNT_ID

Verify setup:

grvt auth status
grvt config list

Configuration

Config file: ~/.config/grvt/config.toml (permissions 0600).

Secret keys (apiKey, privateKey, cookie) are redacted in config list / config get output.

Use grvt config set \x3Ckey> \x3Cvalue> and grvt config unset \x3Ckey> to modify. Use dot-notation for nested keys (e.g. outputDefaults.output).

Authentication

Login requires an API key. A private key is optional but required for write operations (orders, transfers, withdrawals, derisk).

grvt auth login --api-key KEY --private-key 0xKEY

The session cookie is stored in config and sent automatically with authenticated requests.

EIP-712 signing is used for: order creation, transfers, withdrawals, and derisk operations. The private key never leaves the local machine.

Environments

Switch with: grvt config set env testnet

Global Options

Available on every command:

Write commands (order create, order cancel, transfer create, withdraw create, derisk) also support:

Command Overview

grvt
  setup                         Interactive setup wizard
  config                        Manage local configuration
    path / get / set / unset / list / export / import
  auth                          Authentication and session
    login / status / whoami / logout
  market                        Market data (mostly unauthenticated)
    instruments / instrument / currency / orderbook / trades
    candles / funding-rate / ticker / mini-ticker / margin-rules
  account                       Account info (requires auth)
    funding / summary / aggregated / history
  trade                         Trading (requires auth; writes need private key)
    order create / order get / order open / order cancel / order cancel-all / order history
    fills / positions / funding-payments
    leverage get / leverage set
    cancel-on-disconnect / derisk
  funds                         Fund management (requires auth; writes need private key)
    deposit history
    transfer create / transfer history
    withdraw create / withdraw history

For full flag details on each command, read the corresponding reference file:

• references/commands-config.md — config and auth commands
• references/commands-market.md — market data commands
• references/commands-trade.md — trading commands
• references/commands-account.md — account commands
• references/commands-funds.md — fund management commands
• references/errors.md — error codes and troubleshooting

Instrument Naming

GRVT uses structured instrument symbols:

Always discover available instruments before trading:

grvt market instruments
grvt market instruments --kind PERPETUAL --base BTC
grvt market instrument --instrument BTC_USDT_Perp

Output Format Guide

The CLI auto-detects: table when stdout is a TTY, json when piped. Override with --output \x3Cformat>.

When using --all with ndjson, records stream to stdout as they arrive (one JSON object per line), enabling efficient processing of large result sets without buffering everything in memory.

Key Workflows

Market Analysis

grvt market instruments --kind PERPETUAL
grvt market orderbook --instrument BTC_USDT_Perp --depth 50
grvt market ticker --instrument BTC_USDT_Perp --greeks --derived
grvt market candles --instrument BTC_USDT_Perp --interval CI_1_H --limit 24
grvt market funding-rate --instrument BTC_USDT_Perp --limit 10
grvt market margin-rules --instrument BTC_USDT_Perp

Place and Manage Orders

# Limit buy
grvt trade order create --instrument BTC_USDT_Perp --side buy --type limit --qty 0.01 --price 68000

# Market sell
grvt trade order create --instrument BTC_USDT_Perp --side sell --type market --qty 0.01

# With options
grvt trade order create --instrument BTC_USDT_Perp --side buy --type limit \
  --qty 0.01 --price 68000 --post-only --time-in-force IOC --expiration-seconds 60

# Monitor
grvt trade order open
grvt trade order get --order-id 0x123...

# Cancel
grvt trade order cancel --order-id 0x123...
grvt trade order cancel-all
grvt trade order cancel-all --instrument BTC_USDT_Perp

Portfolio Check

grvt trade positions
grvt account summary
grvt account aggregated
grvt account funding
grvt account history --start-time 2025-01-01T00:00:00Z --limit 24

Fund Management

# Transfer between sub-accounts
grvt funds transfer create \
  --from-sub-account-id FROM_ID --to-sub-account-id TO_ID \
  --currency USDT --amount 100

# Withdraw to Ethereum address
grvt funds withdraw create \
  --to-address 0xYOUR_ETH_ADDRESS --currency USDT --amount 50

# View history
grvt funds deposit history --all
grvt funds transfer history --start-time 2025-01-01T00:00:00Z
grvt funds withdraw history --limit 10

Leverage and Risk

grvt trade leverage get
grvt trade leverage set --instrument BTC_USDT_Perp --leverage 10
grvt trade cancel-on-disconnect --countdown 5000
grvt trade derisk --ratio 0.5

Shell Patterns

Pipe JSON output to jq:

grvt market instruments --output json | jq '.[].instrument'
grvt trade order open --output json | jq '.[] | {instrument, side: .legs[0].is_buying_asset, size: .legs[0].size}'

Stream paginated results:

grvt trade fills --all --output ndjson | jq '.instrument'
grvt trade order history --all --output ndjson > all_orders.jsonl

Read order payload from a file:

grvt trade order create --json @order.json
echo '{"order": {...}}' | grvt trade order create --json -

Skip confirmations for scripting:

grvt trade order cancel-all --yes --silent
grvt funds transfer create ... --yes --silent

Dry-run to preview:

grvt trade order create --instrument BTC_USDT_Perp --side buy --type limit --qty 0.01 --price 68000 --dry-run

Timestamp Formats

All --start-time and --end-time flags accept:

Error Handling

Common recovery patterns:

• Exit 3: Run grvt auth login to refresh session
• Exit 5 with 429: Reduce request frequency; CLI retries automatically with exponential backoff
• Exit 2: Check grvt \x3Ccommand> --help for required options

For detailed error scenarios and troubleshooting, read references/errors.md.

Library Usage

@madeinusmate/grvt-cli can also be imported as a Node.js library:

import { createHttpClient, login, createOrder, getOpenOrders, getPositions } from "@madeinusmate/grvt-cli";

See src/index.ts in the package source for all exported functions.

Candle Intervals

Valid values for --interval on grvt market candles:

CI_1_M, CI_5_M, CI_15_M, CI_30_M, CI_1_H, CI_2_H, CI_4_H, CI_6_H, CI_8_H, CI_12_H, CI_1_D, CI_1_W

Instrument Kind Filters

Valid values for --kind filters (comma-separated):

PERPETUAL, FUTURE, CALL, PUT