Skip to content

README.md

Latest commit

 

History

History
139 lines (97 loc) · 3.94 KB

README.md

File metadata and controls

139 lines (97 loc) · 3.94 KB

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