Perpl-CLI
perpl-cli is a command-line tool for reading and tracing Perpl exchange state and events directly from the chain. Use it to take a point-in-time snapshot of the exchange, follow the live event stream, or inspect a single account, order book, block, or transaction — all without writing any code.
It is a thin wrapper over the Perpl Rust SDK. Under the hood it builds a state snapshot with the SDK's SnapshotBuilder and then follows the chain with the SDK's raw event stream, so anything the CLI prints, you can reproduce programmatically with the SDK.
perpl-cli is read-only. It never signs or sends transactions — it only queries an RPC (remote procedure call) endpoint. To place or cancel orders, use the SDK's order-posting helpers.
Installing
perpl-cli ships as the crates/cli member of the perpl-sdk workspace and is built from source with Cargo. You need Rust >= 1.85.0 (the workspace uses edition 2024).
From the dex-sdk workspace root:
# Build an optimized binary at target/release/perpl-cli
cargo build --release -p perpl-cli
# ...or run it directly through Cargo (arguments after `--` go to the CLI)
cargo run -p perpl-cli -- snapshotFor the examples on this page, assume perpl-cli is on your PATH (for example by copying target/release/perpl-cli into a directory on your PATH). If you prefer to run through Cargo, replace perpl-cli with cargo run -p perpl-cli -- in any example below.
Usage
perpl-cli [OPTIONS] <COMMAND>All options are global — they can appear before the command or after it. Command-specific options (such as --depth for show book) must follow their subcommand.
By default perpl-cli targets Mainnet (chain ID 143). Pass --testnet to target Testnet (chain ID 10143). Each network has its own default RPC endpoint and Exchange contract address; see Networks & Configuration for the full per-network reference.
Commands
snapshot
Fetch the exchange state at a single block height and print it.
trace
Take an initial snapshot, then follow (trace) events block by block, and print the final state when it stops.
show account
Print live account state (balances, positions, orders, recent trades).
show book
Print a perpetual's live order book.
show trades
Print recent trades.
block <BLOCK_NUMBER>
Trace the raw events emitted in one specific block.
tx <TX_HASH>
Trace the raw events emitted by one specific transaction.
snapshot
Captures the full exchange state at one block and prints it. With no filters it snapshots every perpetual and account the exchange knows about; narrow it with --perp and/or --account. Pin the block with --block (defaults to the latest block).
trace
Takes an initial snapshot, then follows the event stream forward from that point, applying each block's events to keep the state current. It prints the final state when it stops. Without --num-blocks it runs until you interrupt it with Ctrl+C.
Tracing follows finalized blocks. On Monad the latest tag is a proposed (not-yet-final) block, so the stream waits for a block to reach the safe tag before emitting its events. This keeps the traced state consistent at the cost of a short lag behind the chain head.
show account
Prints the live state of one account: balances, open positions, resting orders, and (by default) its most recent trades. --account is required for this command.
Command option:
--num-trades <N>
10
Number of recent trades to show. 0 hides the trades section.
You can also identify the account by its on-chain address instead of its numeric ID:
show book
Prints a perpetual's live order book. --perp is required for this command.
Command options:
-d, --depth <N>
10
Number of price levels per side to show. 0 shows all levels.
--orders-per-level <N>
10
Number of individual orders to show at each price level (the book is level-3, i.e. order-by-order). 0 shows all orders.
--show-expired
false
Include expired orders in the output.
show trades
Prints recent trades. With no --perp it shows trades across all perpetuals; pass --perp (repeatable) to filter.
block and tx
Inspect the raw exchange events emitted by a single block or a single transaction. These are handy for debugging a specific on-chain action.
Options
Every option below is global and applies to all commands.
--testnet
off (Mainnet)
Target Testnet instead of Mainnet. Switches the default RPC endpoint and Exchange address to their testnet values.
--rpc <RPC>
Mainnet: https://rpc.monad.xyz; Testnet: https://testnet-rpc.monad.xyz
RPC endpoint to connect to. Supply your own node URL to override the default.
--rpc-throttle <REQ_PER_SEC>
15 for the built-in RPC endpoints; none for a custom --rpc
Client-side rate limit in requests per second.
--exchange <ADDRESS>
Mainnet: 0x34B6552d57a35a1D042CcAe1951BD1C370112a6F; Testnet: 0x1964C32f0bE608E7D29302AFF5E61268E72080cc
Exchange contract address. Override for a non-standard deployment.
--block <BLOCK>
latest block
Block number to fetch state at (snapshot) or to start tracing from (trace).
--num-blocks <NUM_BLOCKS>
unlimited (until Ctrl+C)
Number of blocks to trace or show.
--account <ADDRESS or ACCOUNT_ID>
all accounts for snapshot/trace; required for show account
Account to snapshot, trace, or show. Repeatable — pass the flag multiple times to select several accounts. Accepts either the numeric account ID or the account's on-chain address.
--perp <PERPETUAL_ID>
all perpetuals for snapshot/trace/show trades; required for show book
Perpetual (market) to operate on. Repeatable.
Perpetual IDs are network-specific — for example BTC is perpetual 1 on Mainnet but 16 on Testnet. See the market tables in Networks & Configuration, or run a snapshot with no --perp filter to list every market on the target network.
Using a custom RPC endpoint
Point the CLI at your own node — for example a private archival node or a local test chain — with --rpc. When you supply a custom endpoint the built-in 15 req/sec throttle is disabled; set --rpc-throttle yourself if your provider enforces a rate limit.
Common tasks
See the whole exchange right now (mainnet)
perpl-cli snapshot
See one market's state at a past block
perpl-cli --perp 1 --block 55000000 snapshot
Watch the order book for BTC live
perpl-cli --perp 1 show book
Watch one account's positions and orders
perpl-cli --account 42 show account
Stream recent trades for a market
perpl-cli --perp 20 show trades
Follow all events on testnet for a while
perpl-cli --testnet --num-blocks 500 trace
Debug what one transaction did
perpl-cli tx 0xabc123...def
Debug what happened in one block
perpl-cli block 55123456
See also
Networks & Configuration — chain IDs, RPC URLs, Exchange addresses, and market IDs for both networks.
Perpl Rust SDK — the library
perpl-cliis built on, for programmatic state snapshots, event streams, and order posting.
Last updated