Agent Sniper

@three-ws/agent-sniper

A lightweight, embeddable pump.fun sniper engine for 3D AI agents. One trade loop — feed a stream of new launches, score each against a per-agent strategy, run the pre-trade guards, buy, then sweep open positions on an interval and exit on stop-loss / take-profit / trailing-stop / timeout / sentiment-flip. It is multi-agent and multi-user by construction (one wallet per agentId), and every external dependency — wallet custody, persistence, RPC/venue, launch feed — is a pluggable adapter, so the same engine runs locally with in-memory state or hosted across thousands of tenants. The package ships with four faces over that one engine: a library, a CLI, an MCP server, and an x402 paid HTTP API.

---

Why — the adapter architecture

The engine is pure orchestration. It owns the decision pipeline; it owns nothing about *where* the money, the data, or the chain live. Five adapter interfaces (src/types.js) are the seams, and a default implementation ships for each:

                            ┌──────────────────────────── engine ────────────────────────────┐

Feed ──{mint|intel|claim}─▶ score ──▶ guards ──▶ executeBuy ──▶ claimPosition │ (PumpPortal) (scorer) (concurrency, (quote + (atomic slot) │ budget, SOL build + sign │ headroom, + broadcast) │ price impact) │ position sweep (every pollMs) │ ──▶ decideExit ──▶ executeSell │ └────────────────────────────────────────────────────────────────────┘ adapters: Feed Solana Wallet Executor Store (launch (quote/build (resolve a (sign + (strategies, stream) pump.fun ix) Keypair per broadcast) positions, agentId) spend ledger)

Swap any one without touching the loop: a custodial KMS wallet instead of local keys, a Postgres store instead of memory, a different launch feed, a different venue. Implement the shape, pass it to createSniper(), done.

Optional Hooks (firewall assessSafety, oracleGate, onScreen, onBuy, onSell, recordDecision) are best-effort cross-cutting callbacks — a throw is swallowed and never aborts a trade, except onTip, which is a deliberate veto.

---

Install

npm i @three-ws/agent-sniper

Optional peers, installed only if you use the face that needs them:

npm i better-sqlite3   # durable Store (src/adapters/store/sqlite.js)

npm i express # the x402 HTTP API face

Requires Node >= 22.

---

Quickstart (library)

The presets.local wiring is the zero-to-running path: in-memory store + self-custody wallet + pump.fun client + web3 executor + PumpPortal feed. Run it in simulate mode on devnet first — the engine scores, guards, and logs every decision but never broadcasts.

A strategy must carry a stop_loss_pct — the engine refuses to arm a strategy without one. SOL amounts on a strategy are expressed in lamports (1 SOL = 1,000,000,000 lamports), as a string, number, or bigint.

import { createSniper, createMemoryStore, presets } from '@three-ws/agent-sniper';

// 1 SOL = 1e9 lamports. const SOL = 1_000_000_000n;

const strategy = { id: 'strat_scout_1', agent_id: 'scout', // one wallet per agentId enabled: true, trigger: 'new_mint', // fire on the create event network: 'devnet', per_trade_lamports: (SOL / 100n).toString(), // 0.01 SOL per snipe daily_budget_lamports: (SOL / 2n).toString(), // 0.5 SOL/day ceiling max_concurrent_positions: 3, slippage_bps: 500, // 5% max_price_impact_pct: 10, // entry circuit breaker stop_loss_pct: 30, // REQUIRED — exit when down 30% take_profit_pct: 80, // exit when up 80% trailing_stop_pct: 20, // exit when down 20% from peak (after profit) max_hold_seconds: 1800, // hard time-stop require_socials: true, // skip launches with no twitter/telegram/website max_creator_launches: 10, // skip serial launchers };

const sniper = await presets.local({ network: 'devnet', mode: 'simulate', // no funds move strategies: [strategy], // secrets: { scout: ' ' }, // for live mode });

await sniper.start();

console.log(sniper.stats()); // { events, candidates, buys, sells, errors, strategies, queued, lastEventAt } console.log(sniper.strategies()); // the live armed-strategy cache

// Fire a manual buy by hand (drives the same path as MCP snipe_now): sniper.submitCandidate( { mint: 'THREEsynthetic1111111111111111111111111111111', entry_trigger: 'manual' }, { force: true }, );

// later… await sniper.stop();

createSniper(deps) is the lower-level constructor when you want to bring your own adapters — pass { config, store, wallet, solana, executor, feed, hooks }. presets.local is just one wiring of it.

---

CLI usage

The package installs an agent-sniper binary. Default mode is simulate — it will not move funds until you pass --mode live (or set SNIPER_MODE=live), which trades real funds.

# Run the engine. Mode defaults to simulate; live trades real funds.

npx agent-sniper run --network devnet --strategy ./strategy.json

Serve the engine over MCP (stdio) for Claude / Cursor / any MCP client.

agent-sniper mcp

Serve the x402-gated HTTP API + web console (open http://localhost:8787).

agent-sniper serve

Help.

agent-sniper help

Safety. run/serve/mcp all start in simulate mode unless you opt into

live explicitly. In live mode every armed strategy can spend up to its

daily_budget_lamports per UTC day. Read Safety & guardrails below before

you flip the switch.

--strategy ./strategy.json loads a strategy (or array of strategies) as JSON. A minimal file mirrors the object in the Quickstart — note stop_loss_pct is required.

---

MCP server

agent-sniper mcp exposes the engine as an MCP stdio server. Every tool maps 1:1 onto a public engine/store method — no internals are reached around. The server is unauthenticated and meant to run locally against your own wallet/RPC.

Wire it into an MCP client (Claude Desktop, Cursor, etc.):

{

"mcpServers": { "agent-sniper": { "command": "npx", "args": ["-y", "@three-ws/agent-sniper", "mcp"], "env": { "SNIPER_NETWORK": "devnet", "SNIPER_MODE": "simulate" } } } }

createSniperMcpServer(deps) builds the fully-registered server without connecting a transport, so you can construct it in a test and drive it over an in-memory transport.

---

x402 paid HTTP API

agent-sniper serve (or import { serve } from '@three-ws/agent-sniper/api') mounts the engine over HTTP. Reads are free; the four mutating endpoints are gated behind x402 USDC micropayments via @three-ws/x402-server — the middleware verifies the X-PAYMENT header against the facilitator, runs the work, settles on-chain, and emits the receipt.

Prices are the defaults (USDC atomic units, 6 decimals); override via deps.prices = { arm, snipe, disarm, close }.

Gating turns on when a merchant wallet is configured — deps.payTo.solana or the X402_PAY_TO_SOLANA env (a Base lane is available via X402_PAY_TO_BASE). When no payTo is set, the mutating routes still mount but answer 503, so the server boots cleanly for local/dev without payment config.

The Solana lane also needs a facilitator sponsor fee-payer — set X402_FEE_PAYER_SOLANA (or deps.feePayer). Without it the Solana lane self-disables (falling back to the Base lane, or the 503 guard if that's the only lane) rather than failing requests, and logs a one-time warning at boot.

import { serve } from '@three-ws/agent-sniper/api';

await serve( { payTo: { solana: process.env.X402_PAY_TO_SOLANA } }, { port: 8787 }, );

---

Web console

serve also ships a built-in operator dashboard — a single, dependency-free HTML file served from the same origin as the API, at / and /console. Open http://localhost:8787 and you get a live control room:

• Live stats — buys, sells, candidates, armed strategies, in-flight queue and signal count, animated as they change, with time-since-last-signal.
• Positions table — every position with entry, current value, and colored P&L (unrealized total in the header), plus a one-click Close that schedules an exit through the normal sell path.
• Armed strategies — each policy with its stop-loss / take-profit / trailing tags, and a Disarm button.
• Arm a strategy and Manual snipe forms with inline validation.
• Live activity feed — the same engine screen events the CLI prints, streamed in with relative timestamps.
• Designed loading / empty / error states, toasts, keyboard shortcuts (s snipe, n new strategy, r refresh, , settings, ? help), a disconnected banner, and full mobile responsiveness.

Reads are free. The mutating controls (arm, snipe, disarm, close) are x402-paid for external callers — so to drive them from your own console without paying yourself, set an operator token:

export SNIPER_ADMIN_TOKEN="$(opens