@2oolkit/grvt-cli

Trade perpetual futures on GRVT — a hybrid decentralized derivatives exchange on ZKsync — from your terminal or AI agent.

One package, three interfaces:

Interface	Command	Use Case
CLI	`grvt-cli`	Terminal trading, scripting, automation
MCP Server	`grvt-mcp`	AI agents (Claude, Cursor, Windsurf, etc.)
OpenClaw Skill	`skill/SKILL.md`	AI agent ecosystem (OpenClaw, ClawdBot)

90+ perpetual instruments: crypto (BTC, ETH, SOL), equities (TSLA, AMZN), commodities (XAU, XAG).

Installation

npm install -g @2oolkit/grvt-cli

This installs both grvt-cli (CLI) and grvt-mcp (MCP server).

Prerequisites

Node.js >= 20
A GRVT account at grvt.io
An API key (Dashboard > Settings > API Keys)

CLI Usage

Quick Start

# 1. Interactive setup (prompts for API key, secret, sub-account ID)
grvt-cli config init

# 2. Check a price (no auth needed)
grvt-cli market ticker BTC_USDT_Perp

# 3. Place a limit buy
grvt-cli order create --instrument BTC_USDT_Perp --side buy --size 0.001 --price 60000

# 4. View open orders
grvt-cli order list

Configuration

Interactive setup (recommended):

grvt-cli config init

Prompts for:

Prompt	Description	Where to find it
API Key	Your GRVT API key	Dashboard > Settings > API Keys
API Secret	Private key for EIP-712 signing	Shown once when creating API key
Sub-account ID	Numeric sub-account ID	Dashboard > Sub-accounts

Manual setup:

grvt-cli config set --api-key <key> --api-secret <secret> --sub-account-id <id>
grvt-cli auth login

Environment variables (CI/CD, Docker):

export GRVT_API_KEY=<your-api-key>
export GRVT_SECRET_KEY=<your-api-secret>
export GRVT_SUB_ACCOUNT_ID=<your-sub-account-id>

Command Reference

Market Data (no auth required)

grvt-cli market instruments                        # List all instruments
grvt-cli market instruments --kind PERPETUAL       # Filter by kind
grvt-cli market instruments --base BTC             # Filter by base currency
grvt-cli market ticker BTC_USDT_Perp               # Price, volume, funding
grvt-cli market orderbook BTC_USDT_Perp            # Orderbook (10 levels)
grvt-cli market orderbook BTC_USDT_Perp --depth 20 # 20 levels

Orders (auth required)

# Create
grvt-cli order create --instrument BTC_USDT_Perp --side buy --size 0.001 --price 60000
grvt-cli order create --instrument BTC_USDT_Perp --side sell --size 0.001 --type market
grvt-cli order create --instrument ETH_USDT_Perp --side buy --size 0.1 --price 3000 --post-only
grvt-cli order create --instrument BTC_USDT_Perp --side sell --size 0.01 --type market --reduce-only

# Manage
grvt-cli order list                                # Open orders
grvt-cli order get --order-id <id>                 # Order details
grvt-cli order cancel --order-id <id>              # Cancel one
grvt-cli order cancel-all                          # Cancel all
grvt-cli order history --limit 50                  # Order history

Order options:

Option	Required	Description	Default
`--instrument`	Yes	e.g., `BTC_USDT_Perp`	—
`--side`	Yes	`buy` or `sell`	—
`--size`	Yes	Size in base currency	—
`--type`	No	`limit` or `market`	`limit`
`--price`	Limit only	Limit price	—
`--post-only`	No	Maker-only	`false`
`--reduce-only`	No	Reduce-only	`false`
`--time-in-force`	No	`GOOD_TILL_TIME`, `IMMEDIATE_OR_CANCEL`, `FILL_OR_KILL`	`GOOD_TILL_TIME`
`--client-order-id`	No	Custom tracking ID	auto

Positions, Account & Funding

grvt-cli position list                             # All open positions
grvt-cli position list --kind PERPETUAL            # Filter by kind

grvt-cli account summary                           # Funding account
grvt-cli account sub-account                       # Sub-account (margin, balance)

grvt-cli funding rate BTC_USDT_Perp                # Current funding rate
grvt-cli funding history --limit 10                # Payment history

Auth & Config

grvt-cli auth login                                # Login
grvt-cli auth status                               # Check session
grvt-cli auth logout                               # Clear session

grvt-cli config init                               # Setup wizard
grvt-cli config set --api-key <key>                # Update config
grvt-cli config list                               # Show config (masked)
grvt-cli config get <key>                          # Get specific value

Output Formats

All commands support -o json for scripting and piping:

grvt-cli market ticker BTC_USDT_Perp -o json
grvt-cli order list -o json | jq '.[].order_id'

MCP Server

The MCP (Model Context Protocol) server exposes all GRVT functionality as tools for AI agents. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Setup for Claude Code

claude mcp add grvt-mcp -- grvt-mcp

Setup for Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

{
  "mcpServers": {
    "grvt": {
      "command": "grvt-mcp"
    }
  }
}

Or without global install:

{
  "mcpServers": {
    "grvt": {
      "command": "npx",
      "args": ["-y", "-p", "@2oolkit/grvt-cli", "grvt-mcp"]
    }
  }
}

Available Tools (17)

Category	Tools	Auth Required
Market Data	`get_instruments`, `get_ticker`, `get_orderbook`	No
Orders	`create_order`, `cancel_order`, `cancel_all_orders`, `get_order`, `list_open_orders`, `get_order_history`	Yes
Positions	`list_positions`	Yes
Account	`get_account_summary`, `get_sub_account_summary`	Yes
Funding	`get_funding_rate`, `get_funding_payment_history`	Mixed
Auth	`auth_login`, `auth_status`, `auth_logout`	No

Once configured, your AI agent can directly query prices, place orders, manage positions, and monitor your account on GRVT.

MCP Prerequisites

Before using MCP tools that require authentication, set up credentials via the CLI:

grvt-cli config init    # Interactive setup
grvt-cli auth login     # Create session

The MCP server reads the same config and session files as the CLI (~/.grvt-cli/).

OpenClaw Skill

This package includes an OpenClaw skill definition for AI agent ecosystems. The skill file is located at skill/SKILL.md with detailed reference docs in skill/references/.

Compatible with OpenClaw, ClawdBot, and other agent skill platforms.

Instrument Naming

Instruments follow {BASE}_{QUOTE}_{Type}:

Instrument	Description
`BTC_USDT_Perp`	Bitcoin perpetual
`ETH_USDT_Perp`	Ethereum perpetual
`SOL_USDT_Perp`	Solana perpetual
`TSLA_USDT_Perp`	Tesla equity perpetual
`XAU_USDT_Perp`	Gold perpetual

Use grvt-cli market instruments -o json for the full list with tick sizes and minimum order sizes.

Common Workflows

Close a Position

# Long position → sell reduce-only
grvt-cli order create --instrument BTC_USDT_Perp --side sell --size 0.002 --type market --reduce-only

# Short position → buy reduce-only
grvt-cli order create --instrument ETH_USDT_Perp --side buy --size 0.5 --type market --reduce-only

Always use --reduce-only when closing positions to prevent accidentally opening the opposite direction.

Bracket Order (Entry + Take-Profit)

grvt-cli order create --instrument BTC_USDT_Perp --side buy --size 0.01 --type market
grvt-cli order create --instrument BTC_USDT_Perp --side sell --size 0.01 --price 75000 --reduce-only

Funding Rate Arbitrage

grvt-cli funding rate BTC_USDT_Perp -o json     # Check rate
grvt-cli order create --instrument BTC_USDT_Perp --side buy --size 0.1 --type market  # Go long if negative
grvt-cli funding history --instrument BTC_USDT_Perp --limit 5 -o json  # Monitor payments

Portfolio Health Check

grvt-cli account sub-account -o json             # Margin & balance
grvt-cli position list -o json                    # Open positions
grvt-cli order list -o json                       # Open orders

Cancel Everything

grvt-cli order cancel-all
grvt-cli position list -o json
# For each position, create opposite reduce-only market order

Error Handling

Errors include actionable recovery instructions:

ERROR: Not authenticated. Session expired or not logged in.

To fix this, run:
  grvt-cli auth login

Error	Recovery
`Not authenticated`	`grvt-cli auth login`
`API key is not configured`	`grvt-cli config init`
`Order below minimum notional`	Increase `--size` or `--price`
`Instrument not found`	`grvt-cli market instruments --kind PERPETUAL`

Safety Rules

Use --reduce-only for all exit orders — prevents accidental position flips
Check instrument specs before placing orders — verify minSize and tickSize
Check account balance before large orders — grvt-cli account sub-account -o json
Start with small sizes when testing strategies
Never expose API secret — it's used locally for signing, never sent to servers
Use Trade-only API keys — never use keys with withdrawal permissions

Security

Secret input masking — config init hides your API secret as you type (displays *)
Cryptographic nonce — order signing uses a CSPRNG (crypto.randomInt), not Math.random()
File permissions — config and session files are created with 0600 (owner read/write only)
Input validation — MCP tool inputs (instrument, size, price, order ID) are validated with regex patterns
Error sanitization — server error responses are filtered to prevent internal detail leakage
Expired session cleanup — expired session files are automatically deleted on detection

Configuration Files

File	Path	Description
Config	`~/.grvt-cli/config.json`	API key, secret, sub-account ID
Session	`~/.grvt-cli/session.json`	Login session (auto-managed)

Both files use 0600 permissions (owner read/write only). Sessions auto-refresh when needed.

Environment Variables

Variable	Description
`GRVT_API_KEY`	API key (fallback when config not set)
`GRVT_SECRET_KEY`	API secret / private key
`GRVT_SUB_ACCOUNT_ID`	Default sub-account ID

Resources

GRVT Exchange: https://grvt.io
npm Package: https://www.npmjs.com/package/@2oolkit/grvt-cli
GitHub: https://github.com/haeminmoon/grvt-cli
GRVT API Docs: https://docs.grvt.io/api

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
skill		skill
src		src
test		test
.gitignore		.gitignore
PLAN.md		PLAN.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

@2oolkit/grvt-cli

Installation

Prerequisites

CLI Usage

Quick Start

Configuration

Command Reference

Market Data (no auth required)

Orders (auth required)

Positions, Account & Funding

Auth & Config

Output Formats

MCP Server

Setup for Claude Code

Setup for Claude Desktop / Cursor / Windsurf

Available Tools (17)

MCP Prerequisites

OpenClaw Skill

Instrument Naming

Common Workflows

Close a Position

Bracket Order (Entry + Take-Profit)

Funding Rate Arbitrage

Portfolio Health Check

Cancel Everything

Error Handling

Safety Rules

Security

Configuration Files

Environment Variables

Resources

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages