Solana Market ID CLI

Find Serum v1/v3 (and OpenBook v2 soon) market IDs for a token (pair) and inspect market metadata (bids/asks/event queue/request queue, vaults, top-of-book). 
Fast & reliable: uses Serum's official on-chain layout to build tight RPC filters (no heavy scans).

Tip jar: 88888kfJ3SRayhz1dHj9msNm99G5iVZ7FBN8MRjhEdK8

---

 Features

- Find markets by base & quote mint:
 - RPC-only exact filters (recommended)
 - Optional Helius-assisted program scan with automatic RPC fallback
- Inspect a known market: print metadata, queue sizes, and top-of-book (Serum)
- Configurable via flags or .env (RPC URL(s), program IDs, Helius API key)
- Windows-friendly (quotes & line continuation notes included)

---

 Installation

 Option A - Run instantly (no install)

bash
npx solana-market-id <args


 Works after publishing to npm. For local development, use npx ts-node against src/cli.ts or dist/cli.js after build.

 Option B - Global install

bash
npm i -g solana-market-id
solana-market-id --help


 Option C - From source

bash
 Requires Node.js = 18
git clone <your-repo-url
cd <repo

 Install dependencies
npm i

 Build to dist/
npm run build

 Run
node dist/cli.js --help
 or dev run with ts-node (if installed)
npx ts-node src/cli.ts --help


---

 Dependencies

Installed automatically via npm i:

- @solana/web3.js
- @project-serum/serum
- dotenv
- node-fetch (v2)
- Dev: typescript, @types/node, @types/node-fetch, rimraf

---

 .env Configuration (optional)

Create a .env file next to your project to set defaults:

ini
 (RECOMMENDED) Your default RPC endpoint (dedicated RPC avoids throttling)
RPC_URL=https://api.mainnet-beta.solana.com

 Optional: comma-separated additional RPCs for failover
RPC_URLS=https://api.mainnet-beta.solana.com,https://solana-api.projectserum.com

 Required only if you use --use-helius
HELIUS_API_KEY=YOUR_HELIUS_KEY

 Optional overrides (mainnet defaults used if omitted)
SERUM_V1_PROGRAM_ID=srmqPvymJeFKQ4zGQed1GFppgkRHL9kaELCbyksJtPX
SERUM_V3_PROGRAM_ID=9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZbG8SxwP3E
OPENBOOK_V2_PROGRAM_ID=opnb2LAfJYbRMAHHvqjCwQxanZn7ReEHp1k81EohpZb


Which must be filled?
- Required: none (the CLI will still run using public RPC) 
- Recommended: RPC_URL (to avoid rate limiting) 
- Required only when using Helius mode: HELIUS_API_KEY

 Do not commit .env to source control.

---

 CLI Usage

 Help

bash
solana-market-id --help


 Find markets (RPC-only; fast & reliable)

bash
solana-market-id <BASE_MINT --quotes <QUOTE1,QUOTE2,... --program <serum1|serum3|all --rpc "<RPC_URL"


Example (Serum v1; Windows/POSIX):
bash
solana-market-id 9kt93AW5QMjFL6ZxomnSq3FbWiU5ibNeTSgBz9UDFSB6 --quotes EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --program serum1 --rpc "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"


 Optional: Helius-assisted discovery

bash
solana-market-id <BASE_MINT --quotes <QUOTE1,QUOTE2,... --program serum1 --use-helius --api-key <HELIUS_KEY --pages 60 --rpc "<RPC_URL"


- Scans program-level transactions with source=SERUM, then verifies candidates via RPC
- Auto-fallback to RPC for the pair if Helius yields nothing

 Inspect a known market

bash
solana-market-id --known-market <MARKET_ID [--depth 10] --rpc "<RPC_URL"


Outputs:
- Base/Quote mints
- Bids / Asks / Event Queue / Request Queue accounts
- Vault accounts
- Live counts (Event Q, Request Q, bids, asks)
- Top N price levels for bids/asks (aggregated levels; use --depth to change N)

 Quick tests

bash
solana-market-id --test1 your token vs WSOL
solana-market-id --test2 token vs USDC (DEXLAB example)


---

 Flags (Full List)

| Flag | Alias | Value | Required | Description |
|---|---|---|---|---|
| --help | -h | - | No | Show usage. |
| --program | -P | serum1 \| serum3 \| all | No (default all) | Which DEX programs to query. |
| --quotes | -q | Comma-separated mint list | No (defaults: USDC, WSOL) | One or more quote mints to check against base. |
| --rpc | -r | URL | No (falls back to .env / public) | RPC endpoint for this run. |
| --use-helius | -H | - | No | Enable Helius-assisted program scan. |
| --api-key | -k | Helius key | Only if using --use-helius | API key for Helius. Can be set in .env. |
| --pages | -pg | Number | No (default 20) | Helius pagination depth (100 tx/page). |
| --known-market | -km | Market address | No | Inspect known Serum market metadata & top-of-book. |
| --depth | -d | Number | No (default 10) | L2 depth for top-of-book output in --known-market. |
| --json | - | - | No | Output machine-readable JSON for results. |
| --test1 | - | - | No | Test: your token vs WSOL. |
| --test2 | - | - | No | Test: token vs USDC (DEXLAB). |

---

 Examples

 Serum v1: Base vs USDC

bash
solana-market-id 9kt93A... --quotes EPjFWd... --program serum1 --rpc "https://api.mainnet-beta.solana.com"


 Multi-quote search

bash
solana-market-id 9kt93A... --quotes EPjFWd...,So1111... --program serum1 --rpc "https://api.mainnet-beta.solana.com"


 Serum v3 and v1

bash
solana-market-id 9kt93A... --quotes EPjFWd... --program all --rpc "https://api.mainnet-beta.solana.com"


 Inspect known market (e.g., the one you verified)

bash
solana-market-id --known-market EUwL9Lg... --depth 25 --rpc "https://api.mainnet-beta.solana.com"


 JSON for scripting

bash
solana-market-id 9kt93A... --quotes EPjF... --program serum1 --json
 pipe to jq
solana-market-id 9kt93A... --quotes EPjF... --program serum1 --json | jq .


---

 Windows Notes

- Do not include angle brackets around values (CMD treats <... as I/O redirection).
- Quote RPC URLs: 
 --rpc "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY"
- Line continuation:
 - CMD.exe: use ^ at line end.
 - PowerShell: use backtick at line end.
 - Backslash \ (POSIX style) does not work in CMD.

---

 How it Works (Why it is fast)

- Uses @project-serum/serum's official state layout:
 - We read the offsets of baseMint/quoteMint and the span for the market account.
 - We pass exact filters (dataSize + two memcmps) to getProgramAccounts.
 - RPC returns only a tiny result set avoids throttling/deprioritization.
- Helius path (optional) scans program-level transactions and verifies candidates via RPC; auto-falls back to RPC if empty.

Note on Top-of-Book: 
getL2(N) aggregates orders into price levels (e.g., multiple orders at 83 collapse into one level). 
So you may see Asks Length: 11 but only 7 aggregated price levels printed.

---

 Troubleshooting

- Request deprioritized due to number of accounts requested 
 likely using a broad scan. The default RPC-only path uses exact layout filters and should not trigger this. Use a dedicated RPC if possible.

- Cannot create a string longer than 0x1fffffe8 characters 
 That is from fetching too many accounts. The CLI avoids this by default; ensure not forcing broad scans.

- No markets found 
 - Make sure you selected the correct program (--program serum1 for legacy v1). 
 - Try the reverse pair (quote/base). 
 - Confirm the mints are correct base58 addresses. 
 - Use --known-market <address to validate the market exists & belongs to that program.

- Windows parsing issues 
 - Always quote the RPC URL. 
 - Remove < around values. 
 - Use ^ (CMD) or (PowerShell) for multiline commands.

---

 Security

- Read-only: no private keys required or used.
- Do not commit your HELIUS_API_KEY to Git.
- Prefer using .env over passing secrets inline on the command line (shell history).

---

 Changelog (What is different vs naive scanners)

- Replaced broad scans with Serum layout-based exact filters.
- Added Helius-assisted discovery with auto RPC fallback per pair.
- Introduced known market inspector with queue sizes & L2 top-of-book.
- Added --depth for customizable L2 output.
- Windows-friendly CLI UX (quotes/continuation guidance).

---

 License

MIT Abraham Dixit-Blessed