solana-trade

v1.1.0

Published

3 months ago

A comprehensive Solana trading library supporting multiple DEXs and MEV protection services

Downloads

146

🚀 Solana Trade

A comprehensive, production-ready Solana trading library supporting 15+ DEXs with advanced MEV protection, built for both programmatic integration and CLI usage. Perfect for your trading bots / Solana dApps!

✨ Features

🏪 15+ DEX Support: Pump.fun, PumpSwap, Raydium (AMM/CLMM/CPMM/Launchpad), Orca, Meteora (DLMM/DAMM/DBC), Moonit, Heaven, Sugar, Boop.fun
🛡️ Advanced MEV Protection: Jito, Nozomi, Astralane with regional optimization
⚡ High Performance: Optimized transaction building with automatic pool discovery
🎯 Smart Routing: Intelligent provider selection based on tip amounts and availability
💻 Dual Interface: Full-featured programmatic API + powerful CLI
📦 TypeScript: Complete type definitions
🔧 Configurable: Extensive customization options for advanced users
📊 Transaction Control: Priority fees, slippage protection, simulation control
📈 Price & Curve Insight: Get price in SOL/lamports for any mint, plus bonding curve completion percent for launchpads
🌐 Multi-Region: Global MEV protection endpoints for optimal performance

📋 Supported Markets & Protocols

| Protocol | Market ID | |----------|-----------| | Pump.fun | PUMP_FUN | | Pump Swap | PUMP_SWAP | | Raydium AMM | RAYDIUM_AMM | | Raydium CLMM | RAYDIUM_CLMM | | Raydium CPMM | RAYDIUM_CPMM | | Raydium Launchpad | RAYDIUM_LAUNCHPAD | | Orca Whirlpool | ORCA_WHIRLPOOL | | Meteora DLMM | METEORA_DLMM | | Meteora DAMM V1 | METEORA_DAMM_V1 | | Meteora DAMM V2 | METEORA_DAMM_V2 | | Meteora DBC | METEORA_DBC | | Moonit | MOONIT | | Heaven XYZ | HEAVEN | | Sugar | SUGAR | | Boop.fun | BOOP_FUN |

🛡️ Transaction Senders / MEV Protection Services

Jito Labs

Minimum Tip: No minimum (bundles require ≥1000 lamports)
Environment: JITO_UUID
Regions: MAINNET, AMS, DUB, FRA, LON, NY, SLC, SG, TYO

Nozomi

Minimum Tip: 0.001 SOL
Environment: NOZOMI_API_KEY (standard), NOZOMI_API_KEY_ANTIMEV (anti-MEV)
Regions: PITT, TYO, SG, EWR, AMS, FRA

Astralane

Minimum Tip: 0.00001 SOL
Environment: ASTRALANE_API_KEY
Regions: FR, LAX, JP, NY, AMS, LIM

🚀 Installation

npm install solana-trade
# or
yarn add solana-trade
# or
pnpm add solana-trade

⚡ Quick Start

Programmatic Usage

import { SolanaTrade } from 'solana-trade';
import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';

// Initialize with custom RPC (optional)
const trader = new SolanaTrade('https://your-premium-rpc.com');

// Create wallet from private key
const wallet = Keypair.fromSecretKey(bs58.decode('your-private-key-base58'));

// Buy 0.1 SOL worth of tokens
const buySignature = await trader.buy({
  market: 'PUMP_FUN',
  wallet: wallet,
  mint: 'So11111111111111111111111111111111111111112',
  amount: 0.1,
  slippage: 5, // 5%
  sender: 'JITO', // Optional MEV protection
  region: 'NY', // Optional region preference
  antimev: true // Enable anti-MEV features
});

console.log('Buy transaction:', buySignature);

// Sell 1,000,000 tokens
const sellSignature = await trader.sell({
  market: 'PUMP_FUN',
  wallet: wallet,
  mint: 'So11111111111111111111111111111111111111112',
  amount: 1000000,
  slippage: 5,
  priorityFeeSol: 0.001, // Higher priority fee
  tipAmountSol: 0.01 // MEV protection tip
});

console.log('Sell transaction:', sellSignature);

// Query spot price (SOL or lamports) & bonding curve percent
const { price, bondingCurvePercent } = await trader.price({
  market: 'RAYDIUM_CPMM',
  mint: 'TokenMintAddress',
  unit: 'SOL' // or 'LAMPORTS'
});

console.log('Price (SOL):', price, 'Curve %:', bondingCurvePercent);

// Get transaction object without sending (Legacy Transaction)
const transaction = await trader.buy({
  market: 'PUMP_FUN',
  wallet: wallet,
  mint: 'So11111111111111111111111111111111111111112',
  amount: 0.1,
  slippage: 5,
  send: false // Returns Transaction object instead of sending
});

console.log('Transaction object:', transaction);
// You can then send it manually or modify it further

CLI Usage

# Install globally for CLI access
npm install -g solana-trade

# Buy tokens with Jito MEV protection
solana-trade \
  --market PUMP_FUN \
  --direction buy \
  --mint So11111111111111111111111111111111111111112 \
  --amount 0.1 \
  --slippage 5 \
  --private-key your-base58-private-key \
  --sender JITO \
  --tip 0.001 \
  --region NY

# Get spot price via CLI (outputs JSON { price, bondingCurvePercent })
solana-trade \
  --price \
  --market RAYDIUM_CPMM \
  --mint TokenMintAddress \
  --unit SOL

# Sell tokens with custom priority fee
solana-trade \
  --market RAYDIUM_CLMM \
  --direction sell \
  --mint TokenMintAddress \
  --amount 1000000 \
  --slippage 3 \
  --private-key your-base58-private-key \
  --priority-fee 0.005 \
  --skip-simulation true

📖 API Documentation

SolanaTrade Class

Constructor

new SolanaTrade(rpcUrl?: string)

Parameters:

rpcUrl (optional): Custom RPC endpoint URL. Defaults to process.env.RPC_URL or Solana mainnet-beta.

Methods

`buy(params: BuyParams): Promise<string | Transaction>`

Execute a buy transaction.

Parameters:

interface BuyParams {
  market: string;                    // Market identifier (see supported markets)
  wallet: Keypair;                   // Solana wallet keypair
  mint: PublicKey | string;          // Token mint address
  amount: number;                    // SOL amount to spend
  slippage: number;                  // Slippage tolerance (0-100)
  priorityFeeSol?: number;           // Priority fee in SOL (default: 0.0001)
  tipAmountSol?: number;             // MEV protection tip in SOL (default: 0)
  poolAddress?: PublicKey | string;  // Specific pool address (optional, will skip pool discovery if provided)
  send?: boolean;                    // Whether to send transaction (default: true)
  sender?: 'ASTRALANE' | 'NOZOMI' | 'JITO'; // MEV protection service
  antimev?: boolean;                 // Enable anti-MEV features (default: false)
  region?: string;                   // Preferred region for MEV service
  skipSimulation?: boolean;          // Skip transaction simulation (default: false)
  skipConfirmation?: boolean;        // Skip confirmation waiting (default: false)
  additionalInstructions?: TransactionInstruction[]; // Appends right after market instructions
}

`sell(params: SellParams): Promise<string | Transaction>`

Execute a sell transaction. Same parameters as buy(), except amount represents token quantity.

Adding additional instructions

You can provide custom Solana TransactionInstruction items via additionalInstructions. They will be appended immediately after the market swap instructions and before any provider tip instructions:

import { SystemProgram } from '@solana/web3.js';

await trader.buy({
  market: 'PUMP_FUN',
  wallet,
  mint: 'So11111111111111111111111111111111111111112',
  amount: 0.1,
  slippage: 5,
  additionalInstructions: [
    SystemProgram.transfer({
      fromPubkey: wallet.publicKey,
      toPubkey: wallet.publicKey, // example noop self-transfer
      lamports: 1,
    }),
  ],
});

🌍 Environment Variables

Core Configuration

# RPC Endpoint (optional, defaults to public mainnet)
RPC_URL=https://your-rpc-endpoint.com

MEV Protection Services

# Jito Labs
JITO_UUID=your-jito-uuid

# Nozomi
NOZOMI_API_KEY=your-nozomi-api-key
NOZOMI_API_KEY_ANTIMEV=your-nozomi-antimev-key  # Optional: for enhanced protection

# Astralane
ASTRALANE_API_KEY=your-astralane-api-key

PumpSwap

# Milliseconds to wait for PumpSwap pool readiness before decoding
# Prevents early "invalid account discriminator" during snipes/migrations
# Default: 5000
PUMPSWAP_POOL_READY_TIMEOUT_MS=5000

📝 CLI Reference

Required Arguments

--market: Market identifier (see supported markets table)
--direction: Transaction direction (buy or sell)
--mint: Token mint address
--amount: Amount (SOL for buy, tokens for sell)
--slippage: Slippage tolerance (0-100)
--private-key: Base58-encoded private key

Optional Arguments

--priority-fee: Priority fee in SOL (default: 0.0001)
--tip: MEV protection tip in SOL (default: 0)
--pool-address: Specific pool address
--sender: MEV protection service (JITO, NOZOMI, ASTRALANE)
--antimev: Enable anti-MEV features (true, false)
--region: Preferred region code
--skip-simulation: Skip transaction simulation (true, false)
--skip-confirmation: Skip confirmation waiting (true, false)

🛠️ Error Handling

try {
  const result = await trader.buy({
    market: 'PUMP_FUN',
    wallet: wallet,
    mint: 'invalid-mint-address',
    amount: 0.1,
    slippage: 5,
  });
  console.log('Success:', result);
} catch (error) {
  if (error.message.includes('Simulation failed')) {
    console.error('Transaction would fail:', error);
    // Handle simulation failure
  } else if (error.message.includes('HTTP')) {
    console.error('Network error:', error);
    // Handle network issues
  } else {
    console.error('Unknown error:', error);
    // Handle other errors
  }
}

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

git clone https://github.com/FlorianMgs/solana-trade.git
cd solana-trade
npm install

# Build the project
npm run build

# Test the CLI
npm run cli -- --help

Contribution Guidelines

Fork the repository and create your feature branch
Follow TypeScript best practices and existing code style
Update documentation for any API changes
Test thoroughly across different markets and scenarios
Submit a pull request with a clear description

Areas We Need Help With

🚀 New DEX/Launchpad Integrations: We more than welcome new launchpads and DEXs to integrate their protocols into the project! This helps expand trading opportunities for all users.
🔥 Transaction senders: If you're running a transaction provider service, don't hesitate to add it!
📚 Documentation: Examples, tutorials, API documentation
🐛 Bug Reports: Issue identification and reproduction steps
✨ New Features: Optimization improvements, additional functionality

DEX/Launchpad Integration

New protocols are more than welcome! If you're a DEX or launchpad team looking to integrate:

Contact us via GitHub Issues or email to discuss integration
Provide SDK/API documentation for your protocol
Share test environments and pool addresses for testing
Collaborate on implementation - we'll help build the integration
Benefit from exposure to our user base once integrated

☕ Buy Me a Coffee

If this library helps your project, consider supporting its development:

Donate SOL

Address: CDuvRTHRaPFEQJYdHsEWpuE3yRB49Azi9e5g8Yi9Xm4d

Why Support?

🔬 Research & development: New DEX integrations, optimization
🛠️ Maintenance: Bug fixes, security updates, dependency management
📖 Documentation: Tutorials, examples, comprehensive guides
🆘 Support: Community assistance, issue resolution

The library includes a small 0.15% fee on buy transactions to support development (disable with DISABLE_DEV_TIP=true if needed). Your donations and keeping the fee active help maintain this project! 🙏

📜 License

MIT License - see the LICENSE file for details.

🔗 Links

GitHub: https://github.com/FlorianMgs/solana-trade
NPM: https://www.npmjs.com/package/solana-trade
Issues: https://github.com/FlorianMgs/solana-trade/issues
Discussions: https://github.com/FlorianMgs/solana-trade/discussions

🆘 Support & Community

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions

⚠️ Disclaimer

Important: Trading cryptocurrencies involves substantial risk of loss and is not suitable for all investors. This software is provided "as-is" without any warranties or guarantees. The authors and contributors are not responsible for any financial losses incurred through the use of this software.

Key Risks:

Market Risk: Cryptocurrency prices are highly volatile
Technical Risk: Smart contract bugs, network issues, transaction failures
MEV Risk: Sandwich attacks, front-running despite protection measures
Slippage Risk: Price movement during transaction execution

Best Practices:

Only trade with funds you can afford to lose
Test with small amounts first
Understand the risks of each DEX and token
Keep your private keys secure
Monitor transactions carefully

Made with ❤️ by FlorianMgs (Madgic)

Pls leave a ⭐ star on GitHub!