@three-ws/agent-sniper

<!-- three.ws:badges -->

<!-- /three.ws:badges -->

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.

| Adapter | Responsibility | |------------|----------------| | Feed | Push { kind: 'mint'\|'intel'\|'claim', data: Candidate } events into the engine. | | Solana | Quote + build pump.fun buy/sell instructions; expose a web3 Connection. | | Wallet | Resolve a signing Keypair for an agentId (or null if unprovisioned). | | Executor | The one place that signs and broadcasts; returns landing telemetry. | | Store | Persist strategies, positions, and the daily spend ledger; atomic claimPosition. |

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 >= 20.

---

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: '<base58 | [byte,array] | 0x-hex secret>' },  // 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.

| Tool | Kind | Purpose | |------|------|---------| | arm_strategy | write | Register/update a strategy. SOL → lamports for you; stop_loss_pct mandatory. | | disarm_strategy | write | Disable a strategy (enabled=false); open positions still exit on their rules. | | list_strategies | read | List the armed strategy set the engine is evaluating. | | snipe_now | write | Force a manual buy of a mint across all armed agents (bypasses the scorer). | | list_positions | read | List positions, filter by agentId and/or status. | | close_position | write | Schedule an exit — flips the position's kill switch; the next sweep sells it. | | sniper_status | read | Engine health: event/candidate/buy/sell counts, armed count, queue depth, network/mode. |

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.

| Method | Endpoint | Price | Notes | |--------|----------|-------|-------| | GET | /health | free | Liveness + network/mode/stats. | | GET | /status | free | Full stats + immutable runtime config. | | GET | /strategies | free | The armed strategy set. | | GET | /positions?agentId=&status= | free | Positions from the store. | | GET | /activity | free | The recent engine screen events (what the console feed renders). | | GET | / and /console | free | The built-in operator console (see below). | | POST | /strategies | $0.01 USDC | Arm a strategy (SOL → lamports; stop-loss required). | | POST | /snipe | $0.05 USDC | Force a snipe on { mint, symbol?, agentId? }. | | POST | /strategies/:id/disarm | $0.005 USDC | Disable a strategy. | | POST | /positions/:id/close | $0.005 USDC | Schedule an exit; the next sweep sells it. |

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 to