CA: AKSYuSqinmiYt5pSQxsfb4m97seTP37s32TSs9Lpumpx github

wallet

command line

Ship hooks from your terminal.

patcha-cli is the command-line entry point to the Patcha hook executor on Solana. Scaffold a hook project, backtest builtins against live pools, install hooks on chain with the holder-tier PATCHA burn, and quote any wallet's burn tier read-only.

npmpatcha-cli@latest · Node 20+ · MIT

prerequisites

The CLI is a thin client on top of Solana and your own keypair. You'll need the Solana toolchain even though installing patcha-cli itself is one npm install.

what you need before install

1Node 20 or higher. node --version should print v20.x or above. nodejs.org or nvm install 20.
2Solana CLI on your PATH: sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)". Verify with solana --version. Without it, patcha-cli can still scaffold and simulate, but can't sign or send transactions.
3A Solana keypair file. solana-keygen new creates one at ~/.config/solana/id.json by default. Pass --keypair <path> to override per command.
4Some SOL in that wallet for tx fees. A few hundredths of a SOL covers many installs (~0.000005 SOL per signature). Top up via solana airdrop 1 on devnet, or transfer on mainnet.
5(Burn path only) PATCHA in that same wallet, ≥ the burn amount for your tier (see the table below). Pass --no-burn to use the legacy free path while you acquire PATCHA.

install

Install globally from npm:

npm

1npm i -g patcha-cli@latest

Or the hosted tarball mirror (always latest, pinned to this site):

hosted tarball

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

Verify:

verify

1patcha --version

download .tgz →npmjs.com →

first commands

A 60-second walk-through. Each line is one command you can run as soon as the prerequisites above are in place.

first commands

1# 1. browse the hook marketplace
2patcha list
3 
4# 2. quote your wallet's burn tier (read-only, no signature)
5patcha tiers --wallet <your-wallet-pubkey>
6 
7# 3. backtest a builtin hook against a real pool (no wallet needed)
8patcha simulate dynamic-fee --pool <pool-addr> --dex orca
9 
10# 4. install a hook on a real pool (mainnet tx; signs from your keypair)
11patcha install dynamic-fee --pool <pool-addr> --dex orca
12 
13# 5. scaffold your own hook project
14patcha init my-hook && cd my-hook && patcha simulate hook.toml

command reference

patcha list

Browse the hook marketplace — built-in and community hooks, with cable color, category, and install count.

example

1patcha list --cluster mainnet

patcha tiers [--wallet <addr|path>]

Print the holder-share burn tier table. With --wallet, also quotes that wallet against live mint supply: tier, burn amount per install, and installs remaining. Read-only — no signature.

example

1patcha tiers --wallet f3Kt3HPX7DtzfLVXBFvhStfvKtg3XsayDkCSGYz4V64

patcha simulate <slug|config> --pool <addr> --dex <venue>

Backtest a builtin hook or a hook.toml file against a real CLMM pool. Returns fee APR, simulated performance vs baseline, and metrics. No wallet needed.

example

1patcha simulate dynamic-fee --pool <pool-addr> --dex meteora --period-days 30

patcha install <slug> --pool <addr> --dex <venue> [--no-burn]

Install a hook on a pool. Default path burns a tier-derived amount of PATCHA from the installer's wallet (see the table below). Pass --no-burn to use the legacy non-burning instruction. Idempotent — re-running the same (pool, slug) updates params instead of failing.

example

1patcha install dynamic-fee --pool <pool-addr> --dex orca --cluster mainnet

patcha init <name>

Scaffold a new hook project — Rust hook crate, TS config, a hook.toml ready to patcha simulate.

example

1patcha init my-hook

patcha create hook <slug> [-o <file>]

Generate a hook config from a builtin template.

example

1patcha create hook dynamic-fee -o hook.toml

patcha deploy <file>

example

1patcha deploy hook.toml --cluster mainnet

global flags

Every command accepts the following flags. Per-command flags (above) take precedence over the global ones.

--cluster mainnet|devnet|testnet|localnet (default mainnet)
--rpc <url> (overrides --cluster and PATCHA_RPC)
--wallet <path> (default ~/.config/solana/id.json)
--help, --version (per-command help: patcha install --help)

install_hook_burning · per-call burn

token-2022 · decimals 6

Every patcha install burns a tier-derived amount of PATCHA from the installer's wallet. Holding is the discount — the on-chain executor reads your share of total PATCHA_MINT supply and the SDK / CLI quote the same number off chain. Full spec.

tier	holder share	burn / install	notes
T1	≥ 2.0% supply	100 PATCHA	whale rate, effectively free
T2	≥ 1.0% supply	300 PATCHA	large holders
T3	≥ 0.5% supply	1,000 PATCHA	member rate
T4	≥ 0.1% supply	5,000 PATCHA	casual holders
T5	< 0.1% supply	50,000 PATCHA	non-holders — buy-and-burn cycle

Burn never fires from holding alone. It only runs when patcha install ... is signed by the wallet itself, and it burns only from that signer. PATCHA_MINT is a program const, mintAuthority and freezeAuthority are both null on chain — no new mints, no freezes, no admin switch.

troubleshooting

insufficient PATCHA for tier N: need X, wallet holds Y, short Z
Your signer wallet doesn't have enough PATCHA to cover the tier's burn. Buy the shortfall, or pass --no-burn to use the legacy free path. Use patcha tiers --wallet <addr> to preview before signing anything.
keypair not found at <path>
Run solana-keygen new to create one, or pass --keypair <path> / set the ANCHOR_WALLET env var.
Insufficient funds for rent / transaction simulation failed
Add SOL to the signer wallet (~0.05 SOL is enough headroom for most installs).
failed to get recent blockhash (TypeError: fetch failed)
The bundled fetch shim before 0.3.x was incompatible with Node 20+ fetch. Upgrade: npm i -g patcha-cli@latest.
bigint: Failed to load bindings, pure JS will be used
Cosmetic warning from bigint-buffer on Node 22 / Windows. Silenced in patcha-cli@0.3.1 and later; functionally a no-op either way.

Source on GitHub. CLI reference also in the docs.