impulse

impulse is a terminal client for the Imperial perps API.

It has two modes:

• CLI subcommands for scripting/automation
• TUI for interactive monitoring + order flow

Quick Start

cargo build --release
./target/release/impulse

If no subcommand is provided, impulse starts the TUI.

Core Workflow

1. Login (JWT auth):

impulse login

2. Check account + market state:

impulse whoami
impulse balances
impulse positions
impulse marks --symbol SOL

3. Route and trade:

impulse route --side long --notional 1000 --leverage 5 --asset SOL
impulse order --side long --venue phoenix --notional 100 --collateral 20 --asset SOL

4. Manage orders:

impulse orders
impulse cancel --order-pda <PDA>
impulse update --order-pda <PDA> --trigger 91.5

5. Cleanup:

impulse sweep --profile 0
impulse revoke

JSON Mode (for agents)

Every command supports --json and returns one envelope:

• success: {"ok": true, "data": ...}
• failure: {"ok": false, "error": "..."}

Example:

impulse marks --symbol SOL --json

This is the recommended mode for Claude/Codex integrations.

Deposit / Withdraw

impulse deposit maps to Imperial /deposit/build-tx and supports:

• --mode deposit (wallet USDC -> profile USDC)
• --mode withdraw (profile USDC -> wallet USDC)

Important: this endpoint returns a partially-signed sponsored tx. You still need to:

1. decode base64
2. sign with wallet keypair
3. broadcast via Solana RPC

Example:

impulse deposit --usdc 100 --profile 0 --mode deposit
impulse deposit --usdc 50 --profile 0 --mode withdraw

Sweep

impulse sweep calls /passthrough/users/{wallet}/profiles/{index}/sync. Use it after fully closing non-USDC-collateralized positions (residue like WSOL/WBTC/WETH) to reclaim USDC back to wallet.

TUI

Start:

impulse tui

Useful keys:

• : command line
• ? help
• b / s prefill buy/sell
• c prefill close
• x cancel selected order
• v cycle venue
• m cycle candle bucket
• q quit

TUI commands include: buy, sell, close, limit, cancel, route, balances, positions, orders, status, sweep, sym, venue, profile, revoke, clear.

Route API Coverage

CLI exposes both basic and advanced route parameters (see impulse route --help), including:

• hold-hours
• daily-vol
• sticky-venue
• subaccount-default-venue
• wallet
• profile-index
• excluded-venues

Config

• Global API override: --base-url
• Credentials path override: IMPULSE_HOME
• JSON output: --json

Default auth file location:

• $XDG_CONFIG_HOME/impulse/credentials.json
• fallback: ~/.config/impulse/credentials.json

Command Help

Use:

impulse --help
impulse <command> --help

Flag descriptions are detailed and aligned with Imperial API behavior.

API Source of Truth

Imperial OpenAPI:

• https://api.imperial.space/api/v1/openapi.json

Docs UI:

• https://api.imperial.space/api/v1/docs

License

MIT