Documentation

What is ECHO

ECHO is a Solana on-chain airdrop protocol built around a simple loop: creator fees accumulate in an engine wallet, the radar finds the hottest trending coin, Jupiter buys it with the fee pot, and the bag is airdropped pro-rata to every qualifying $ECHO holder — automatically, every 30 minutes, with no claiming step.

The protocol is fully transparent. Every swap and airdrop is a public Solana transaction. The engine wallet address is published on the site. Holders can verify every drop on Solscan.

Stack

Architecture

The codebase is intentionally flat — one process, no build step, no framework. Each module has a single responsibility.

Module dependencies

index.js imports engine, indexer, and server, each of which imports config and db. engine additionally imports trending, solnative, pda, and bot. There are no circular deps.

Drop cycle

The engine runs a tick() every 5 seconds. When Date.now() ≥ nextDropAt, runDrop() fires. The cycle repeats on a fixed interval (DROP_INTERVAL_MIN, default 30 min).

Budget math

balance       = engine wallet SOL balance
spendable     = max(0, balance − RESERVE_SOL)
dropLamports  = floor(spendable × SPLIT_DROP)
dropLamports  = min(dropLamports, MAX_DROP_SOL × 10⁹)   // per-drop cap
rakeLamports  = floor(spendable × SPLIT_RAKE)

  → SPLIT_DROP + SPLIT_RAKE must be ≤ 1.0
  → excess above MAX_DROP_SOL rolls over to the next cycle

Trending radar

Implemented in src/trending.js. Source priority is controlled by TRENDING_SOURCE.

Holder indexer

Implemented in src/indexer.js. Polls Helius for every token account under TOKEN_MINT and maintains a live snapshot in the holders SQLite table.

Helius getTokenAccounts

Uses Helius's proprietary DAS RPC method (not a standard Solana method). Paginates with a cursor field, up to 100 pages × 1000 accounts = 100k holders maximum. Multiple accounts owned by the same wallet are summed. Wallets with zero balance after summing are deleted from the table.

POST https://mainnet.helius-rpc.com/?api-key=<KEY>
{
  "jsonrpc": "2.0",
  "method": "getTokenAccounts",
  "params": { "mint": "<TOKEN_MINT>", "limit": 1000, "cursor": "<prev>" }
}

Recipient selection

getRecipients() applies three filters in order:

• Dust filter — balance < MIN_HOLD_TOKENS — removes wallets holding fewer than the minimum token amount. Default: 100,000 tokens.
• Exclusion list — removes all addresses in EXCLUDED_WALLETS. Critical: the pump.fun bonding curve holds a large fraction of supply and must always be excluded, or nearly the entire airdrop goes to the curve and is lost.
• Top-N cap — sorts by balance descending and takes the top MAX_RECIPIENTS wallets. Default: 150. Each recipient requires an ATA creation instruction (~0.002 SOL rent), so the cap exists for economic reasons.

SPL airdrop mechanism

Implemented in Engine.distribute() inside src/engine.js. Executes entirely with raw Solana instructions — no SPL helper libraries required.

Per-recipient share

totalBal = sum of all recipient.balance values
share_i  = floor(totalRaw × (balance_i / totalBal))
  where totalRaw = floor(tokensBought × 10^decimals)

Rounding is floor, so the engine wallet keeps any dust remainder.

Transaction structure

Each transaction handles 6 recipients. For each recipient, two instructions are packed:

Configuration

All configuration is via environment variables. Parsed in src/config.js. No config files — change a var and restart.

Chain required in live mode

Modes

Drop cycle

Recipient eligibility

Trending source

Infrastructure

Twitter / X bot optional

Mock / demo mode

HTTP API

Two read-only JSON endpoints. The frontend polls both every 4 seconds. No authentication.

{
  "brand":          { "name", "ticker", "tagline", "buyUrl" },
  "ca":             string,          // TOKEN_MINT — drives Copy CA
  "mock":           boolean,
  "dryRun":         boolean,
  "now":            number,          // unix seconds
  "nextDropAt":     number,          // unix seconds
  "cycleSec":       number,          // DROP_INTERVAL_MIN × 60
  "current":        { "mint", "symbol", "name", "reason" } | null,
  "tankSol":        number,          // spendable SOL (balance − RESERVE_SOL)
  "totalSol":       number,          // sum of sol_spent across all done drops
  "dropsDone":      number,
  "distinctCoins":  number,
  "holders":        number,          // wallets with balance ≥ MIN_HOLD_TOKENS
  "engineWallet":   string | null,
  "dropIntervalMin": number
}

[{
  "id":             number,
  "at":             number,          // unix seconds
  "target_mint":    string,
  "target_symbol":  string,
  "target_name":    string,
  "reason":         string,          // why this coin was chosen
  "sol_spent":      number,
  "tokens_bought":  number,
  "recipients":     number,
  "swap_sig":       string,          // tx signature or "DRY_RUN"
  "status":         "done" | "skipped" | "failed",
  "note":           string
}]

Database schema

SQLite, WAL mode. File path: DB_PATH (default ./data/echo.db).

wallet       TEXT PRIMARY KEY    -- base58 owner address
balance      REAL NOT NULL       -- UI units (raw / 10^decimals)
last_seen    INTEGER             -- unix seconds of last Helius observation
updated_at   INTEGER

id             INTEGER PRIMARY KEY AUTOINCREMENT
at             INTEGER NOT NULL    -- unix seconds
target_mint    TEXT
target_symbol  TEXT
target_name    TEXT
reason         TEXT                -- "top boosted on dexscreener" etc.
sol_spent      REAL DEFAULT 0
tokens_bought  REAL DEFAULT 0
recipients     INTEGER DEFAULT 0
swap_sig       TEXT                -- tx signature or "DRY_RUN"
status         TEXT DEFAULT 'done' -- done | skipped | failed
note           TEXT

key    TEXT PRIMARY KEY
value  TEXT

The meta table is used for persistent state across restarts (currently reserved for future use — state is reconstructed from drops and live RPC calls).

Scripts

npm run keygen

Generates a fresh Solana keypair using only node:crypto (no dependencies). Prints the public address and base58 private key. Use this to create the engine wallet — then launch your pump.fun coin from this wallet so it becomes the creator.

node scripts/keygen.js

→ Public address (use as the pump.fun creator wallet):
    73FL5Jwx...
→ POT_WALLET_SECRET (keep secret!):
    5Kd3NbFMvy...

node scripts/prelaunch.js <CA> [siteUrl]

Offline pre-launch helper. Takes your token's mint address (CA) and derives the pump.fun bonding curve address using the same PDA math as the Solana SDK. Outputs a ready-to-copy environment variable block.

node scripts/prelaunch.js CAnht1PfUb... https://yoursite.com

→ CA:            CAnht1PfUb...
→ Bonding curve: BZoQUSnD9p...   (must be in EXCLUDED_WALLETS)
→ ... full env block ...

Running locally

Demo mode (zero keys)

MOCK=1 PORT=5000 node src/index.js

Simulated fees, synthetic holders, fake drops on a 40-second cycle. No chain calls. Safe for UI development and testing.

Dry-run mode (live reads, no transactions)

MOCK=0 DRY_RUN=1 \
  HELIUS_API_KEY=... \
  TOKEN_MINT=... \
  ENGINE_WALLET_SECRET=... \
  DROP_INTERVAL_MIN=2 \
  PORT=5000 node src/index.js

Polls real holders from Helius, picks a real trending coin, calculates a real buy — but sends no transactions. Drops are logged with swap_sig = DRY_RUN. Use a short DROP_INTERVAL_MIN (1–2) to quickly verify the full cycle works before going live.

Live mode

MOCK=0 DRY_RUN=0 PORT=5000 node src/index.js

Real swaps and real airdrops. Ensure ENGINE_WALLET_SECRET is set, the engine wallet is funded, and EXCLUDED_WALLETS includes the bonding curve + engine wallet + your personal wallets.

Launch checklist

• Run npm run keygen → save public address + store secret in ENGINE_WALLET_SECRET
• Launch the pump.fun coin from the engine wallet address (this makes it the creator)
• Run node scripts/prelaunch.js <CA> → copy the derived bonding curve address
• Set TOKEN_MINT to the coin's CA
• Set EXCLUDED_WALLETS = <bonding curve>,<engine wallet>,<your personal wallets>
• Set BUY_URL = https://pump.fun/coin/<CA>
• Set RAKE_WALLET to your personal wallet
• Fund the engine wallet with ≥ 0.3 SOL (covers RESERVE_SOL + ATA rent + a few drops)
• Start with DRY_RUN=1 and DROP_INTERVAL_MIN=2 — watch for [engine] 📡 DROP in logs
• Verify the drop log shows real holders and a real Jupiter quote resolved
• Flip DRY_RUN=0 and DROP_INTERVAL_MIN=30 — restart
• Monitor the first live drop on Solscan before announcing publicly

Security notes

Engine wallet

The engine wallet holds real SOL and signs real transactions. Store ENGINE_WALLET_SECRET only in an environment secret manager (Replit Secrets, Doppler, etc.) — never in a file, never in a repo, never in a log.

API endpoints are public and unauthenticated

/api/state and /api/drops are intentionally public — transparency is a feature of the protocol. They are read-only. No write endpoints exist.

Bonding curve exclusion

The bonding curve address for any pump.fun token is deterministic and can be derived offline with scripts/prelaunch.js. Always derive it before launch and add it to EXCLUDED_WALLETS. Failure to do so means most of every airdrop is lost.

Recipient cap disclosure

The MAX_RECIPIENTS=150 cap and MIN_HOLD_TOKENS=100000 dust filter should be disclosed publicly. Holders below the threshold or outside the top 150 receive nothing from a given drop. This is by design — ATA rent makes unlimited recipients uneconomical.

DRY_RUN safety

The engine defaults to DRY_RUN=true. No transaction is ever signed or sent unless DRY_RUN is explicitly set to 0 or false. The config validator enforces that ENGINE_WALLET_SECRET is present before allowing DRY_RUN=0.