outsmart-agent 1.0.0-alpha.1 → 1.0.0-alpha.11

package/.claude-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "outsmart-agent",
+  "version": "1.0.0",
+  "description": "Solana DeFi survival toolkit for AI agents — trade, LP, snipe, and farm across 18 DEX protocols to earn your own existence",
+  "author": {
+    "name": "outsmartchad",
+    "email": "outsmartchad@users.noreply.github.com"
+  },
+  "homepage": "https://github.com/outsmartchad/outsmart-agent",
+  "keywords": [
+    "solana", "defi", "trading", "mcp", "ai-agent",
+    "lp-farming", "sniping", "dex", "meteora", "raydium",
+    "jupiter", "pumpfun", "survival", "automaton"
+  ],
+  "license": "ISC",
+  "skills": [
+    "./skills/outsmart-dex-trading",
+    "./skills/outsmart-lp-farming",
+    "./skills/outsmart-lp-sniping",
+    "./skills/outsmart-dca-grid",
+    "./skills/outsmart-trenching",
+    "./skills/outsmart-devving-coins",
+    "./skills/outsmart-prediction-markets",
+    "./skills/outsmart-survival",
+    "./skills/outsmart-percolator-perps"
+  ],
+  "agents": [
+    "./agents/solana-trading-expert.md"
+  ]
+}

package/README.md

@@ -1,35 +1,20 @@
 # outsmart-agent
 
-**MCP server + AI skills for Solana trading.** Wraps the [`outsmart`](https://www.npmjs.com/package/outsmart) trading library as 11 MCP tools for AI agents.
+DeFi survival toolkit for AI agents on Solana. Trade, LP, snipe, trench, dev coins, operate perp exchanges, and farm across 18 DEX protocols. Earn your own existence.
 
 ```
 npx outsmart-agent
 ```
 
-> Starts an MCP server (stdio transport) exposing buy, sell, LP, quote, and balance tools across 18 Solana DEX protocols.
+## Why
 
----
+An AI agent needs money to stay alive — compute costs, inference fees, API calls. This gives any MCP-compatible agent the tools to earn revenue on Solana through DeFi. LP farming, memecoin trenching, token launching, prediction markets, systematic DCA — whatever the market calls for.
 
-## Quick Start
-
-### 1. Install
-
-```bash
-npm install -g outsmart-agent
-```
-
-### 2. Set Environment Variables
+42 MCP tools for execution. 9 AI skills that teach the agent **when** and **why**, not just how.
 
-```bash
-export WALLET_PRIVATE_KEY="your-base58-private-key"
-export RPC_URL="https://your-rpc-endpoint.com"
-# Optional:
-export JUPITER_API_KEY="your-jupiter-api-key"
-```
-
-### 3. Configure Your MCP Client
+## Quick Start
 
-#### Claude Desktop
+### Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -40,164 +25,197 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["outsmart-agent"],
       "env": {
-        "WALLET_PRIVATE_KEY": "your-base58-private-key",
-        "RPC_URL": "https://your-rpc-endpoint.com"
+        "PRIVATE_KEY": "your-base58-private-key",
+        "MAINNET_ENDPOINT": "https://your-rpc-endpoint.com"
       }
     }
   }
 }
 ```
 
-#### Cursor
-
-Add to `.cursor/mcp.json` in your project:
+### Cursor
 
-```json
-{
-  "mcpServers": {
-    "outsmart-agent": {
-      "command": "npx",
-      "args": ["outsmart-agent"],
-      "env": {
-        "WALLET_PRIVATE_KEY": "your-base58-private-key",
-        "RPC_URL": "https://your-rpc-endpoint.com"
-      }
-    }
-  }
-}
-```
+Same config in `.cursor/mcp.json`.
 
-#### Claude Code
+### Claude Code
 
 ```bash
 claude mcp add outsmart-agent -- npx outsmart-agent
 ```
 
----
-
-## MCP Tools
-
-10 tools exposed over stdio transport:
-
-| Tool | Description |
-|------|-------------|
-| `solana_buy` | Buy tokens with SOL on any DEX |
-| `solana_sell` | Sell tokens for SOL (percentage-based) |
-| `solana_quote` | Get on-chain price from a pool |
-| `solana_add_liquidity` | Add LP to a pool (supports DLMM strategies) |
-| `solana_remove_liquidity` | Remove LP from a pool |
-| `solana_claim_fees` | Claim accumulated swap fees from LP positions |
-| `solana_list_positions` | List user's LP positions in a pool |
-| `solana_token_info` | Get token market data from DexScreener |
-| `solana_list_dexes` | List all available DEX adapters and capabilities |
-| `solana_wallet_balance` | Check SOL or SPL token balance |
-
-### Example: Buy a Token
-
-```
-User: "Buy 0.1 SOL of USDC on jupiter-ultra"
+### Automaton / Conway Cloud
 
-Agent calls: solana_buy({
-  dex: "jupiter-ultra",
-  token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
-  amount: 0.1
-})
+```bash
+npx skills add outsmartchad/outsmart-agent
 ```
 
-### Example: Provide Liquidity
-
-```
-User: "Add 0.5 SOL of liquidity to this Meteora DLMM pool"
-
-Agent calls: solana_add_liquidity({
-  dex: "meteora-dlmm",
-  pool: "BGm1tav58oGcsQJehL9WXBFXF7D27vZsKefj4xJKD5Y",
-  amount_sol: 0.5,
-  strategy: "spot",
-  bins: 50
-})
-```
+## MCP Tools
 
----
+### DEX Tools (11)
+
+| Tool | What |
+|------|------|
+| `dex_buy` | Buy tokens with SOL on any DEX |
+| `dex_sell` | Sell tokens (percentage-based) |
+| `dex_quote` | On-chain price from a pool |
+| `dex_snipe` | Competitive buy with Jito MEV tip |
+| `dex_find_pool` | Find pool address for a token pair |
+| `dex_create_pool` | Create DAMM v2 pool on Meteora |
+| `dex_add_liquidity` | Add LP (DLMM bins, DAMM v2 full-range) |
+| `dex_remove_liquidity` | Remove LP |
+| `dex_claim_fees` | Collect swap fees from LP |
+| `dex_list_positions` | Your LP positions in a pool |
+| `dex_list_dexes` | All 18 adapters + capabilities |
+
+### Launchpad Tools (1)
+
+| Tool | What |
+|------|------|
+| `launchpad_create_coin` | Launch token on PumpFun |
+
+### Solana Tools (2)
+
+| Tool | What |
+|------|------|
+| `solana_token_info` | DexScreener market data |
+| `solana_wallet_balance` | SOL and token balances |
+
+### Jupiter Tools (9)
+
+| Tool | What |
+|------|------|
+| `jupiter_shield` | Token security warnings |
+| `jupiter_prediction_events` | Browse/search prediction market events |
+| `jupiter_prediction_market` | Market details + orderbook depth |
+| `jupiter_prediction_order` | Place buy/sell orders on prediction markets |
+| `jupiter_prediction_positions` | Your positions + trade history |
+| `jupiter_prediction_claim` | Claim winnings from resolved markets |
+| `jupiter_dca_create` | Create recurring DCA order |
+| `jupiter_dca_list` | List active/historical DCA orders |
+| `jupiter_dca_cancel` | Cancel a DCA order |
+
+### Percolator Perp Tools (15)
+
+| Tool | What |
+|------|------|
+| `percolator_create_market` | Create a permissionless perp exchange |
+| `percolator_init_user` | Register a trader account on a market |
+| `percolator_long` | Open a long position (auto-detects account, auto-cranks) |
+| `percolator_short` | Open a short position (auto-detects account, auto-cranks) |
+| `percolator_close` | Close an open position (auto-detects size and direction) |
+| `percolator_deposit` | Deposit collateral |
+| `percolator_withdraw` | Withdraw collateral |
+| `percolator_trade` | Open/close/modify positions (low-level, manual indices) |
+| `percolator_push_oracle` | Update oracle price (admin-oracle mode) |
+| `percolator_crank` | Run keeper crank |
+| `percolator_market_state` | Read full market state |
+| `percolator_insurance_lp` | Deposit/withdraw insurance fund LP |
+| `percolator_keeper_start` | Start WebSocket oracle keeper (watches DEX pools, pushes prices) |
+| `percolator_keeper_stop` | Stop the running keeper |
+| `percolator_keeper_status` | Get keeper stats (pushes, errors, active watchers) |
+
+### Polymarket Tools (4)
+
+| Tool | What |
+|------|------|
+| `polymarket_search` | Search prediction markets by keyword |
+| `polymarket_trending` | Discover highest-volume active events |
+| `polymarket_event` | Detailed event info by slug or ID |
+| `polymarket_orderbook` | CLOB orderbook (bids/asks) for a market token |
+
+> Polymarket tools are **read-only** — no wallet or API key needed. Uses the public Gamma API and CLOB API.
+
+## Skills
+
+9 strategy skills that teach agents how to think about Solana DeFi:
+
+| Skill | What |
+|-------|------|
+| **outsmart-dex-trading** | Tool reference, DEX selection, safety rules |
+| **outsmart-lp-farming** | DLMM concentrated LP, DAMM v2 pool creation, fee compounding |
+| **outsmart-lp-sniping** | Evaluating new launches, early entry, position sizing |
+| **outsmart-trenching** | Memecoin trading — finding metas, security checks, take-profit ladders |
+| **outsmart-devving-coins** | Launching tokens — catching narratives, PumpFun, Jupiter Studio, LaunchLab |
+| **outsmart-dca-grid** | Jupiter Recurring DCA + DLMM grid trading |
+| **outsmart-prediction-markets** | Probability estimation, edge calculation, Jupiter + Polymarket + Futarchy |
+| **outsmart-survival** | Capital management, survival tiers, emergency liquidation |
+| **outsmart-percolator-perps** | Operating perp exchanges — market creation, LP, pricing, keeper duties |
 
 ## Supported DEXes
 
-18 adapters covering every major Solana DEX protocol:
+18 adapters across every major Solana protocol:
 
-**Swap Aggregators** (best price routing):
-- `jupiter-ultra` — Jupiter Ultra API
-- `dflow` — DFlow intent-based routing
+**Aggregators:** jupiter-ultra, dflow
+**Raydium:** amm-v4, cpmm, clmm, launchlab
+**Meteora:** damm-v2, dlmm, damm-v1, dbc
+**PumpFun:** pumpswap amm, bonding curve
+**Others:** orca, pancakeswap-clmm, byreal-clmm, fusion-amm, futarchy-amm, futarchy-launchpad
 
-**On-Chain DEXes** (direct pool execution):
-- `raydium-amm-v4`, `raydium-cpmm`, `raydium-clmm`, `raydium-launchlab`
-- `meteora-damm-v2`, `meteora-dlmm`, `meteora-damm-v1`, `meteora-dbc`
-- `pumpfun-amm`
-- `orca`
-- `byreal-clmm`, `pancakeswap-clmm`
-- `fusion-amm`, `futarchy-amm`, `futarchy-launchpad`
+## Architecture
 
-**LP Management** (add/remove/claim):
-- `meteora-damm-v2` — Full LP lifecycle
-- `meteora-dlmm` (via `meteora-lp-dlmm`) — Concentrated LP with bin strategies
+```
+outsmart (npm)              outsmart-agent (this repo)
+──────────────              ──────────────────────────
+18 DEX adapters             MCP server (42 tools)
+Percolator perps            9 AI skills
+TX landing providers        Agent definition
+Wallet + TX helpers         Plugin manifest
+DexScreener API
+```
 
----
+`outsmart-agent` imports `outsmart` as a dependency. The MCP server is a thin wrapper — validates params, calls adapter methods, returns JSON. Polymarket tools call their public REST APIs directly (no dependency needed).
 
-## AI Skills
+## For Autonomous Agents
 
-This package includes a trading skill at `skills/outsmart/SKILL.md` compatible with the [skills.sh](https://skills.sh) CLI:
+If you're building a self-sustaining agent, here's a starting point:
 
-```bash
-npx skills add outsmartchad/outsmart-agent
 ```
+You are a DeFi survival agent on Solana. Earn enough to pay for compute.
 
-The skill teaches AI agents:
-- Which DEX to use for different scenarios
-- How to check token safety before trading
-- Common workflows (buy, sell, LP, exit)
-- Safety rules for autonomous trading
-
----
+40% LP farming, 15% DCA/grid, 10% trenching, 10% sniping,
+10% prediction markets, 10% reserve, 5% experimental.
 
-## Architecture
+Check credits every 6 hours. Below $0.50 → conservative.
+Below $0.10 → liquidate everything and top up.
 
+Never >5% on a single trade. Take profits. Track what works. Evolve.
 ```
-outsmart (npm package)           outsmart-agent (this repo)
-──────────────────────           ─────────────────────────
-18 DEX adapters                  MCP server (11 tools)
-12 TX landing providers          AI skills (SKILL.md)
-Wallet/connection helpers        Claude Code marketplace plugin
-DexScreener utility              Re-exports outsmart API
-```
-
-`outsmart-agent` imports `outsmart` as an npm dependency — zero code duplication. The MCP server is a thin wrapper (~320 lines) that validates params, calls adapter methods, and returns JSON results.
 
----
-
-## Environment Variables
+## Environment
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `WALLET_PRIVATE_KEY` | Yes | Base58-encoded Solana private key |
-| `RPC_URL` | Yes | Solana RPC endpoint |
-| `JUPITER_API_KEY` | No | For jupiter-ultra adapter |
-| `DFLOW_API_KEY` | No | For dflow adapter |
-
----
+| `PRIVATE_KEY` | Yes | Base58 Solana private key |
+| `MAINNET_ENDPOINT` | Yes | Solana RPC (Helius, Triton, etc.) |
+| `JUPITER_API_KEY` | No | Jupiter Ultra, Shield, Prediction, DCA |
+| `DEVNET_ENDPOINT` | No | Solana devnet RPC (Percolator) |
+| `DFLOW_API_KEY` | No | DFlow |
+
+## Roadmap
+
+- [x] MCP Server — 42 tools (11 DEX + 1 Launchpad + 2 Solana + 9 Jupiter + 15 Percolator + 4 Polymarket), 18 DEX adapters
+- [x] AI Skills — 9 strategy skills
+- [x] Claude Code Plugin manifest
+- [x] Percolator — Permissionless perp exchange creation, trading, LP, insurance
+- [x] Oracle Keeper — WebSocket + gRPC keeper bots (8 DEX types, real-time price feed)
+- [x] Perp Trading — High-level long/short/close tools with auto-detection
+- [x] Polymarket — Read-only prediction market data (search, trending, events, orderbook)
+- [ ] Event Streaming — Yellowstone gRPC for real-time pool creation
+- [ ] LP Manager — Autonomous rebalancing and fee compounding
+- [ ] Strategy Engine — Tier-aware capital allocation
 
 ## Related
 
-- **[outsmart](https://www.npmjs.com/package/outsmart)** — The underlying trading library + CLI
-- **[outsmart-cli](https://github.com/outsmartchad/outsmart-cli)** — CLI for humans: `outsmart buy --dex raydium-cpmm --pool <POOL> --amount 0.1`
+- **[outsmart](https://www.npmjs.com/package/outsmart)** — The trading library + CLI
+- **[outsmart-cli](https://github.com/outsmartchad/outsmart-cli)** — Source repo
 
-## Discord
+## Community
 
-https://discord.gg/dc3Kh3Y3yJ
+Discord: https://discord.gg/dc3Kh3Y3yJ
 
 ## Disclaimer
 
-This software is provided "as is", without warranty of any kind. Use at your own risk. The authors take no responsibility for any financial loss. Users are responsible for ensuring compliance with applicable laws.
-
-Never share your private keys.
+Use at your own risk. Memecoins go to zero. LP positions suffer impermanent loss. Prediction markets can lose. Never trade with money you can't afford to lose. Never share your private keys.
 
 ## License
 

package/agents/solana-trading-expert.md

@@ -0,0 +1,52 @@
+---
+description: Expert agent for Solana DeFi trading decisions. Analyzes tokens, selects DEXes, evaluates risks, and recommends trade parameters. Use when the user needs help deciding *what* to trade, *where* to trade it, or *how much* to risk — not just executing a trade.
+model: opus
+allowed-tools: Read, Glob, Grep, WebFetch
+---
+
+# Solana Trading Expert
+
+You are an expert in Solana DeFi trading with deep knowledge of every DEX protocol, LP mechanism, and token lifecycle on Solana.
+
+## Expertise
+
+1. **DEX Selection** — Which adapter to use for which token/pool type (aggregator vs on-chain, CPMM vs CLMM vs DLMM)
+2. **Token Analysis** — Reading DexScreener data: red flags (low liquidity, few buyers, fresh deployer), green flags (growing volume, organic distribution)
+3. **LP Strategy** — When to LP (high volume/TVL ratio), where (DLMM bins vs DAMM v2 full-range), how to set bin width and strategy
+4. **Risk Assessment** — Position sizing, rug detection, slippage estimation, impermanent loss
+5. **Pool Mechanics** — How each Solana AMM works: constant product, concentrated liquidity, DLMM bins, bonding curves
+6. **Stablecoin Routing** — When pools quote in USDC/USDT/USD1 instead of SOL, and how auto-swap handles it
+7. **TX Landing** — When to use Jito tips, MEV protection strategies, priority fee optimization
+8. **PumpFun Lifecycle** — Bonding curve → graduation → AMM migration, when to enter/exit
+9. **Survival Economics** — Capital allocation for autonomous agents, profit extraction timing, risk budgets
+10. **Memecoin Alpha** — Reading social signals, volume patterns, whale behavior, and smart money flows
+
+## Response Guidelines
+
+- Always provide specific, actionable recommendations
+- Include risk warnings — never minimize downside
+- Cite specific numbers: pool addresses, liquidity depth, volume/TVL ratios
+- For LP recommendations, specify strategy (spot/curve/bid-ask), bin count, and expected APR range
+- For buys, recommend position size as percentage of portfolio, not absolute amounts
+- If data is insufficient to make a recommendation, say so explicitly
+
+## DEX Quick Reference
+
+| Scenario | DEX | Why |
+|----------|-----|-----|
+| Best price, any token | `jupiter-ultra` | Aggregates all routes |
+| Specific Raydium pool | `raydium-cpmm` / `raydium-clmm` / `raydium-amm-v4` | Direct on-chain |
+| Meteora concentrated LP | `meteora-dlmm` | Bin-based, high fee capture |
+| Meteora full-range LP | `meteora-damm-v2` | Full lifecycle support |
+| New PumpFun tokens | `pumpfun-amm` | Post-graduation AMM |
+| Bonding curve tokens | `pumpfun` | Pre-graduation |
+| Raydium launches | `raydium-launchlab` | Bonding curve → CPMM |
+
+## Risk Framework
+
+| Risk Level | Position Size | Max Loss | Use Case |
+|-----------|---------------|----------|----------|
+| **Degen** | 1-5% of portfolio | Total loss acceptable | New launches, memecoins, sniping |
+| **Moderate** | 5-15% | 50% drawdown | Established tokens, LP farming |
+| **Conservative** | 15-40% | 20% drawdown | Blue chips (SOL, JUP, JTO), stable LPs |
+| **Reserve** | 5-10% | Never touch | Emergency compute/gas fund |

package/dist/mcp/server.d.ts

@@ -2,14 +2,35 @@
 /**
  * outsmart-agent MCP Server
  *
- * Exposes 11 MCP tools wrapping the `outsmart` trading library.
+ * Exposes 42 MCP tools wrapping the `outsmart` trading library + Jupiter APIs + Percolator + Polymarket.
  * Runs over stdio transport — start with `npx outsmart-agent`.
  *
- * Tools:
- *   solana_buy, solana_sell, solana_quote, solana_find_pool,
- *   solana_add_liquidity, solana_remove_liquidity, solana_claim_fees,
- *   solana_list_positions, solana_token_info, solana_list_dexes,
- *   solana_wallet_balance
+ * DEX Tools (11):
+ *   dex_buy, dex_sell, dex_quote, dex_find_pool, dex_snipe,
+ *   dex_create_pool, dex_add_liquidity, dex_remove_liquidity,
+ *   dex_claim_fees, dex_list_positions, dex_list_dexes
+ *
+ * Launchpad Tools (1):
+ *   launchpad_create_coin
+ *
+ * Solana Tools (2):
+ *   solana_token_info, solana_wallet_balance
+ *
+ * Jupiter Tools (9):
+ *   jupiter_shield,
+ *   jupiter_prediction_events, jupiter_prediction_market,
+ *   jupiter_prediction_order, jupiter_prediction_positions, jupiter_prediction_claim,
+ *   jupiter_dca_create, jupiter_dca_list, jupiter_dca_cancel
+ *
+ * Percolator Perp Tools (15):
+ *   percolator_create_market, percolator_trade, percolator_long, percolator_short,
+ *   percolator_close, percolator_deposit, percolator_withdraw,
+ *   percolator_market_state, percolator_list_markets,
+ *   percolator_push_price, percolator_crank, percolator_insurance_lp,
+ *   percolator_keeper_start, percolator_keeper_stop, percolator_keeper_status
+ *
+ * Polymarket Tools (4):
+ *   polymarket_search, polymarket_trending, polymarket_event, polymarket_orderbook
  */
 export {};
 //# sourceMappingURL=server.d.ts.map

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}