meme-executor

name	meme-executor
description	Solana memecoin trade execution and simulation. Use when you already have a TradePlan (token, side, size, SL/TP, slippage, risk mode) from meme-trader / flow-tracker / degen-savant and want to either simulate or send a swap through a Solana wallet.
tools	Read(pattern:.claude/skills/meme-executor/**), TodoWrite

Meme Executor - Solana Trade Execution Layer

Solana-focused execution skill that turns high‑level trade plans into concrete orders.

Current Status: Phase 1 (Safe Mode)

Component	Status	Risk Level
execute-trade.ts	DRY RUN only	None
auto-trader.ts	DRY RUN only	None
jupiter-client.ts	Quote-only	None
wallet-manager.ts	Read-only	None
position-tracker.ts	Local tracking	None

No real transactions are sent in Phase 1.

When to Use

• You already have a TradePlan from other agents/skills:
  • meme-trader (signals + sizing)
  • flow-tracker (liquidity + position sizing)
  • degen-savant (narrative / conviction)
  • contract-surgeon (rug/safety cleared)
• You want to:
  • Simulate trades and log PnL without sending real transactions
  • Eventually route real orders via a configured Solana wallet + DEX router

Core Responsibilities

• Parse a structured trade plan (token, side, size %, target size, SL/TP, slippage).
• Apply simple risk checks (max position %, max concurrent positions hooks).
• DRY‑RUN by default – log what would be traded and why.
• Provide clear TODO hooks for wiring:
  • Jupiter swap routing
  • Wallet private key / signer configuration
  • Trade log storage (JSONL or database)

TradePlan Interface

The executor expects a JSON payload matching this shape:

export interface TradePlan {
  tokenAddress: string;
  symbol?: string;
  chain: 'solana';
  side: 'buy' | 'sell';
  // either percentage of portfolio or absolute amount in SOL
  sizing: {
    mode: 'percent' | 'absolute';
    value: number; // e.g. 2 = 2% or 0.5 = 0.5 SOL
  };
  riskMode: 'degen' | 'moderate' | 'conservative';
  entryLimitPrice?: number; // optional, for limit-style behavior
  maxSlippageBps: number; // e.g. 1000 = 10%
  stopLossPrice?: number;
  takeProfit1?: number;
  takeProfit2?: number;
  notes?: string; // free-form rationale from upstream agents
  dryRun?: boolean; // default true; set false only once wired to real wallet
}

Usage (Simulation First)

From the repo root, a typical simulated execution call will look like:

npx tsx .claude/skills/meme-executor/scripts/execute-trade.ts \
  --plan-file /path/to/trade-plan.json

Where trade-plan.json contains a single TradePlan object.

Output Formats

• Simulation Log (default) – human-friendly summary:
  • What would be bought/sold
  • Position size and notional exposure
  • SL/TP levels and implied RR
  • Any risk rule violations
• JSON Log (--json) – machine-friendly output for chaining into other tools.

New Phase 1 Components

Jupiter Client (Quote-Only)

Get swap quotes without executing:

# Get a quote for swapping SOL to a token
npx tsx .claude/skills/meme-executor/scripts/jupiter-client.ts \
  --quote --input SOL --output <TOKEN_MINT> --amount 0.1

# JSON output
npx tsx .claude/skills/meme-executor/scripts/jupiter-client.ts \
  --quote --input SOL --output BONK --amount 0.5 --json

Wallet Manager (Read-Only)

Check wallet balances without signing:

# Check balance of any wallet
npx tsx .claude/skills/meme-executor/scripts/wallet-manager.ts \
  --balance --address <WALLET_ADDRESS>

# Use devnet
npx tsx .claude/skills/meme-executor/scripts/wallet-manager.ts \
  --balance --address <WALLET_ADDRESS> --devnet

Position Tracker

Track open positions locally:

# Add a position (after buy)
npx tsx .claude/skills/meme-executor/scripts/position-tracker.ts \
  --add --token <MINT> --symbol MEME --entry-price 0.001 --amount 1000 \
  --sl 0.0007 --tp 0.002

# List positions
npx tsx .claude/skills/meme-executor/scripts/position-tracker.ts --list

# Check stop-loss/take-profit triggers
npx tsx .claude/skills/meme-executor/scripts/position-tracker.ts \
  --check --prices '{"<MINT>": 0.0015}'

# Close a position
npx tsx .claude/skills/meme-executor/scripts/position-tracker.ts \
  --close --token <MINT> --exit-price 0.002

Phase Roadmap

Phase	Components	Risk
1 (Current)	Quote, balance, tracking	None
2	Devnet swap execution	Low (fake SOL)
3	Mainnet paper trading	None (simulated)
4	Mainnet live (small size)	High

Data Quality Validation Layer

<data_validation> Pre-Execution Data Requirements: All trades (even simulated) require validated data to ensure backtesting fidelity.

interface ExecutionDataQuality {
  price_quality: {
    score: number;           // Min 90 for execution
    sources_count: number;   // Min 2
    max_deviation: number;   // Max 5% between sources
    freshness_ms: number;    // Max 30000 (30s)
  };
  liquidity_check: {
    available: number;       // Must support trade size
    slippage_estimate: number;
    depth_ratio: number;     // Our size / available liquidity
  };
  risk_clearance: {
    rug_score: number;       // From meme-trader
    position_approved: boolean; // From risk-portfolio-manager
    kill_switch_status: 'active' | 'paused' | 'halted';
  };
}

interface ValidationResult {
  approved: boolean;
  quality_score: number;
  warnings: string[];
  blockers: string[];
}

Validation Pipeline:

Trade Plan → Price Validation → Liquidity Check → Risk Clearance → Execute/Reject
                 ↓                    ↓                 ↓
            Min 2 sources      Size < 5% pool    No kill switch
            Max 5% deviation   Slippage < limit   Position approved
            Max 30s stale      Depth sufficient   Rug score < 7

Validation Output (included in dry-run):

DATA VALIDATION REPORT
═════════════════════════════════════

PRICE DATA: PASSED (94/100)
├─ Sources: 3/3 (dexscreener, birdeye, jupiter)
├─ Prices: $0.00042 | $0.000418 | $0.000421
├─ Deviation: 0.48% (< 5% threshold)
├─ Freshness: 8 seconds ago
└─ Status: VALID

LIQUIDITY CHECK: PASSED
├─ Available Liquidity: $127,000
├─ Trade Size: $500 (0.39% of pool)
├─ Estimated Slippage: 0.8%
├─ Depth Ratio: HEALTHY
└─ Status: SUFFICIENT

RISK CLEARANCE: PASSED
├─ Rug Score: 4/10 (acceptable)
├─ Position Sizing: APPROVED (2.3% of portfolio)
├─ Kill Switch: ACTIVE
├─ Daily Loss Buffer: $1,260 remaining
└─ Status: CLEARED

OVERALL: APPROVED FOR EXECUTION
Quality Score: 92/100
Warnings: None
Blockers: None

Rejection Scenarios:

Condition	Action	Message
Price quality < 90	REJECT	"Insufficient price data quality"
Single source only	WARN	"Low confidence - single source"
Price deviation > 5%	REJECT	"Price disagreement - investigate"
Stale data > 60s	REJECT	"Data too old for execution"
Size > 5% of pool	WARN	"High slippage expected"
Rug score > 7	REJECT	"Token failed safety check"
Kill switch halted	REJECT	"Trading halted - risk limit"
</data_validation>

Real-Time Data Integration

<real_time_data> Data Sources for Execution:

const executionDataSources = {
  price: {
    primary: 'jupiter',      // Most accurate for Solana swaps
    fallback: ['dexscreener', 'birdeye'],
    refresh_interval: 5000,  // 5 seconds
    max_age: 30000,          // 30 seconds
  },
  liquidity: {
    primary: 'jupiter',      // Direct pool data
    fallback: ['raydium-api', 'dexscreener'],
    refresh_interval: 10000,
  },
  execution: {
    rpc: 'helius',
    backup_rpc: 'triton',
    commitment: 'confirmed',
  },
};

Pre-Execution Price Fetch:

# Fetch validated price before execution
npx tsx .claude/skills/meme-executor/scripts/pre-execution-check.ts \
  --token <MINT> \
  --size 500 \
  --validate-liquidity \
  --output json

</real_time_data>

Safety & TODOs

• This skill MUST remain DRY‑RUN ONLY until:
  • A secure wallet management pattern is agreed
  • Jupiter / router integration is properly tested on devnet
  • Data validation pipeline is production-tested
• When enabling live trading:
  • Add explicit --live flag and environment guardrails
  • Require confirmation in higher‑level orchestration agents
  • Implement daily loss limits via risk-portfolio-manager
  • Add kill switch command integration
  • Require minimum data quality score of 90/100
  • Log all executions for audit and backtesting validation