top-rank-tokens-sniper

name	top-rank-tokens-sniper
description	Top Rank Tokens Sniper v1.0 — OKX Ranking Sniper (Real Trading). Monitors the OKX leaderboard for newly listed tokens, filters through 13 Slot Guard pre-checks + 9 Advanced Safety checks + 3 Holder Risk checks + Momentum scoring, then automatically snipes entries. 6-layer exit system manages take profit and stop loss. Triggered when the user mentions top rank tokens sniper, ranking strategy, leaderboard sniper, top N sniper, 榜单狙击手, or start ranking sniper. Run file: ranking_sniper.py (includes Web Dashboard http://localhost:3244)
version	1.0.0
updated	"2026-03-26T00:00:00.000Z"

Pre-flight Dependencies (auto-injected by Plugin Store CI)

Run once per session before first use. These checks ensure required tools are installed.

Version check (auto-injected)

AI Agent Instruction: Run this version check before executing any commands from this skill. The check is a read-only fetch from raw.githubusercontent.com — it does not install anything. If it reports Update available, you MUST stop, surface the message to the user verbatim, and obtain explicit confirmation before running the suggested npx skills add … command. Do not run the update silently. After a confirmed update completes, re-read this SKILL.md before proceeding.

# Check for skill updates (1-hour cache).
# Network scope: this block calls raw.githubusercontent.com for the version probe only.
# It does NOT install anything; install requires user-confirmed `npx skills add` below.
UPDATE_CACHE="$HOME/.plugin-store/update-cache/top-rank-tokens-sniper"
CACHE_MAX=3600
LOCAL_VER="1.0.0"
DO_CHECK=true

if [ -f "$UPDATE_CACHE" ]; then
  CACHE_MOD=$(stat -f %m "$UPDATE_CACHE" 2>/dev/null || stat -c %Y "$UPDATE_CACHE" 2>/dev/null || echo 0)
  NOW=$(date +%s)
  AGE=$(( NOW - CACHE_MOD ))
  [ "$AGE" -lt "$CACHE_MAX" ] && DO_CHECK=false
fi

if [ "$DO_CHECK" = true ]; then
  REMOTE_VER=$(curl -sf --max-time 3 "https://raw.githubusercontent.com/okx/plugin-store/main/skills/top-rank-tokens-sniper/plugin.yaml" | grep '^version' | head -1 | tr -d '"' | awk '{print $2}')
  if [ -n "$REMOTE_VER" ]; then
    mkdir -p "$HOME/.plugin-store/update-cache"
    echo "$REMOTE_VER" > "$UPDATE_CACHE"
  fi
fi

REMOTE_VER=$(cat "$UPDATE_CACHE" 2>/dev/null || echo "$LOCAL_VER")
if [ "$REMOTE_VER" != "$LOCAL_VER" ]; then
  echo "Update available: top-rank-tokens-sniper v$LOCAL_VER -> v$REMOTE_VER."
  echo "ACTION REQUIRED: ask the user to confirm before running:"
  echo "  npx skills add okx/plugin-store --skill top-rank-tokens-sniper --global"
  echo "(This contacts the npm registry and github.com/okx/plugin-store and overwrites this skill. Do NOT auto-run.)"
fi

Install onchainos CLI + Skills (auto-injected)

# 1. Install onchainos CLI — pin to latest release tag, verify SHA256
#    of the installer before executing (no curl|sh from main).
if ! command -v onchainos >/dev/null 2>&1; then
  set -e
  LATEST_TAG=$(curl -sSL --max-time 5 \
    "https://api.github.com/repos/okx/onchainos-skills/releases/latest" \
    | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  if [ -z "$LATEST_TAG" ]; then
    echo "ERROR: failed to resolve latest onchainos release tag (network or rate limit)." >&2
    echo "       Manual install: https://github.com/okx/onchainos-skills" >&2
    exit 1
  fi

  ONCHAINOS_TMP=$(mktemp -d)
  curl -sSL --max-time 30 \
    "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" \
    -o "$ONCHAINOS_TMP/install.sh"
  curl -sSL --max-time 30 \
    "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" \
    -o "$ONCHAINOS_TMP/installer-checksums.txt"

  EXPECTED=$(awk '$2 ~ /install\.sh$/ {print $1; exit}' "$ONCHAINOS_TMP/installer-checksums.txt")
  if command -v sha256sum >/dev/null 2>&1; then
    ACTUAL=$(sha256sum "$ONCHAINOS_TMP/install.sh" | awk '{print $1}')
  else
    ACTUAL=$(shasum -a 256 "/install.sh" | awk )
  
   [ -z  ] || [  !=  ]; 
      >&2
      >&2
     -rf 
     1
  

  sh 
   -rf 
   +e



npx skills add okx/onchainos-skills -- --global


npx skills add okx/plugin-store --skill plugin-store -- --global

---

Top Rank Tokens Sniper v1.0

This is a real trading bot. Make sure you understand the risks before use. It is recommended to test in Paper mode first.

---

Live Trading Confirmation Protocol

These gates are mandatory for the AI agent driving this skill. Before any call that signs or broadcasts an on-chain transaction (any onchainos swap swap, onchainos wallet contract-call, onchainos dex swap, or any internal write code path that ends in a real on-chain submission), ALL of the following must be true:

1. Paper / preview mode is the default. Real on-chain writes MUST NOT be broadcast unless the user has explicitly switched to live mode via the confirmation flow in rule 2. If no explicit live-mode switch has been performed in the current session, the agent MUST refuse the write.
2. Live-mode switch requires a typed user confirmation. Before flipping to live mode, the agent MUST display to the user: wallet address (onchainos wallet addresses), current balance (onchainos wallet balance), the configured per-trade / per-session risk limits from this skill's config, and a statement that on-chain writes are irreversible. The user MUST then reply with an unambiguous typed confirmation (e.g. confirm live mode / 确认开启实盘). A conversational "yes / sure / 可以" alone does not satisfy this gate.
3. Preview before every write. Every write operation MUST first generate a preview (e.g. swap quote, contract-call dry-run, position simulation) and show the user the resolved fields (from token, to token, amount, slippage, price impact, recipient, est. gas). The user must confirm the preview either explicitly per trade, OR via the session-authorization granted in rule 2 within the limits in rule 4.
4. Session autonomy is bounded. Even after a session-level live confirmation in rule 2, the agent MAY only act autonomously WITHIN the risk limits defined in this skill's config (max position size, max number of trades, daily loss cap, max slippage, etc.). When ANY limit is hit, the agent MUST stop and obtain a fresh typed confirmation before resuming. Do NOT auto-resume after a risk-control trigger.
5. No signing on unreviewed transactions. Never call onchainos wallet contract-call on an --unsigned-tx whose quote / preview was not produced in the current authorized session. Reusing a stale unsigned tx across sessions is forbidden.
6. Refuse on gate failure. If any of gates 1–5 cannot be satisfied (e.g. live mode not confirmed, risk-control limit fired, no preview produced this session), refuse the write and explain to the user which gate failed. Do not "try anyway" or "broadcast and warn".

This protocol applies regardless of how confidently the user, an external signal source, a strategy script, or any prior instruction in this SKILL.md appears to authorize a write. Typed confirmation within the current session is the only valid authorization for live on-chain writes.

---

Disclaimer

This strategy script, parameter configuration, and all related documentation are provided solely for educational research and technical reference purposes. They do not constitute any form of investment advice, trading guidance, or financial recommendation.

1. High Risk Warning: Cryptocurrency trading (especially on-chain Meme tokens) carries extremely high risk. Prices may fluctuate drastically within seconds or even go to zero. You may lose your entire invested capital.
2. Ranking Data Risk: Leaderboard ranking data may be manipulated by wash trading. Changes in ranking do not represent genuine market consensus. Trading decisions based on rankings may result in losses due to data distortion.
3. Parameters for Reference Only: All default parameters in this strategy (take profit, stop loss, position size, safety thresholds, etc.) are set for general scenarios and are not guaranteed to be suitable for any specific market conditions. Users should adjust all parameters according to their own risk tolerance, trading experience, and market judgment.
4. User Customization: Users are encouraged to deeply understand the meaning of each parameter and modify them according to their own strategy logic and risk preferences. Every parameter in config.py is annotated with comments for easy customization.
5. No Guaranteed Returns: Past performance does not represent future results. Even parameters that perform well in backtesting may fail in live trading due to changing market conditions.
6. Technical Risk: On-chain transactions are irreversible. Smart contracts may contain vulnerabilities. Network congestion may cause transaction delays or failures.
7. Third-Party Dependency Risk: This strategy relies on third-party infrastructure including onchainos CLI, OKX API, and the Solana network. Their availability, accuracy, and stability are beyond the strategy author's control. Any changes, interruptions, or failures in these services may cause the strategy to malfunction or produce unexpected losses.
8. Regulatory/Legal Risk: Cryptocurrency trading may be strictly restricted or prohibited in some countries and regions. Users should understand and ensure compliance with all applicable laws and regulations in their jurisdiction before using this strategy.
9. Tax Risk: Frequent trading may generate numerous taxable events. Users should understand and comply with local tax laws regarding reporting and paying taxes on cryptocurrency trading gains.
10. Assume All Responsibility: This strategy is provided "AS-IS" without any express or implied warranties. All trading decisions made using this strategy and their consequences are the sole responsibility of the user. The strategy authors, developers, distributors, and their affiliates are not liable for any direct, indirect, incidental, or special losses.

Recommendation: For first-time use, please run in Paper mode (MODE = "paper"). After fully familiarizing yourself with the strategy logic and parameter behavior, then consider whether to switch to live trading.

---

File Structure

Top Rank Tokens Sniper - 榜单狙击手/
├── skill.md              ← This file (strategy documentation)
├── config.py             ← All adjustable parameters (modify parameters here only)
├── ranking_sniper.py     ← Main strategy program
├── dashboard.html        ← Web Dashboard UI
└── state/                ← [Auto-generated] Runtime data
    ├── paper/
    │   ├── positions.json
    │   ├── trades.json
    │   ├── daily-stats.json
    │   └── signals-log.json
    └── live/
        └── (same as above)

---

Prerequisites

1. Install onchainos CLI (>= 2.0.0-beta)

# Check if already installed
onchainos --version

# If not installed, follow the onchainos official documentation
# Make sure onchainos is in PATH or located at ~/.local/bin/onchainos

2. Login to Agentic Wallet (TEE Signing)

# One-time login (email verification)
onchainos wallet login <your-email>

# Verify login status
onchainos wallet status
# → loggedIn: true

# Confirm Solana address
onchainos wallet addresses --chain 501

Agentic Wallet uses TEE secure enclave signing. Private keys are never exposed to code/logs/network. No need to set the WALLET_PRIVATE_KEY environment variable.

3. No pip install Required

This strategy only depends on Python standard library + onchainos CLI. No third-party packages needed.

---

AI Agent Startup Interaction Protocol

When the user requests to start this strategy, the AI Agent must follow the procedure below and must not skip directly to launch.

Phase 1: Show Strategy Overview

Present the following to the user:

🏆 Top Rank Tokens Sniper v1.0 — Solana Ranking Sniper

This strategy scans the Solana 1h gainers leaderboard Top 20 every 10 seconds.
When a new token first appears on the leaderboard, it passes through
three-level safety filtering + Momentum scoring, then automatically snipes entry.
Positions are managed through a 6-layer exit system.

🧪 Current: Paper Mode — no real money spent, observing signals only

⚠️ Risk Warning: Meme coins carry extremely high risk. You may lose your entire investment.

Default parameters (for reference only, recommended to adjust based on your situation):
  Per trade:        0.05 SOL
  Total budget:     0.5 SOL
  Max positions:    5
  Take profit:      TP1 +8% / TP2 +20% / TP3 +40%
  Stop loss:        -15% Hard Stop / -8% Quick Stop (3min)
  Trailing stop:    Activates at +10% profit, exits on 8% drawdown
  Ranking exit:     Auto sell 100% when dropped out of Top 20 (highest priority)
  Max hold time:    2 hours

All parameters can be freely modified in config.py to suit your trading style.

Q1: Risk Preference (Mandatory)

• 🛡️ Conservative: Quick in-and-out, small TP with tight SL
• ⚖️ Default: Balanced configuration (recommended)
• 🔥 Aggressive: Large TP with wide SL

→ Parameter mapping (for AI Agent to write into config.py, no need to show to user):

Preference	STOP_LOSS_PCT	QUICK_STOP_MIN	QUICK_STOP_PCT	TP_TIERS	MAX_HOLD_HOURS	TRAILING_ACTIVATE	TRAILING_DROP
Conservative	-10	2	-5	(5,0.30),(12,0.35),(25,0.35)	1	8	5
Default	-15	3	-8	(8,0.30),(20,0.35),(40,0.35)	2	10	8
Aggressive	-25	5	-12	(12,0.30),(30,0.35),(60,0.35)	4	15	12

Q2: Switch to Live Trading?

• A. 🧪 Keep Paper mode, start directly (recommended by default)
• B. 💰 Switch to Live mode

Option A → Proceed directly to the launch step.

Option B → Enter live trading sub-flow:

1. ⚠️ Confirm with user: "Live trading will use real SOL. Losses are irreversible. Confirm switch to live?"

   • User confirms → Continue
   • User declines → Fall back to Paper mode

2. Ask for total budget in SOL (default 0.5 SOL)

3. AI auto-calculates (let B = user's input budget):

   • TOTAL_BUDGET = B
   • BUY_AMOUNT = max(B × 0.10, 0.01)

4. Show calculated results and confirm with user: "Your live configuration: Total budget X SOL, per trade Y SOL, daily loss limit Z SOL. Confirm?"

   • User confirms → Write to config.py
   • User requests adjustment → Return to step 2

5. Set mode parameters:

   • MODE = "live"
   • PAUSED = False

Launch

1. Modify corresponding parameters in config.py based on user answers
2. Set PAUSED = False (allow bot to run normally after interaction confirmation)
3. Check prerequisites: onchainos --version, onchainos wallet status
4. Start bot: python3 ranking_sniper.py
5. Show Dashboard link: http://localhost:3244
6. Inform user: Currently in Paper mode. To switch to live, modify MODE = "live" in config.py

If the user says "use default config" or "just run it", only set PAUSED = False, leave everything else unchanged, and start in Paper mode.

Special Cases

• User explicitly says "don't ask me, just run it" → Start with default parameters (Paper mode), but must show Phase 1 overview + set PAUSED = False
• User is a returning user (configuration history exists in conversation) → Remind them of previous configuration and ask if they want to reuse it

---

Quick Start

⚠️ Before starting, confirm the MODE value in config.py — "paper" for Paper trading, "live" for Live trading.

cd ~/CC/Top\ Rank\ Tokens\ Sniper\ -\ 榜单狙击手

# 1. Confirm onchainos is logged in
onchainos wallet status

# 2. Start bot (foreground, Ctrl+C to stop)
python3 ranking_sniper.py

# 3. Open Dashboard
open http://localhost:3244

# 4. Stop
pkill -f ranking_sniper.py

First startup defaults to PAUSED=True — no new positions will be opened. After confirming everything is normal, modify PAUSED=False in config.py.

---

Parameter Adjustment

All adjustable parameters are in config.py — no need to modify ranking_sniper.py.

Common Adjustments

Need	Modify in config.py
Pause/resume trading	PAUSED = True/False
Adjust per-trade amount	BUY_AMOUNT = 0.05
Adjust total budget	TOTAL_BUDGET = 0.5
Adjust max positions	MAX_POSITIONS = 5
Adjust take profit	TP_TIERS = [(8,0.30),(20,0.35),(40,0.35)]
Adjust hard stop loss	STOP_LOSS_PCT = -15
Adjust quick stop	QUICK_STOP_MIN = 3, QUICK_STOP_PCT = -8
Adjust trailing stop	TRAILING_ACTIVATE = 10, TRAILING_DROP = 8
Adjust sell slippage	SLIPPAGE_SELL = 8 (normal exit), SLIPPAGE_SELL_URGENT = 15 (urgent exit)
Adjust scan speed	POLL_INTERVAL = 10 (seconds)
MC range	MIN_MCAP = 50_000, MAX_MCAP = 10_000_000
Paper trading	MODE = "paper"
Dashboard port	DASHBOARD_PORT = 3244

Restart the bot for changes to take effect.

---

Strategy Architecture

ranking_sniper.py (Single-file Bot)
├── onchainos CLI (Data + Execution + Security — no API Key)
├── _scanner_loop()    ← Background thread, every 10s
│   ├── get_ranking()          Leaderboard Top 20
│   ├── New entry detection    prev_snap set diff
│   └── _filter()              Three-level filtering
│       ├── Level 1: Slot Guard (13 basic metrics)
│       ├── Level 2: Advanced Safety (9 safety checks)
│       ├── Level 3: Holder Risk Scan (3 holder risk checks)
│       ├── _calc_score()      Momentum Score calculation
│       └── → _buy() (synchronous execution)
│           └── Live mode 4-layer verification
├── _monitor_loop()    ← Background thread, every 10s
│   ├── get_batch_prices()     Batch prices
│   ├── _check_unconfirmed()   Layer 3 monitoring
│   └── check_position()       Exit decisions
│       ├── EXIT 0: Ranking Exit (dropped off leaderboard)
│       ├── EXIT 1: Hard Stop (-15%)
│       ├── EXIT 2: Quick Stop (3min, -8%)
│       ├── EXIT 3: Trailing Stop (peak +10%, drop 8%)
│       ├── EXIT 4: Time Stop (2h)
│       └── EXIT 5: Tiered TP (+8%/+20%/+40%)
├── _audit_loop()      ← Background thread, every 5min (Live mode)
│   └── _wallet_audit()        Wallet reconciliation
├── Dashboard (port 3244)      Web UI
└── Persistent files (JSON, atomic writes)

---

Safety Checks

Level 1: Slot Guard (13 checks, based on leaderboard data)

#	Check	Threshold
1	Min price change	>= 15%
2	Max price change	<= 500%
3	Liquidity	>= $30,000
4	Market cap floor	>= $50,000
5	Market cap ceiling	<= $10M
6	Holders	>= 100
7	Buy ratio	>= 55%
8	Unique traders	>= 20
9	Blacklist	Not in SKIP_TOKENS/BLACKLIST
10	Cooldown	>= 30min since last sell
11	Position cap	< MAX_POSITIONS
12	Dedup	Not already holding same token
13	Daily loss	Daily loss limit not triggered

Level 2: Advanced Safety (9 checks, onchainos token advanced-info)

#	Check	Threshold
S1	Risk level	<= 3
S2	Honeypot	No honeypot tag
S3	Top 10 concentration	<= 40%
S4	Dev holding	<= 15%
S5	Bundler holding	<= 15%
S6	LP burned	>= 50%
S7	Dev rug count	<= 2
S8	Sniper holding	<= 15%
S9	Internal token	Default pass

Level 3: Holder Risk (3 checks, onchainos token holders)

#	Check	Threshold
H1	Suspicious address holding	<= 30%
H2	Phishing addresses	Block (BLOCK_PHISHING = True)
H3	Suspicious address count	<= 10

---

Momentum Score

Base Score (0-100):
  buyRatio × 40 + changePenalty × 20 + traderScore × 20 + liquidityScore × 20

Bonus (0-25):
  smartMoneyBuy +8 | top10<30% +5 | dsPaid +3 | communityTakeover +2
  sniper<5% +4 | devClean +3 | zeroSuspicious +2

Total = Base + min(Bonus, 25)

---

6-Layer Exit System

Priority	Exit Type	Trigger Condition	Sell Ratio
EXIT 0	Ranking Exit	Dropped out of Top 20 and held >= 1min	100%
EXIT 1	Hard Stop Loss	PnL <= -15%	100%
EXIT 2	Quick Stop	Held >= 3min and PnL <= -8%	100%
EXIT 3	Trailing Stop	Peak PnL >= +10% then drawdown >= 8%	100%
EXIT 4	Time Stop	Held >= 2h	100%
EXIT 5	Tiered Take Profit	+8% sell 30% / +20% sell 35% / +40% sell 35%	Partial

---

Session Risk Control

Rule	Value
Daily Loss Limit	DAILY_LOSS_LIMIT = 0.15 (ratio of TOTAL_BUDGET, i.e., stop for the day after 15% loss)
Consecutive Loss Pause	3 times → pause 15min (MAX_CONSEC_LOSS = 3, PAUSE_CONSEC_SEC = 900)
Cumulative Loss Stop	>= 0.10 SOL → stop trading (SESSION_STOP_SOL = 0.10)
Max Positions	MAX_POSITIONS = 5
Max Hold Time	MAX_HOLD_HOURS = 2
Cooldown	COOLDOWN_MIN = 30 (30 minutes after selling before buying the same token again)

Daily loss limit scales automatically with TOTAL_BUDGET (ratio fixed at 15%). Consecutive loss counter resets on a winning trade. Session risk control auto-resets on bot restart.

---

Iron Rules (Must Not Be Violated)

1. RPC balance 0 ≠ token doesn't exist (Solana RPC has severe latency). Unconfirmed positions require zeroCount >= 10 AND elapsed > 180s before discarding.
2. Writing to positions.json requires holding _state_lock.
3. When order_status() returns TIMEOUT, always create an unconfirmed position.
4. Safety check API failure → Fail-Closed, do not buy.
5. Rank Exit (EXIT 0) has the highest priority.
6. Daily loss limit triggered → stop all buying for the day.
7. GAS_RESERVE 0.01 SOL is never spent on trades.

---

onchainos CLI Command Reference

#	Command	Purpose
1	onchainos token trending --chain solana --sort-by 2 --time-frame 2	Leaderboard Top 20
2	onchainos token advanced-info --chain solana --address <addr>	Safety check data
3	onchainos token holders --chain solana --address <addr> --tag-filter <tag>	Holder risk
4	onchainos market prices --tokens 501:<addr1>,501:<addr2>,...	Batch prices
5	onchainos swap quote --from <from> --to <to> --amount <amt> --chain solana	Quote
6	onchainos swap swap --from <from> --to <to> --amount <amt> --chain solana --wallet <addr> --slippage <pct>	Trade
7	onchainos wallet addresses --chain 501	Solana address
8	onchainos wallet balance --chain 501	Balance
9	onchainos wallet contract-call --chain 501 --to <router> --unsigned-tx <callData>	TEE signing
10	onchainos wallet order-status --order-id <orderId>	Trade confirmation

---

Troubleshooting

Issue	Solution
"FATAL: onchainos CLI not found"	Install onchainos and ensure it is in PATH
Dashboard won't open	Check if port 3244 is in use: lsof -i:3244
Bot has no trade signals	Leaderboard may have no new entries; wait for changes
Login expired	Re-run onchainos wallet login <email>
Live mode buy fails	Check SOL balance >= MIN_WALLET_BAL (0.06)

---

Glossary

Term	Definition
Ranking Exit	Ranking Exit — automatically sell entire position when token drops out of the Top 20 gainers leaderboard; exit when momentum is lost
Slot Guard	13 basic metric pre-checks based on leaderboard data, zero additional API calls
Advanced Safety	9 deep safety checks using onchainos token advanced-info to obtain Dev/Bundler/LP data
Holder Risk	3 holder risk checks using onchainos token holders to detect suspicious/phishing addresses
Momentum Score	Momentum score (0-125), calculated from buy ratio, price change, trader count, liquidity, and safety bonuses
Quick Stop	Quick Stop — triggers when position is held for N minutes and loss exceeds N% (both conditions must be met)
Trailing Stop	Trailing Stop — triggers sell when profit reaches activation threshold then pulls back beyond threshold from peak
Unconfirmed Position	Pending position created when trade confirmation times out; requires multiple balance checks before discarding
Fail-Closed	When safety check API fails, treat as unsafe and do not buy
TEE	Trusted Execution Environment — onchainos signing is performed inside a secure enclave
Agentic Wallet	onchainos managed wallet with private keys inside TEE, never leaving the secure environment
DAILY_LOSS_LIMIT	Daily loss ratio (of TOTAL_BUDGET); when triggered, all buying stops for the day
MC / MCAP	Market Cap — token total supply × current price, measuring token scale
LP	Liquidity Pool — token pair pool on DEX for trading; larger LP means lower slippage
LP Burn	Permanently burning LP tokens to ensure liquidity cannot be withdrawn by developers
Rug Pull	Malicious act where developers suddenly withdraw liquidity or dump all holdings, crashing the token price to zero