outsmart 2.0.0-alpha.0 → 2.0.0-alpha.10

package/README.md

@@ -1,14 +1,15 @@
 # outsmart
 
-**Solana trading CLI — buy, sell, and LP across 18 DEXes with 12 TX landing providers.**
+**Solana trading CLI — buy, sell, LP, and operate perp exchanges across 18 DEXes with 12 TX landing providers.**
+
+**[Documentation](https://outsmartchad.github.io/outsmart-cli/)** | **[npm](https://www.npmjs.com/package/outsmart)** | **[Discord](https://discord.gg/dc3Kh3Y3yJ)**
 
 ```bash
-npm install -g outsmart
+npm install -g outsmart@alpha
+outsmart init
 outsmart buy --dex raydium-cpmm --pool <POOL> --amount 0.1
 ```
 
-> **This branch (`agent-trading-infra`) is under active development.** For the stable version, use [`typescript-main`](https://github.com/outsmartchad/outsmart-cli/tree/typescript-main).
-
 ---
 
 ## Quick Start
@@ -16,40 +17,23 @@ outsmart buy --dex raydium-cpmm --pool <POOL> --amount 0.1
 ### 1. Install
 
 ```bash
-# From source
+# From npm (recommended)
+npm install -g outsmart@alpha
+
+# Or from source
 git clone https://github.com/outsmartchad/outsmart-cli.git
 cd outsmart-cli
-nvm install && nvm use
 npm install --legacy-peer-deps
 npm run build
-
-# Or globally (when published to npm)
-npm install -g outsmart
 ```
 
 ### 2. Configure
 
-Run the interactive setup — it prompts for your wallet key and RPC endpoint:
-
 ```bash
 outsmart init
 ```
 
-This writes your config to `~/.outsmart/config.env` (and `.env` in the project root if you cloned from source). You only need to do this once.
-
-**Or configure manually:** copy `.env.example` to `.env` and fill in your values:
-
-```bash
-cp .env.example .env
-```
-
-```bash
-# Required
-PRIVATE_KEY=your_base58_private_key_here
-MAINNET_ENDPOINT=https://mainnet.helius-rpc.com/?api-key=YOUR_HELIUS_KEY
-```
-
-See `.env.example` for all available options (TX landing provider keys, trading defaults, etc.).
+Prompts for your wallet key and RPC endpoint. Writes config to `~/.outsmart/config.env`. You only need to do this once.
 
 ### 3. Trade
 
@@ -60,32 +44,41 @@ outsmart buy --dex raydium-cpmm --pool <POOL> --amount 0.1
 # Sell 100% of held balance
 outsmart sell --dex raydium-cpmm --pool <POOL> --pct 100
 
-# Stablecoin-quoted pool — auto-swaps SOL → USD1, then buys token
-outsmart buy --dex raydium-launchlab --pool <POOL> --amount 0.1
+# Swap aggregator (no pool needed, just token mint)
+outsmart buy --dex jupiter-ultra --token <MINT> --amount 0.1
 
-# Sell on a stablecoin pool — sells token → USD1, then auto-swaps USD1 → SOL
-outsmart sell --dex raydium-launchlab --pool <POOL> --pct 100
+# Check your balances
+outsmart balance
+```
 
-# Swap aggregator (no pool needed, just token)
-outsmart buy --dex jupiter-ultra --token <MINT> --amount 0.1
+**Example output:**
 
-# Check token info
-outsmart info --token <MINT>
+```
+  buying on raydium-cpmm...
+  TX sent: 5zwjta... — confirming...
+
+  dex:       raydium-cpmm
+  tx:        5zwjtaMj8LCzf4cY7Kt2QU2CAcAn3BAwvpVCbTjsR3qJ...
+  confirmed: true
+  in:        0.001 SOL
+  out:       2.001886 USELESS
+  pool:      Q2sPHPdUWFMg7M7wwrQKLrn619cAucfRsmhVJffodSp
 ```
 
 ---
 
 ## Commands
 
-### buy
+### Trading
+
+#### buy
 
 Buy tokens with SOL (or a quote token).
 
 ```bash
 outsmart buy --dex <name> --pool <POOL> --amount <SOL>
 outsmart buy --dex raydium-cpmm --pool <POOL> --amount 0.1
-outsmart buy --dex meteora-damm-v2 --pool <POOL> --amount 1 --tip 0.001
-outsmart buy --dex jupiter-ultra --token <MINT> --amount 0.5 --slippage 500
+outsmart buy --dex jupiter-ultra --token <MINT> --amount 0.5
 ```
 
 | Flag | Description |
@@ -93,26 +86,128 @@ outsmart buy --dex jupiter-ultra --token <MINT> --amount 0.5 --slippage 500
 | `-d, --dex <name>` | DEX adapter name (required) |
 | `-a, --amount <sol>` | SOL amount to spend (required) |
 | `-p, --pool <address>` | Pool address (required for on-chain DEXes) |
-| `-t, --token <mint>` | Token mint (auto-detected from pool; required for aggregators or non-SOL quote pools) |
+| `-t, --token <mint>` | Token mint (auto-detected from pool; required for aggregators) |
 
-### sell
+#### sell
 
-Sell tokens for SOL (or a quote token). Specify what percentage of your balance to sell.
+Sell tokens for SOL. Specify what percentage of your balance to sell.
 
 ```bash
-outsmart sell --dex <name> --pool <POOL> --pct <0-100>
+outsmart sell --dex <name> --pool <POOL> --pct <1-100>
 outsmart sell --dex raydium-cpmm --pool <POOL> --pct 100
-outsmart sell --dex dflow --token <MINT> --pct 50 --slippage 300
+outsmart sell --dex jupiter-ultra --token <MINT> --pct 50
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-d, --dex <name>` | DEX adapter name (required) |
-| `--pct <percentage>` | Percentage of balance to sell, 0-100 (required) |
+| `--pct <percentage>` | Percentage of balance to sell, 1-100 (required) |
 | `-p, --pool <address>` | Pool address (required for on-chain DEXes) |
-| `-t, --token <mint>` | Token mint (auto-detected from pool; required for aggregators or non-SOL quote pools) |
+| `-t, --token <mint>` | Token mint (auto-detected from pool; required for aggregators) |
+
+#### quote
+
+Get the current on-chain price from a pool.
+
+```bash
+outsmart quote --dex raydium-cpmm --pool <POOL>
+```
+
+#### find-pool
+
+Discover a pool for a token pair on a specific DEX.
+
+```bash
+outsmart find-pool --dex raydium-cpmm --token <MINT>
+```
+
+### Wallet Management
+
+#### wallet
+
+Show the active wallet address and SOL balance.
+
+```bash
+outsmart wallet
+```
+
+```
+  label:   default
+  address: tstXr3NbiMd6FFZF2qbPzxJqxCGXuSjpZVvdjeXiPv1
+  balance: 0.377743 SOL
+```
+
+#### wallet list
+
+Show all saved wallets with their balances. Active wallet marked with `*`.
+
+```bash
+outsmart wallet list
+```
+
+```
+  LABEL              ADDRESS                                         SOL
+  ──────────────────────────────────────────────────────────────────────────
+ * default            tstXr3NbiMd6FFZF2qbPzxJqxCGXuSjpZVvdjeXiPv1  0.3777
+   trading            7xKXt...                                       1.2340
+
+  * = active wallet
+```
+
+#### wallet add
 
-### add-liq
+Add a new wallet. Prompts for the private key.
+
+```bash
+outsmart wallet add --label trading
+```
+
+#### wallet switch
+
+Switch the active wallet. All subsequent commands use the new wallet.
+
+```bash
+outsmart wallet switch trading
+```
+
+#### wallet remove
+
+Remove a saved wallet (with confirmation prompt).
+
+```bash
+outsmart wallet remove trading
+```
+
+### Balances
+
+#### balance
+
+Show SOL + stablecoin balances for the active wallet.
+
+```bash
+outsmart balance
+```
+
+```
+  Wallet: tstXr3NbiMd6FFZF2qbPzxJqxCGXuSjpZVvdjeXiPv1
+
+  SOL        0.377743
+  USDC       0.000001
+  USDT       0
+  USD1       0
+```
+
+#### balance --token
+
+Check the balance of a specific token.
+
+```bash
+outsmart balance --token <MINT>
+```
+
+### Liquidity
+
+#### add-liq
 
 Add liquidity to a pool.
 
@@ -127,198 +222,199 @@ outsmart add-liq --dex meteora-dlmm --pool <POOL> --amount-sol 0.5 --amount-toke
 | `-p, --pool <address>` | Pool address (required) |
 | `--amount-sol <amount>` | Amount of SOL to deposit |
 | `--amount-token <amount>` | Amount of non-SOL token to deposit |
-| `-t, --token <mint>` | Token mint (for single-sided token deposits) |
 | `--strategy <type>` | Distribution: `spot` \| `curve` \| `bid-ask` (DLMM only, default: spot) |
 | `--bins <count>` | Number of bins (DLMM only, default: 50, max: 70) |
 
-### remove-liq
+#### remove-liq
 
 Remove liquidity from a pool.
 
 ```bash
 outsmart remove-liq --dex meteora-damm-v2 --pool <POOL> --pct 100
-outsmart remove-liq --dex meteora-dlmm --pool <POOL> --pct 50
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-d, --dex <name>` | DEX adapter name (required) |
-| `-p, --pool <address>` | Pool address (required) |
-| `--pct <percentage>` | Percentage of LP position to remove, 0-100 (required) |
-| `--position <address>` | Specific position to remove from (default: first found) |
-
-### claim-fees
+#### claim-fees
 
 Claim accumulated swap fees from LP positions.
 
 ```bash
 outsmart claim-fees --dex meteora-damm-v2 --pool <POOL>
-outsmart claim-fees --dex meteora-dlmm --pool <POOL> --position <POSITION>
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-d, --dex <name>` | DEX adapter name (required) |
-| `-p, --pool <address>` | Pool address (required) |
-| `--position <address>` | Specific position to claim from (default: all) |
-
-### positions
+#### positions
 
 List LP positions in a pool.
 
 ```bash
 outsmart positions --dex meteora-damm-v2 --pool <POOL>
-outsmart positions --dex meteora-dlmm --pool <POOL> --json
 ```
 
-| Flag | Description |
-|------|-------------|
-| `-d, --dex <name>` | DEX adapter name (required) |
-| `-p, --pool <address>` | Pool address (required) |
-| `--json` | Output as JSON |
+### Pool Creation
 
-### quote
+#### create-pump-coin
 
-Get the current on-chain price from a pool.
+Create a new PumpFun token with a bonding curve.
 
 ```bash
-outsmart quote --dex raydium-cpmm --pool <POOL>
-outsmart quote --dex meteora-dlmm --pool <POOL>
+outsmart create-pump-coin --name "My Token" --symbol "MYTKN" --uri "https://ipfs.io/ipfs/Qm..."
 ```
 
-### find-pool
+#### create-pool
 
-Discover a pool for a token pair on a specific DEX.
+Create a new PumpSwap AMM pool with initial liquidity.
 
 ```bash
-outsmart find-pool --dex raydium-cpmm --token <MINT>
-outsmart find-pool --dex raydium-amm-v4 --token <MINT> --quote <USDC_MINT>
+outsmart create-pool --base <MINT> --quote So111...112 --base-amount 1000000 --quote-amount 1
 ```
 
-### create-pump-coin
+#### create-damm-pool
 
-Create a new PumpFun token with a bonding curve. The token is instantly tradeable on pump.fun.
+Create a Meteora DAMM v2 custom pool with full fee configuration.
 
 ```bash
-outsmart create-pump-coin --name "My Token" --symbol "MYTKN" --uri "https://ipfs.io/ipfs/Qm..."
+outsmart create-damm-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5
+outsmart create-damm-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5 \
+  --max-fee 5000 --min-fee 100 --fee-mode 1 --dynamic-fee
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--name <name>` | Token name (required) |
-| `--symbol <symbol>` | Token symbol (required) |
-| `--uri <uri>` | Metadata URI — IPFS/Arweave link to JSON metadata (required) |
+#### create-damm-config-pool
 
-Returns the new mint address and bonding curve address.
+Create a Meteora DAMM v2 pool using an existing on-chain config.
 
-### create-pool
+```bash
+outsmart create-damm-config-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5 \
+  --config <CONFIG_ADDRESS>
+```
 
-Create a new PumpSwap AMM pool with initial liquidity.
+### Perpetual Futures (Percolator)
+
+Create and operate on-chain perpetual futures exchanges. All prices in USD, all amounts in SOL.
+
+#### perp create-market
+
+Create a new perp market. You become the admin/oracle authority.
 
 ```bash
-outsmart create-pool --base <MINT> --quote So111...112 --base-amount 1000000 --quote-amount 1
+outsmart perp create-market --price 150 --lp 2
+outsmart perp create-market --price 0.00001 --lp 5 --tier medium --network mainnet
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--price <usd>` | Initial oracle price in USD (required) | |
+| `--lp <sol>` | Initial LP collateral in SOL (required) | |
+| `--tier <size>` | `small` \| `medium` \| `large` | `small` |
+| `--network <net>` | `devnet` \| `mainnet` | `devnet` |
+
+#### perp long / short
+
+Open a leveraged position.
+
+```bash
+outsmart perp long  -m <MARKET> -s 0.1
+outsmart perp short -m <MARKET> -s 0.05
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--base <mint>` | Base token mint address (required) |
-| `--quote <mint>` | Quote token mint address, usually WSOL (required) |
-| `--base-amount <amount>` | Initial base token deposit, human-readable (required) |
-| `--quote-amount <amount>` | Initial quote token deposit, human-readable (required) |
-| `--index <number>` | Pool index (default: 1; 0 is reserved for canonical pump pools) |
+| `-m, --market <address>` | Market (slab) address (required) |
+| `-s, --size <sol>` | Position size in SOL (required) |
 
-### create-damm-pool
+#### perp close
 
-Create a Meteora DAMM v2 custom pool with full fee configuration. This is the primary method for token launches — gives full control over fee schedule, dynamic fees, and activation timing.
+Close your open position.
 
 ```bash
-# Basic: create with default fee schedule (99% → 2% linear decay over 24h)
-outsmart create-damm-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5
+outsmart perp close -m <MARKET>
+```
 
-# Custom fees: exponential decay, dynamic fee enabled
-outsmart create-damm-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5 \
-  --max-fee 5000 --min-fee 100 --fee-mode 1 --dynamic-fee
+#### perp status
 
-# Scheduled activation (unix timestamp)
-outsmart create-damm-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5 \
-  --activation 1740000000
+View your position and market state.
+
+```bash
+outsmart perp status -m <MARKET>
 ```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--base <mint>` | Base token mint address (required) | |
-| `--base-amount <amount>` | Initial base token deposit (required) | |
-| `--quote-amount <amount>` | Initial quote token deposit (required) | |
-| `--quote <mint>` | Quote token mint | WSOL |
-| `--price <number>` | Initial price in quote/base units | quoteAmount / baseAmount |
-| `--max-fee <bps>` | Max base fee at activation | 9900 |
-| `--min-fee <bps>` | Min base fee after decay | 200 |
-| `--periods <n>` | Number of fee decay periods | 1440 |
-| `--duration <secs>` | Total fee decay duration in seconds | 86400 |
-| `--fee-mode <0\|1>` | 0 = linear decay, 1 = exponential | 0 |
-| `--dynamic-fee` | Enable dynamic fee on top of base fee | false |
-| `--collect-mode <0\|1>` | 0 = both tokens, 1 = quote only | 1 |
-| `--activation <timestamp>` | Activation unix timestamp | immediate |
-| `--alpha-vault` | Create alpha vault after pool | false |
+#### perp deposit / withdraw
+
+Manage collateral in your trading account.
 
-### create-damm-config-pool
+```bash
+outsmart perp deposit  -m <MARKET> -a 1.0
+outsmart perp withdraw -m <MARKET> -a 0.5
+outsmart perp withdraw -m <MARKET> -a all
+```
 
-Create a Meteora DAMM v2 pool using an existing on-chain config. Simpler than `create-damm-pool` — the config determines the fee schedule and price range.
+#### perp init-user
+
+Register a trading account on a market (required before first deposit/trade).
 
 ```bash
-outsmart create-damm-config-pool --base <MINT> --base-amount 1000000 --quote-amount 0.5 \
-  --config 2yAJha5NVgq5mEitTUvdWSUKrcYvxAAc2H6rPDbEQqSu
+outsmart perp init-user -m <MARKET>
 ```
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--base <mint>` | Base token mint address (required) | |
-| `--base-amount <amount>` | Initial base token deposit (required) | |
-| `--quote-amount <amount>` | Initial quote token deposit (required) | |
-| `--config <address>` | On-chain config address (required) | |
-| `--quote <mint>` | Quote token mint | WSOL |
-| `--price <number>` | Initial price in quote/base units | quoteAmount / baseAmount |
-| `--activation <timestamp>` | Activation unix timestamp | immediate |
-| `--lock` | Permanently lock initial liquidity | false |
+#### perp set-price
 
-### list-dex
+Push a new oracle price (admin-oracle markets only).
 
-List all registered DEX adapters and their capabilities.
+```bash
+outsmart perp set-price -m <MARKET> --price 155.50
+```
+
+#### perp crank
+
+Run the permissionless keeper crank (updates funding rates).
 
 ```bash
-outsmart list-dex
-outsmart list-dex --cap canSell
-outsmart list-dex --cap canAddLiquidity --json
+outsmart perp crank -m <MARKET>
 ```
 
-### info
+#### perp markets
 
-Fetch token market data from DexScreener.
+Discover all markets on-chain.
 
 ```bash
-outsmart info --token <MINT>
+outsmart perp markets
+outsmart perp markets --network mainnet
 ```
 
-Returns: price, market cap, volume, liquidity, pair age, buyer counts, social links.
+---
+
+### Utilities
 
-### init
+#### info
 
-Interactive setup — prompts for your wallet private key and RPC endpoint, validates the key, and writes config to `~/.outsmart/config.env`.
+Fetch token market data from DexScreener.
 
 ```bash
-outsmart init
+outsmart info --token <MINT>
 ```
 
-You only need to run this once. After that, all commands will use the saved config.
+#### list-dex
 
-### config
+List all registered DEX adapters and their capabilities.
+
+```bash
+outsmart list-dex
+outsmart list-dex --cap canSell
+```
+
+#### config
 
 View or generate configuration.
 
 ```bash
 outsmart config show        # Show current env config (sensitive values masked)
 outsmart config env         # Print a .env template
-outsmart config env > .env  # Generate .env file
+```
+
+#### init
+
+Interactive setup — prompts for wallet key and RPC endpoint.
+
+```bash
+outsmart init
 ```
 
 ---
@@ -327,9 +423,9 @@ outsmart config env > .env  # Generate .env file
 
 Some pools use stablecoins (USDC, USDT, USD1) as the quote token instead of SOL. The CLI handles this automatically — no extra steps needed.
 
-**On buy:** detects the stablecoin quote from the pool, swaps SOL → stablecoin, then buys the token with the full swapped amount.
+**On buy:** detects the stablecoin quote from the pool, swaps SOL → stablecoin, then buys the token.
 
-**On sell:** sells the token for stablecoin on the DEX, then swaps the stablecoin proceeds back to SOL.
+**On sell:** sells the token for stablecoin, then swaps the proceeds back to SOL.
 
 ```bash
 # LaunchLab pool quoted in USD1 — just specify SOL amount as usual
@@ -340,12 +436,7 @@ outsmart sell --dex raydium-launchlab --pool <POOL> --pct 100
 # → sells token → USD1 → auto-swaps USD1 → SOL
 ```
 
-**How it works:**
-- If `JUPITER_API_KEY` is set, uses Jupiter Ultra for the SOL↔stablecoin conversion
-- If not set, falls back to on-chain DEX adapters with a curated pool registry (high-TVL Raydium CLMM, AMM v4, and Meteora DLMM pools)
-- Only the swapped amount is used — pre-existing stablecoin balances in your wallet are untouched
-
-Get a free Jupiter API key at [portal.jup.ag](https://portal.jup.ag) (optional — on-chain fallback works without it).
+Uses Jupiter Ultra if `JUPITER_API_KEY` is set, otherwise falls back to on-chain DEX pools. Get a free key at [portal.jup.ag](https://portal.jup.ag) (optional).
 
 ---
 
@@ -360,7 +451,6 @@ All swap commands (`buy`, `sell`) accept these options:
 | `--tip <sol>` | MEV tip in SOL | 0.001 |
 | `--cu <units>` | Compute unit limit | auto |
 | `--jito` | Use Jito bundle submission | false |
-| `--strategy <mode>` | TX landing: `concurrent` \| `race` \| `random` \| `sequential` | concurrent |
 | `--quote <mint>` | Quote token mint | WSOL |
 
 ---
@@ -369,28 +459,135 @@ All swap commands (`buy`, `sell`) accept these options:
 
 18 adapters covering every major Solana DEX protocol:
 
-| Adapter | Protocol | Buy | Sell | Pool | Price | LP | Extra | Tested |
-|---------|----------|:---:|:----:|:----:|:-----:|:--:|-------|:------:|
-| raydium-amm-v4 | AMM v4 | x | x | x | x | | | ✅ |
-| raydium-cpmm | CPMM | x | x | x | x | | | ✅ |
-| raydium-clmm | CLMM | x | x | x | x | | | ✅ |
-| raydium-launchlab | Launchlab | x | x | x | x | | auto-swap | ✅ |
-| meteora-damm-v1 | Dynamic AMM | x | x | x | x | | | — |
-| meteora-damm-v2 | CpAmm | x | x | x | x | add/remove/claim/positions | create pool | ✅ |
-| meteora-dlmm | DLMM | x | x | | x | add/remove/claim/positions | | ✅ |
-| meteora-dbc | DBC | x | x | | x | | | ✅ |
-| **pumpfun** | Bonding Curve | x | x | | x | | create coin | ✅ |
-| **pumpfun-amm** | PumpSwap AMM | x | x | | x | | create pool | ✅ |
-| orca | Whirlpool | x | x | | x | | | ✅ |
-| byreal-clmm | CLMM | x | x | | x | | | ✅ |
-| pancakeswap-clmm | CLMM | x | x | | x | | | ✅ |
-| fusion-amm | Fusion | x | x | | x | | | ✅ |
-| futarchy-amm | Futarchy | x | x | | x | | auto-swap | ✅ |
-| futarchy-launchpad | Launchpad | | | | | fund/claim | | — |
-| jupiter-ultra | Ultra API | x | x | | | | | ✅ |
-| dflow | Intent | x | x | | | | | ✅ |
-
-✅ = buy + sell confirmed on Solana mainnet. 15 of 18 adapters tested (meteora-damm-v1 excluded as legacy, futarchy-launchpad is fund/claim only).
+| Adapter | Protocol | Buy | Sell | Price | LP | Extra | Tested |
+|---------|----------|:---:|:----:|:-----:|:--:|-------|:------:|
+| raydium-amm-v4 | AMM v4 | ✅ | ✅ | ✅ | | findpool | ✅ |
+| raydium-cpmm | CPMM | ✅ | ✅ | ✅ | | findpool | ✅ |
+| raydium-clmm | CLMM | ✅ | ✅ | ✅ | | findpool | ✅ |
+| raydium-launchlab | Launchlab | ✅ | ✅ | ✅ | | findpool, auto-swap | ✅ |
+| meteora-damm-v1 | Dynamic AMM | ✅ | ✅ | ✅ | | findpool | — |
+| meteora-damm-v2 | CpAmm | ✅ | ✅ | ✅ | full | findpool, create pool | ✅ |
+| meteora-dlmm | DLMM | ✅ | ✅ | ✅ | full | | ✅ |
+| meteora-dbc | DBC | ✅ | ✅ | ✅ | | | ✅ |
+| pumpfun | Bonding Curve | ✅ | ✅ | ✅ | | create coin | ✅ |
+| pumpfun-amm | PumpSwap AMM | ✅ | ✅ | ✅ | | create pool | ✅ |
+| orca | Whirlpool | ✅ | ✅ | ✅ | | | ✅ |
+| byreal-clmm | CLMM | ✅ | ✅ | ✅ | | auto-swap | ✅ |
+| pancakeswap-clmm | CLMM | ✅ | ✅ | ✅ | | | ✅ |
+| fusion-amm | Fusion | ✅ | ✅ | ✅ | | | ✅ |
+| futarchy-amm | Futarchy | ✅ | ✅ | ✅ | | auto-swap | ✅ |
+| futarchy-launchpad | Launchpad | | | | | fund/claim | — |
+| jupiter-ultra | Ultra API | ✅ | ✅ | | | aggregator | ✅ |
+| dflow | Intent API | ✅ | ✅ | | | aggregator | ✅ |
+
+All ✅ adapters confirmed on Solana mainnet with real transactions.
+
+## Percolator — Permissionless Perpetual Futures
+
+Create and operate your own on-chain perpetual futures exchange on Solana. The `PercolatorAdapter` is a standalone class (not `IDexAdapter` — perps are fundamentally different from spot).
+
+### Why This Matters
+
+First mover creates the perp market for a trending token and captures ALL leveraged volume fees. Nobody else has done AI-operated perp exchanges yet. This is the Percolator alpha.
+
+### Quick Start (Programmatic API)
+
+```typescript
+import { PercolatorAdapter } from "outsmart";
+
+const percolator = new PercolatorAdapter();
+
+// 1. Create a perp market (devnet, BONK collateral, $1 initial price)
+const market = await percolator.createMarket({
+  collateralMint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263", // BONK
+  initialPriceE6: 1_000_000n, // $1.00
+  tier: "small",
+  network: "devnet",
+  lpCollateral: 1_000_000_000n, // 1B BONK for LP
+});
+console.log("Market:", market.slabAddress);
+
+// 2. Register a trader
+const { userIdx } = await percolator.initUser(market.slabAddress, "devnet");
+
+// 3. Deposit collateral
+await percolator.deposit(market.slabAddress, userIdx, 500_000_000n, "devnet");
+
+// 4. Open a long position (positive size = long, negative = short)
+await percolator.trade({
+  slabAddress: market.slabAddress,
+  userIdx,
+  lpIdx: market.lpIndex,
+  size: 100_000_000n, // long 100M units
+  network: "devnet",
+});
+
+// 5. Push oracle price (admin-oracle mode)
+await percolator.pushOraclePrice(market.slabAddress, 1_100_000n, "devnet"); // $1.10
+
+// 6. Read market state
+const state = await percolator.getMarketState(market.slabAddress, "devnet");
+console.log("Open interest:", state.engine.openInterestLong);
+
+// 7. Check your position
+const pos = await percolator.getMyPosition(market.slabAddress, "devnet");
+console.log("PnL:", pos?.account.unrealizedPnl);
+```
+
+### PercolatorAdapter Methods (20)
+
+| Method | Description |
+|--------|-------------|
+| `createMarket(params)` | Full 10-step market creation (slab → init → oracle → crank → vAMM → LP) |
+| `initUser(slab, network?, tier?)` | Register a trader account, returns assigned index |
+| `deposit(slab, idx, amount, network?, tier?)` | Deposit collateral |
+| `withdraw(slab, idx, amount, network?, tier?)` | Withdraw collateral |
+| `trade(params)` | Open/close/modify positions via TradeCpi |
+| `closeAccount(slab, idx, network?, tier?)` | Close account and recover rent |
+| `crank(slab, network?, tier?)` | Permissionless keeper crank |
+| `pushOraclePrice(slab, priceE6, network?, tier?)` | Update oracle price (admin only) |
+| `liquidate(slab, targetIdx, network?, tier?)` | Permissionless liquidation |
+| `createInsuranceMint(slab, network?, tier?)` | One-time insurance LP mint creation |
+| `depositInsuranceLP(slab, amount, network?, tier?)` | Deposit into insurance fund |
+| `withdrawInsuranceLP(slab, lpAmount, network?, tier?)` | Withdraw from insurance fund |
+| `getMarketState(slab, network?)` | Read full slab state (header, config, engine, params, accounts) |
+| `getMyPosition(slab, network?)` | Find user's account by owner pubkey |
+| `discoverMarkets(network?)` | Find all markets across all program tiers |
+| `adminForceClose(slab, targetIdx, network?, tier?)` | Admin force-close a position |
+| `resolveMarket(slab, network?, tier?)` | Resolve/freeze market (admin only) |
+| `withdrawInsurance(slab, network?, tier?)` | Withdraw insurance fund balance |
+| `closeSlab(slab, network?, tier?)` | Close slab account and recover rent |
+| `teardownMarket(slab, network?, tier?)` | Full teardown: resolve → force-close all → withdraw → close |
+
+### Math Utilities
+
+Exported for PnL calculation, risk analysis, and pre-trade simulation:
+
+```typescript
+import {
+  computeMarkPnl,
+  computeLiqPrice,
+  computePreTradeLiqPrice,
+  computeTradingFee,
+  computePnlPercent,
+  computeEstimatedEntryPrice,
+  computeFundingRateAnnualized,
+  computeRequiredMargin,
+  computeMaxLeverage,
+  computeVammQuote,
+} from "outsmart";
+```
+
+### Deployed Programs
+
+| Tier | Devnet | Mainnet |
+|------|--------|---------|
+| Small | `FxfD37s1AZTeWfFQps9Zpebi2dNQ9QSSDtfMKdbsfKrD` | `GM8zjJ8LTBMv9xEsverh6H6wLyevgMHEJXcEzyY3rY24` |
+| Medium | `FwfBKZXbYr4vTK23bMFkbgKq3npJ3MSDxEaKmq9Aj4Qn` | — |
+| Large | `g9msRSV3sJmmE3r5Twn9HuBsxzuuRGTjKCVTKudm9in` | — |
+| Matcher | `4HcGCsyjAqnFua5ccuXyt8KRRQzKFbGTJkVChpS7Yfzy` | `DHP6DtwXP1yJsz8YzfoeigRFPB979gzmumkmCxDLSkUX` |
+
+---
 
 ## TX Landing Providers
 
@@ -411,30 +608,7 @@ All swap commands (`buy`, `sell`) accept these options:
 | Flashblock | `FLASHBLOCK_API_KEY` |
 | Node1 | `NODE1_API_KEY` |
 
-Set any provider's API key in your `.env` and it's automatically enabled. The orchestrator sends your transaction through all enabled providers simultaneously for the fastest possible landing.
-
-Durable nonce accounts prevent duplicate executions when the same transaction hits multiple providers concurrently.
-
----
-
-## Snipe (Coming Soon)
-
-The `outsmart snipe` command is not yet available. Real sniping is not just a buy with a tip — it's a background process that:
-
-1. Connects to a **Geyser gRPC stream** (Yellowstone) using your own gRPC key
-2. Listens for **new pool creation events** on the DEX(es) you select
-3. When a new pool is created where the base or quote token matches your target token, it **instantly fires a buy** through concurrent multi-provider TX landing
-4. Runs as a **background process** (cronjob/tmux) on your machine
-
-This requires your own Geyser gRPC key (from Helius, Triton, or another provider). It will be added in a future update.
-
-**In the meantime**, you can achieve a competitive buy on a known pool with:
-
-```bash
-outsmart buy --dex raydium-cpmm --token <MINT> --pool <POOL> --amount 0.5 --tip 0.01 --priority 12000000
-```
-
-This sends your buy transaction with a high priority fee and MEV tip through the TX landing layer.
+Set any provider's API key and it's automatically enabled. The orchestrator sends your transaction through all enabled providers simultaneously for the fastest possible landing.
 
 ---
 
@@ -444,10 +618,10 @@ This sends your buy transaction with a high priority fee and MEV tip through the
 
 | Variable | Description |
 |----------|-------------|
-| `SOLANA_RPC_URL` | Solana mainnet RPC endpoint |
-| `WALLET_PRIVATE_KEY` | Base58-encoded wallet private key |
+| `PRIVATE_KEY` | Base58-encoded wallet private key |
+| `MAINNET_ENDPOINT` | Solana mainnet RPC endpoint |
 
-### Optional — Trading Defaults
+### Optional
 
 | Variable | Description | Default |
 |----------|-------------|---------|
@@ -455,12 +629,9 @@ This sends your buy transaction with a high priority fee and MEV tip through the
 | `DEFAULT_TIP_SOL` | MEV tip in SOL | `0.001` |
 | `DEFAULT_SLIPPAGE_BPS` | Slippage in basis points | `300` |
 | `DEFAULT_PRIORITY_FEE` | Priority fee in microLamports per CU | `4000` |
-| `JUPITER_API_KEY` | Jupiter Ultra/Metis API key ([portal.jup.ag](https://portal.jup.ag)) | on-chain fallback |
-| `DFLOW_API_KEY` | DFlow intent API key | |
-
-### Optional — TX Landing Provider Keys
-
-See the [TX Landing Providers](#tx-landing-providers) table above.
+| `DEVNET_ENDPOINT` | Solana devnet RPC endpoint (for Percolator) | not set |
+| `JUPITER_API_KEY` | Jupiter Ultra API key ([portal.jup.ag](https://portal.jup.ag)) | works without key |
+| `DFLOW_API_KEY` | DFlow intent API key ([pond.dflow.net](https://pond.dflow.net/build/api-key)) | required for dflow |
 
 ---
 
@@ -484,6 +655,7 @@ const result = await cpmm.buy({
   opts: { slippageBps: 300, tipSol: 0.001 },
 });
 console.log("TX:", result.txSignature);
+console.log("Received:", result.amountOut);
 
 // Sell
 const sellResult = await cpmm.sell({
@@ -507,18 +679,19 @@ For AI agent integration (MCP server, OpenClaw workflows), see [outsmart-agent](
 ## Testing
 
 ```bash
-npm test                 # All tests
-npm run test:registry    # Registry smoke test (no RPC needed)
+npm run test:unit        # 43 CI-safe unit tests (no RPC/SOL needed)
+npm run test:registry    # Registry smoke test
 npm run test:raydium     # Raydium adapters (mainnet)
 npm run test:meteora     # Meteora adapters (mainnet)
 npm run test:pumpfun     # PumpFun + PumpSwap (mainnet)
 npm run test:orca        # Orca Whirlpool (mainnet)
 npm run test:clmm        # Byreal + PancakeSwap CLMM (mainnet)
-npm run test:futarchy    # Fusion + Futarchy AMM (mainnet)
+npm run test:fusion      # Fusion + Futarchy AMM (mainnet)
 npm run test:api         # Jupiter Ultra + DFlow (mainnet)
+npm run test:percolator  # Percolator perps (devnet)
 ```
 
-Mainnet tests require `WALLET_PRIVATE_KEY` and `SOLANA_RPC_URL` env vars. Tests use tiny amounts (0.02 SOL per buy). Run suites one at a time — tests share a wallet and cannot run in parallel.
+Mainnet tests require `PRIVATE_KEY` and `MAINNET_ENDPOINT` env vars. Percolator tests require `DEVNET_ENDPOINT`. Tests use tiny amounts (0.002 SOL per buy). Run suites one at a time — tests share a wallet and cannot run in parallel.
 
 ---
 
@@ -532,10 +705,17 @@ src/
 │   ├── types.ts           # IDexAdapter interface
 │   ├── index.ts           # DexRegistry singleton
 │   ├── shared/clmm-base.ts
+│   ├── percolator/
+│   │   ├── adapter.ts     # PercolatorAdapter (15 methods)
+│   │   └── core/          # Vendored @percolator/core SDK
 │   └── 18 adapter files
 ├── dexscreener/           # Market data (DexScreener API)
-├── helpers/               # Config, wallet, Token-2022 utils
+├── helpers/
+│   ├── config.ts          # Wallet, connection, env loading
+│   ├── wallets.ts         # Multi-wallet management
+│   └── logger.ts          # Structured logger
 └── transactions/
+    ├── send-rpc.ts        # sendAndConfirmVtx (standard swaps)
     └── landing/
         ├── orchestrator.ts    # Multi-provider concurrent submission
         ├── nonce-manager.ts   # Durable nonce for dedup
@@ -551,17 +731,11 @@ https://discord.gg/dc3Kh3Y3yJ
 
 Contributions welcome. Fork, branch, PR.
 
-```bash
-git checkout -b feature/your-feature
-git commit -m 'add your feature'
-git push origin feature/your-feature
-```
-
 ## Disclaimer
 
 This software is provided "as is", without warranty of any kind. Use at your own risk. The authors take no responsibility for any financial loss. Users are responsible for ensuring compliance with applicable laws.
 
-Never share your private keys. The `.env` file is in `.gitignore` for your safety.
+Never share your private keys. Wallet keys are stored in `~/.outsmart/` with owner-only permissions.
 
 ## License