patcha-cli

Scaffold, simulate, and deploy Solana CLMM hooks from the terminal.

Patcha is the first CLMM hooks framework on Solana — the Uniswap v4 hooks model brought to Orca Whirlpools and Raydium CLMM. A hook is a small composable module (dynamic fee, time lock, whitelist gate, range order, anti-MEV, KYC gate) patched into a pool and enforced by an Anchor 0.31 program on Solana mainnet.

The CLI is the same toolkit as the web Hook Designer and the VS Code extension — one @patcha/sdk, one Rust hook-runtime shared with the on-chain executor, byte-identical fee math so the number you backtest is the number that runs.

Install

npm i -g patcha-cli

Node 20 or higher. The published tarball is self-contained — esbuild bundles every runtime dependency into a single dist/index.js, so npm install adds one package and nothing else.

Hosted tarball mirror (always the latest):

npm i -g https://patcha.fi/downloads/patcha-cli-latest.tgz

Quick start

patcha init my-hook                       # scaffold hook.toml + README
patcha simulate my-hook/hook.toml         # backtest against real Orca/Raydium history
patcha install dynamic-fee \              # install on a real pool
  --pool <pool address> \
  --dex orca \
  --cluster mainnet

The four-line loop: scaffold → backtest → install → read the HookTriggered receipt off Solana Explorer.

Commands

| Command | What it does | |---|---| | patcha init <name> | Scaffold a project (hook.toml + README). | | patcha create hook <slug> | Generate a config from a builtin template (dynamic-fee, time-lock, whitelist-gate, range-order, anti-mev, kyc-gate). | | patcha list | Browse the marketplace — backend rows + the six builtins. | | patcha simulate <config> | Backtest the hook against the configured pool's history (real Orca/Raydium swaps). | | patcha install <slug> | Register + install the hook against a pool through the mainnet executor. | | patcha deploy <config> | Build, register, and install in one command (the full lifecycle). |

Every command supports --rpc <url>, --wallet <path>, --cluster <mainnet|devnet|localnet>, and --help for full flags.

The six builtin hooks

| Slug | Category | Cable | Callbacks | |---|---|---|---| | dynamic-fee | fees | red | beforeSwap, afterSwap | | time-lock | timing | yellow | beforeAddLiquidity, beforeRemoveLiquidity | | whitelist-gate | gating | green | beforeSwap, beforeAddLiquidity | | range-order | range | cyan | afterSwap | | anti-mev | mev | purple | beforeSwap, afterSwap | | kyc-gate | kyc | grey | beforeSwap, beforeAddLiquidity |

Definitions live in @patcha/hook-library and are read identically by the CLI, the SDK, the web Designer, and the on-chain executor.

Config — hook.toml

slug = "dynamic-fee"
dex = "orca"                    # orca | raydium
pool = "<pool address>"
period_days = 30

[params]
baseFeeBps = 30
maxFeeBps = 100
pivotAmount = 1000000000        # 1 SOL in lamports

JSON configs (.json) with the same shape are also accepted.

DynamicFee — concretely

fee = base_bps + (max_bps - base_bps) · min(amount_in, pivot) / pivot

Integer math. No floats. A small swap pays 30 bps, the pivot pays the 100-bps cap, between interpolates. The off-chain hook-runtime (what patcha simulate calls) and the on-chain executor compute this from a byte-identical function — there is no gap between the backtest number and the chain number.

Environment

| Variable | Purpose | Default | |---|---|---| | PATCHA_API_URL | Backend base URL for list / simulate | https://api.patcha.fi | | PATCHA_RPC | Default RPC endpoint for install / deploy | https://api.mainnet-beta.solana.com | | ANCHOR_WALLET / SOLANA_KEYPAIR | Signer keypair path | ~/.config/solana/id.json |

Flags override env vars (e.g. --rpc https://your.helius.url).

On-chain executor

| | | |---|---| | Program ID | EPcW7e8RxBNPpQK2XKoKG9maWH6QvmU3ejxifoU5rNRa | | Cluster | Solana mainnet | | Loader | BPFLoaderUpgradeab1e11111111111111111111111 | | Explorer | solscan.io/account/EPcW7e8…rNRa |

The CLI's install / deploy commands call this program directly via @patcha/sdk — same instructions the web Designer fires.

Open source

github.com/patcha-fi/patcha — MIT. Issues and pull requests welcome. Docs: patcha.fi/docs.

References

• Uniswap v4 hooks — Adams & Salem, Uniswap Labs (2024).
• Anchor 0.31 — Coral, 2026.
• Orca Whirlpools program: whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc.
• Raydium CLMM program: CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK.

Learn more at patcha.fi.