| 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.
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)
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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Technical Risk: On-chain transactions are irreversible. Smart contracts may contain vulnerabilities. Network congestion may cause transaction delays or failures.
- 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.
- 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.
- 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.
- 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)
onchainos --version
2. Login to Agentic Wallet (TEE Signing)
onchainos wallet login <your-email>
onchainos wallet status
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:
-
⚠️ 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
-
Ask for total budget in SOL (default 0.5 SOL)
-
AI auto-calculates (let B = user's input budget):
TOTAL_BUDGET = BBUY_AMOUNT = max(B × 0.10, 0.01)
-
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
-
Set mode parameters:
MODE = "live"PAUSED = False
Launch
- Modify corresponding parameters in
config.py based on user answers
- Set
PAUSED = False (allow bot to run normally after interaction confirmation)
- Check prerequisites:
onchainos --version, onchainos wallet status
- Start bot:
python3 ranking_sniper.py
- Show Dashboard link:
http://localhost:3244
- 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\ -\ 榜单狙击手
onchainos wallet status
python3 ranking_sniper.py
open http://localhost:3244
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)
- RPC balance 0 ≠ token doesn't exist (Solana RPC has severe latency). Unconfirmed positions require zeroCount >= 10 AND elapsed > 180s before discarding.
- Writing to positions.json requires holding
_state_lock.
- When
order_status() returns TIMEOUT, always create an unconfirmed position.
- Safety check API failure → Fail-Closed, do not buy.
- Rank Exit (EXIT 0) has the highest priority.
- Daily loss limit triggered → stop all buying for the day.
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 |
