Solana Swap CLI

A developer-focused CLI tool for executing token swaps on Solana mainnet via Jupiter aggregator. Built as a clean, forkable reference implementation - if you're learning Solana backend development, this shows you how wallet interaction, RPC calls, quote fetching, validation, and transaction execution actually fit together.

This is not a consumer product. It's a starting point for developers.

---

What it does

• Connects to your Solana wallet via local keypair
• Fetches live token balances and USD prices via Helius RPC
• Displays interactive token selection with arrow keys
• Gets best swap route and quote from Jupiter aggregator
• Validates before executing — checks token balance, SOL balance for gas, ATA creation fees
• Executes swap on mainnet and returns transaction signature + Solana Explorer link

---

Demo

✓ Please select what you want: » Swap
✓ Select token to sell » USDC    $0.9999
✓ Select token to buy  » SOL     $89.8510
✓ Enter your amount ... 1

1 USDC -> 0.011152 SOL
USD Value: 1.001738
Do you agree?
✓ Confirm Swap? ... yes

Tx: https://explorer.solana.com/tx/3VMj9Xu4...

---

Project structure

src/
├── connection/
│   └── connection.ts    # Singleton RPC connection (Helius or Solana)
├── wallet/
│   └── wallet.ts        # Keypair loading, balance fetching
├── tokens/
│   └── token.ts         # Token list, metadata, USD prices
├── jupiter/
│   ├── quote.ts         # Jupiter quote API integration
│   └── swap.ts          # Swap execution, transaction signing
├── validation/
│   └── validate.ts      # Pre-swap checks (balance, gas, ATA fees)
├── ui/
│   └── display.ts       # Terminal UI, interactive prompts
└── index.ts             # Entry point, orchestrates the full flow

Each module has a single responsibility. If you want to understand how Jupiter swaps work, start with jupiter/quote.ts then jupiter/swap.ts. If you want to understand wallet interaction, start with wallet/wallet.ts.

---

Setup

Prerequisites: Node.js 18+, a Solana wallet keypair file

git clone https://github.com/Enmilo-dev/solana-cli-swap.git
cd solana-cli-swap
npm install

Create .env:

HELIUS_RPC=your_helius_rpc_url
SOLANA_RPC=https://api.mainnet-beta.solana.com
HELIUS=HELIUS
WALLET_PATH=path/to/your/keypair.json

npm run start

---

Adding tokens

Open src/tokens/token.ts. Tokens are stored as a simple object:

export const tokens = {
  SOL:  { mint: "So11111111111111111111111111111111111111112", decimals: 9 },
  USDC: { mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", decimals: 6 },
  // add any SPL token here
}

Add any SPL token by providing its mint address and decimals. That's it.

---

Validation logic

Before every swap the CLI checks in this order:

1. Wallet is a valid on-curve Solana address
2. Sufficient SOL for gas fees
3. Sufficient token balance for the swap amount
4. If output token ATA doesn't exist — checks SOL covers ATA creation cost (~0.002 SOL)
5. Priority fee buffer if needed

If any check fails, the swap is blocked before touching Jupiter.

---

Why this exists

Most Solana learning resources show you isolated concepts. This shows you how they connect in a real flow — RPC connection → wallet → token accounts → Jupiter API → validation → transaction execution.

Fork it, break it, rebuild it. That's the point.

This is also the backend foundation for a larger swap dApp I'm building. CLI first, then frontend.

---

Tech stack

• @solana/web3.js — Solana RPC interaction
• Jupiter V1 API — swap routing and quote fetching
• Helius RPC — enhanced token balance fetching
• @inquirer/prompts — interactive terminal UI
• TypeScript

---

License

MIT