Meme Sniper

Solana meme sniper: scans, rug-checks, and suggests buys and sells, plus a gated launch rail with GitHub repo attach. Paper and suggest mode are the defaults (a missing env var does not sign). Armed stops, the owner-position timeout, and the launch rail ship off until you opt in. Python, MIT.

Your agent's trench crew. Meme Sniper scans every new Solana memecoin and rug-checks it. Trade ideas are suggestions until you approve them. It can also launch your own token through a gated launch rail that ships off. You set the wallet, sizes and rules once, and get pinged about what happens.

No hype, no ticker. Just the code.

Always on: loop, cadence and active hours

Meme Sniper is a loop meant to run continuously: the bot runs 24/7 on its cadence and your agent runs the lanes in automations/ on theirs. It is not a one-shot script.

• Keep it running: use an always-on hosted agent (best), or auto-start on boot on your own PC: Windows Task Scheduler "At log on" running python bots/sniper.py --start, macOS a launchd agent, Linux a systemd --user service or @reboot cron. Have the agent's lane jobs saved as recurring automations so they survive restarts.
• Active hours (tunable, bots/.env): ACTIVE_HOURS (default 00:00-23:59 = always on; e.g. 09:00-23:00, overnight 22:00-02:00, several windows 09:00-12:00,18:00-23:00), ACTIVE_TZ (default America/New_York), ACTIVE_DAYS (blank = every day; e.g. mon-fri). Outside the window the loop idles on new buys and new inbox cards (declined with reason outside_active_hours), never cuts off an order mid-send, keeps monitoring running, and resumes on its own when the window opens. A sell still needs your approval unless you set ARMED_STOPS=1. The stuck-bag watchdog only retries a sell that already went out. TRADING_HOURS / TRADING_TZ still work and apply on top (both windows must allow a buy).
• Cadence (tunable): lane cadences LANE_CADENCE_SNIPER_LANE_MIN (10), LANE_CADENCE_MISC_LANE_MIN (15), LANE_CADENCE_WARDEN_LANE_MIN (20), LANE_MORNING_BRIEF_AT (08:00), LANE_NIGHTLY_EVAL_AT (23:30). Bot-side cadences keep their existing settings (AGENT_INBOX_CADENCE_S, SNIPER_LAUNCH_POLL_S, WALLET_POLL_INTERVAL_S, SNIPER_WATCH_INTERVAL_S).
• Check it: python bots/active_hours.py prints whether new entries are allowed right now and each lane's cadence (no secrets).
• The setup wizard asks active hours right after the agent-autonomy question (AGENT_MODE).

Works with

Sniper can be run by Grok Bot, Muse, or an agent from any of the larger SI companies: any SI agent that can read and write files and run Python works. No official partnership or endorsement is implied.

Contents

• Always on: loop, cadence and active hours
• Works with
• Glossary
• Paper quick start (dry run)
• What Sniper is
• Read this first: safety defaults
• Safety caps and your settings
• Fixes (policy)
• GitHub basics (new to GitHub? start here)
• What's in this folder
• Quick start
• Install as plugin
• Windows, Mac and Linux
• GitHub sign-in setup
• Messaging / notifications setup
• How the inbox works
• Contributing
• Versions and releases
• Updating
• License

What Sniper is

Four pieces that work together:

1. The sniper (bots/meme_sniper.py). Scores every new Solana launch, runs rug checks, buys, and manages each position with stop loss, take profit and trailing stops. Writes what it sees as small JSON "packets" to an inbox for your agent.
2. The launch rail (bots/sub-bots/launch_rail.py). Launches a token for you, with a dev-buy cap (default 0.5 SOL) and a repo gate: the launch must point at a real public GitHub repo. Off by default (see below). Full details: docs/LAUNCH_RAIL.md.
3. GitHub sign-in and repo attach (bots/sniper_github.py). Sign in once with GitHub's device code, list your repos, and attach one to a launch.
4. Contribution review and uploader (also bots/sniper_github.py). Scans pull requests and suggestion files from other people, queues them for you to review, and packages and publishes your own uploads and releases. Nothing auto-merges.

Around those: an SI "brain" (Grok, OpenAI, Claude, any OpenAI-compatible endpoint, or local Ollama), alerts to your phone, a console dashboard, nightly self-review, and skill files in skills/ that teach your agent how to trade.

Who it's for: people who run an SI agent that can read files, run Python and keep a loop going, and who understand Solana memecoins and their risks.

Glossary

• SI agent: your AI agent (hosted or local) that reads packets, decides and writes signals. Sniper executes and guards; the agent decides.
• Packet / card: a JSON file the bots write to inbox/ (or json_relay/) for the agent: candidates, rug-check verdicts, acks, alerts.
• Signal: what the agent writes back to json_relay/agent_signals.json (buy, sell, set_protection_batch).
• Ack / confirmation: the bot's answer to every signal (signal_ack_*, trade_confirmation_* or signal_failure_* with a reason), echoing your request_id.
• Rug check (ca-intel): the vet of a contract address before any buy: authorities, holders, liquidity, creator history.
• Flip / hold: position modes. Flip trades in and out on stops and targets; hold keeps a long-term bag.
• Trail: a trailing stop that arms after a gain and exits after a set giveback.
• Scale-in: a small first buy, then the rest only if liquidity and price hold.
• Launch rail: the gated path that launches your own token with a GitHub repo attached. Off by default.
• Paper mode: SNIPER_PAPER_MODE=1, fills simulated at real quotes, nothing signed or sent.
• Inbox lanes: the recurring agent loops in automations/ that drain inbox/ into inbox_results/.

Paper quick start (dry run)

Paper mode is the default for new setups and needs no wallet private key: set an RPC, a brain and a HOT_WALLET_ADDRESS (any address, e.g. a fresh burner's). Nothing is signed or sent, and fills come from a simulated balance (SNIPER_PAPER_START_SOL, default 1.0). The private key is asked for only when the owner opts into live.

git clone https://github.com/BadmonLano/meme-sniper.git
cd meme-sniper
python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp bots/.env.example bots/.env                       # Windows: copy

In bots/.env keep AGENT_MODE=suggest and SNIPER_PAPER_MODE=1 (both shipped defaults), set the burner's HOT_WALLET_ADDRESS, an RPC_URL (Solana's free public https://api.mainnet-beta.solana.com works for a test) and a brain (GROK_API_KEY or local Ollama). Then python bots/sniper.py --smoke and python bots/sniper.py. Paper state lives in bot_logs/paper/. Going live later needs an explicit LIVE confirmation in the wizard.

Read this first: safety defaults

Honest notes:

• Agent autonomy is the first setup question. AGENT_MODE=suggest (default): the agent proposes trades and waits for your /approve. AGENT_MODE=auto lets it buy and sell on its own inside the caps; pick it only if you accept that.
• Use a burner hot wallet holding only what you can afford to lose. Never your main wallet.
• What wallet access means: the private key in bots/.env lets the bot sign any transaction from that wallet, not just trades: it could move or spend everything in it. So use a burner, keep the balance small, and sweep profits out (LEDGER_ADDRESS).
• Agent buys need a working RPC. Without a reachable RPC_URL (or HELIUS_API_KEY) buy signals are refused, not queued.
• Most memecoins go to zero and many are scams. The gates here reduce risk; they don't remove it. Bugs, RPC outages and bad model output can lose money.
• With the shipped defaults the agent suggests and you approve each buy and sell. Live signing, armed stops, the owner-position timeout, and the launch rail stay off until you opt in. Alerts are notify-only.
• MIT license, no warranty. You're responsible for every transaction it sends.

Safety caps and your settings

These are on by default. Every one is a line in bots/.env; leave it blank to keep the default, set 0 to switch a number off.

First run: the setup wizard and your agent ask you. The wizard asks most of these (see What the setup wizard asks); before it trades, confirm and write the answers into bots/.env: paper or live (default paper; a missing value is also paper), launch rail on or off (default off), armed stops (default off), owner-position auto-timeout (default off), buy size, daily loss stop, daily buy cap, stop loss / trailing stop, same-token cooldown, loss-streak pause, max open positions, and trading hours plus time zone. Press Enter on any question to keep the default. The agent does not turn live mode, the launch rail, armed stops, or the timeout on by itself.

Fixes (policy)

Plain English rules for any agent running this drop:

• The agent proposes patches. You apply them. When it spots a bug it writes an owner card in owner_inbox/ with the evidence, a diff, and a test plan. It does not edit bots/ (the trading engine) itself.
• Fixes for everyone go back as suggestions, not pushes. If the fix would help other users, send it upstream as a suggestion through the review queue (bots/sniper_github.py). Nothing is auto-merged.
• Your copy never auto-pulls. Upstream changes only reach your copy when you choose to update.
• Safety caps only loosen with your OK. The daily loss stop, daily buy cap, fail-closed rug checks, mint/freeze authority gate and max 5-minute pump gate can be tightened only after you say yes, and loosened or switched off only after you say yes. The agent does not change them on its own.

GitHub basics (new to GitHub? start here)

• Repo (repository): a project folder that lives on GitHub, with its full history. This page is one.
• Download ZIP: green Code button → Download ZIP. Gets you a copy with no account and no Git needed.
• Clone: same as downloading, but with Git (git clone <url>), so you can pull updates later with git pull.
• Star: a bookmark and a thumbs-up. Find your stars under your profile → Stars.
• Watch: the Watch button picks what you get notified about. Custom → Releases pings you only when a new version ships. Notifications show in the bell icon (top right) and by email if you allow it in notification settings.
• Fork: your own copy of the repo under your account. You can change it freely. It does not update itself when the original changes (see Versions and releases).
• Pull request (PR): "here's a change I made in my fork, please consider adding it." The owner reviews and decides.
• Issue: a bug report or question. Issues tab → New issue.
• Release: a named, tested version (like v1.0.1) with notes and a downloadable zip. Right side of the repo page → Releases.

What's in this folder

Quick start

1. Install Python 3.12+ from python.org. On Windows tick Add python.exe to PATH.
2. Get the code: green Code button → Download ZIP and unzip it, or git clone https://github.com/BadmonLano/meme-sniper.git then cd meme-sniper.
3. Open a terminal in that folder and install:

   pip install -r requirements.txt
   python -m playwright install chromium
   

   Mac/Linux: make a virtual environment first, then install inside it:

   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   python -m playwright install chromium
   

4. Make your settings file: copy bots/.env.example to bots/.env.
   • Windows: copy bots\.env.example bots\.env
   • Mac/Linux: cp bots/.env.example bots/.env
5. Fill in bots/.env in a text editor: burner wallet (HOT_WALLET_PRIVATE_KEY, HOT_WALLET_ADDRESS), RPC (RPC_URL / HELIUS_API_KEY), one brain (LLM_MAIN plus that provider's key), and SNIPER_PAPER_MODE=1 for your first run.
6. Run it: python bots/sniper.py (Mac/Linux: python3 bots/sniper.py). Pick 2 Setup wizard first, then 1 Start Sniper. --help lists the options.
7. Point your agent at SETUP.md so it finishes setup (rules, skills, automations, alerts).
8. Set up your inbox checks. Sniper only writes files; nothing gets decided until your agent checks them. Ask your agent to create one recurring task per prompt below, pasting the prompt file's text as the task (Grok Bot: a routine; Muse or other SI agents: a scheduled task, cron job or heartbeat with the file's text as the prompt). Replace {AGENT_NAME} / {USER} first, then run each once by hand and check bot_logs/inbox_cron_audit.log.

Offset the start minutes so no two checks start in the same minute. Details: automations/README.md and SETUP.md section 11.

Quick checks: python bots/sniper.py --smoke, python bots/sniper.py --ui-smoke (runs on a temp copy) and python bots/sub-bots/launch_rail.py --help.

Menus

Launcher (python bots/sniper.py): 1 Start Sniper (+ console), 2 Setup wizard, 3 Sign in to X, 4 Live dashboard, 5 Launch a token, 6 Console only, 7 Exit.

Console (opens with 1 or 6): 1 Live dashboard, 2 Logs, 3 Settings, 4 Skills, 5 Launch a token, 6 Sign in to X, 7 Quit UI (engine keeps trading), 8 Stop Sniper. Skills are under 6 Console → 4 Skills (all skill folders, including gork-lore). The token-lore template lives in templates/token-lore/, outside skills/, so plugin loaders don't pick it up as a skill.

What the setup wizard asks

Wallet (key, address, optional cold wallet), RPC (URL, Helius key, Helius plan), the brain (main + fallback and their keys/models), alert channels, owner commands, Pinata, X token, trading values (buy size, default SL/TP, dev-buy cap, own-launch mode and treasury %), Safety caps (daily loss stop 0.5 SOL, daily buy cap 10, same-token cooldown 72h, loss-streak pause 3, max open positions 3, trading hours blank = always, timezone America/New_York), and modes (launch rail on/off, default off, launch live on-chain default no, paper, learning). Enter takes the default shown. Answers go to bots/.env, each comment on its own line. SNIPER_WIZARD_SAFETY=0 hides the Safety caps questions.

Install as plugin

Meme Sniper ships as a plugin: 11 agent skills (meme-hunter, ca-intel, forensics, gork-lore and the sub-skills) plus this repo's bots. The manifest is in .cursor-plugin/plugin.json (Cursor) and .grok-plugin/plugin.json (Grok Bot); both list the same skills.

• Cursor: once listed, open Customize in the sidebar, find meme-sniper, then Install (project or user scope). To try it before then, clone this repo into ~/.cursor/plugins/local/meme-sniper, run Developer: Reload Window, and check under Customize that the skills show up.
• Grok Bot or any other SI agent: clone the repo and point your agent at SETUP.md. It loads the skills from skills/ and sets up the inbox checks in automations/.

The skills tell your agent how to run the bots. The bots themselves still run on your machine: follow Quick start for the install, then test them as shown below.

Test it safely (paper first, then one small live buy)

1. Env setup: copy bots/.env.example to bots/.env. Never commit bots/.env (it's git-ignored) and never paste its keys into chat.
2. RPC and a test wallet: set RPC_URL (or HELIUS_API_KEY). Make a new burner wallet just for testing, fund it with a small amount of SOL, and put it in HOT_WALLET_PRIVATE_KEY / HOT_WALLET_ADDRESS. Never use your main wallet. Start with SNIPER_PAPER_MODE=1, keep the safety caps at their defaults, and set a tiny OWNER_MAX_BUY_SOL.
3. Smoke check: python bots/sniper.py --smoke, then python bots/sniper.py → 2 Setup wizard → 1 Start Sniper.
4. Rug-check a token: ask your agent to vet a contract address (ca-intel skill), or write it to json_relay/ca_research_request.json yourself:

   {"requests": [{"request_id": "test_vet_1", "ca": "<MINT_ADDRESS>", "intent": "research"}]}
   

   The verdict lands in json_relay/ca_research_response.json and as a ca_intel packet in inbox/.
5. Small test buy: in paper mode, have your agent send a buy, or add one to json_relay/agent_signals.json:

   {"signals": [{"signal_id": "test_buy_1", "action": "buy", "mint": "<MINT_ADDRESS>", "amount_sol": 0.01,
     "params": {"stop_loss_pct": 30, "tp_targets_pct": [50]}, "mode": "flip", "reasoning": "plugin test"}]}
   

   Once paper looks right, set SNIPER_PAPER_MODE=0 and repeat with the smallest size you're OK losing.
6. Confirm stop/target armed and confirm/fail: every signal gets an answer that echoes your id as request_id. Look for a signal_ack_* / trade_confirmation_* packet in inbox/ (or a signal_failure_* with the reason), plus the row in bot_logs/signals_response_history.jsonl. Then open the console (1 Live dashboard) and check that the position shows its stop loss and take profit armed. If your agent sends set_protection_batch, that gets its own confirm or fail too.
7. Clean up: sell the test bag ("action": "sell") or let the stop or target close it. Then move the handled packets to inbox_results/done/.

Windows, Mac and Linux

The same Python files run on all three. Built and tested on Windows 10/11; macOS and Linux should work but are less tested.

Windows-only bits in the code, all guarded so they're skipped elsewhere:

• bots/sniper.py: sets the console to UTF-8 with ctypes.windll (Windows only).
• bots/sniper.py, bots/sniper_ui.py, bots/cancel_input.py: single-key input via msvcrt; on Mac/Linux the menus fall back to typed input.
• bots/sub-bots/agent_scraper.py: cleans up its own stray Chrome via PowerShell on Windows only; on Mac/Linux close a stuck scraper browser yourself.
• bots/sniper_ui.py: CREATE_NO_WINDOW subprocess flag (ignored off Windows).

No winreg, scheduled tasks or hard-coded drive paths. Keep the computer awake: trading pauses when it sleeps (Mac: caffeinate -i python3 bots/sniper.py).

GitHub sign-in setup

Optional. Needed only to list your repos, attach one to a launch, review contributions, or publish uploads.

1. Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
2. Name: anything (e.g. Sniper). Homepage URL and Callback URL: your GitHub profile URL (the callback isn't used).
3. Tick Enable Device Flow. Register.
4. If shown, untick "Expire user access tokens". Sniper doesn't refresh tokens yet, so expiring tokens log you out every 8 hours.
5. Copy the Client ID (not a secret) into bots/.env:

   GITHUB_OAUTH_CLIENT_ID=your_client_id
   

   You do not need a client secret.
6. Sign in:

   python bots/sniper_github.py login
   

   Open the link, type the code, approve. Then check with status and my-repos.

The token is stored in your OS password store (Credential Manager / Keychain / Secret Service). If keyring is unavailable it falls back to a user-only file in bot_logs/. python bots/sniper_github.py logout removes it. Default scope is read-only public access.

Other commands: repos, resolve, scan-prs, review, queue, upload, watch-drops, publish-upload, publish-release. Run any with --help.

Messaging / notifications setup

All optional. Pick channels with a comma list in bots/.env, e.g. ALERT_CHANNELS=telegram,ntfy. Leave it blank for none. Every setting has a comment in .env.example, and the setup wizard (python bots/sniper.py → wizard) can do this for you and send a test.

Telegram

1. In Telegram, message @BotFather → /newbot → copy the token.
2. Send your new bot any message, then open https://api.telegram.org/bot<TOKEN>/getUpdates and copy chat.id.
3. Set TELEGRAM_TOKEN= and TELEGRAM_CHAT_ID=, and add telegram to ALERT_CHANNELS.

Discord

1. Server Settings → Integrations → Webhooks → New Webhook → Copy Webhook URL.
2. Set DISCORD_WEBHOOK_URL= and add discord. Treat the URL like a password.

Email (SMTP)

1. Set SMTP_HOST, SMTP_PORT (587 = STARTTLS, 465 = SSL), SMTP_USER, SMTP_PASS, SMTP_FROM, ALERT_EMAIL_TO. Gmail: smtp.gmail.com with an app password.
2. Add email. ALERT_EMAIL_MIN_INTERVAL_S stops it flooding your inbox.

ntfy (free phone push, iPhone and Android)

1. Install the ntfy app, subscribe to a long random topic name.
2. Set NTFY_TOPIC= (and NTFY_URL / NTFY_TOKEN if self-hosted or protected). Add ntfy.

Owner commands (talk back to it, off by default)
Ask for /roast, /recap or /autopsy [ticker|last] by Telegram through a separate command bot (OWNER_COMMANDS, OWNER_COMMANDS_TG_TOKEN, OWNER_COMMANDS_TG_CHAT_ID) or by dropping a text file in owner_commands/. Replies land in your alert channels and inbox_results/owner_replies/. A roast goes to whoever made the trades: your own trades roast you, the agent's trades get its self-roast. See SETUP.md section 6.5.

iMessage on Mac (optional, community recipe)
Sniper has no built-in iMessage channel yet (imessage in ALERT_CHANNELS is ignored and logged as planned). If you're on a Mac signed into Messages, your agent can forward alerts itself with:

osascript -e 'tell application "Messages" to send "Sniper: test alert" to buddy "+15555550123"'

Run it once by hand first (macOS asks for permission). This is outside Sniper's code and unsupported; ntfy is the easier phone option.

How the inbox works

Sniper and your agent talk through plain files, so any agent that can read and write files works:

• Bots → agent: packets land in inbox/ and json_relay/ (new cards, rejected signals, positions, launch requests). Cards meant for you (alerts, recaps) go to owner_inbox/.
• Agent → bots: the agent writes decisions and launch requests back into json_relay/ (e.g. json_relay/launch_requests/*.json).
• Every action gets an answer: each thing your agent sends (buy/sell/SL-TP signals, launches, wallet and archetype commands, repo suggestions and decisions, publish, owner commands, code_tuner and meeting notes, filter edits) gets a confirm_… or failed_… memo in inbox/ with a one-line summary, the reason on failure and the original request id. AGENT_MEMOS=0 turns them off.
• Done work: results go to inbox_results/ and move to inbox_results/done/.
• You → agent: text files in owner_commands/.
• Each request is processed once (tracked in bot_logs/), so nothing fires twice.

The automations/ files are ready-made loops telling your agent how often to read these. Details in SETUP.md sections 6 and 11.

Contributing

Ideas and fixes are welcome. Everything is reviewed by the repo owner. Nothing is auto-merged.

• Pull request: Fork → change it in your fork → Contribute → Open pull request. Keep it small, say what and why, run the tests (python bots/sniper.py --smoke and the test_*.py files).
• Suggestion file: no Git needed. Open an issue, or attach a short markdown file describing the change.
• Security holes: don't open a public issue. See SECURITY.md.
• Never include keys, wallets, .env files or logs in a PR.

Full guide: CONTRIBUTING.md.

Versions and releases

• Feature details for each version (vault exception, celebrity-post rule, scale-in/trail/watchdog, celeb_post cards and later) are in CHANGELOG.md.
• Versions look like v1.0.15 (the trading engine inside keeps its own number, v14.3). Each one is a Release with notes on what changed (history in TIMELINE.md).
• Forks and downloads don't auto-update. You update when you want:
  • ZIP: download the new release, copy your bots/.env, rules/rules.md and learnings/ across.
  • Git clone: git pull.
  • Fork: on your fork's page click Sync fork.
• To hear about new versions: Watch → Custom → Releases.
• Read the release notes before updating; new settings appear in .env.example.

Updating

• Git: git pull in the folder.
• ZIP: download the new release zip and unzip it over the old folder (or next to it and copy your files across).
• Your bots/.env and bot_logs/ are kept either way (git ignores them, and the zip doesn't contain them). The live filter file is ignored too, so git pull doesn't conflict with what the bot tuned.
• Check .env.example and the release notes for new settings.

License

MIT © 2026 Bentayga Empire LLC. Use it, change it, share it; keep the license notice. No warranty.

More from Bentayga: JOS (@JOSYSTEMS) · theflowcycle.com