@potswap_io/mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,91 +1,132 @@
-# @potswap_io/mcp
-
-The Solana swap tool for AI agents. One MCP server gives your agent best-route swaps across every Solana DEX (Metis, JupiterZ, DFlow and OKX compete on each order, MEV-protected), token research with risk flags, balances, and POT rewards for every trade.
-
-- **Non-custodial.** Transactions are signed on your machine with your own keypair. The key never leaves the process and is redacted from every output.
-- **Safe by default.** `swap` needs `confirm: true`; per-trade cap 1 SOL; slippage cap 3%; dry-run mode; a 0.01 SOL reserve is always kept. Every error says whether funds were debited.
-- **Pays you back.** Potswap charges a 0.5% fee inside the swap and returns it to the trading wallet as POT points (Season 1). Agents earn exactly like humans.
-- **$0 to run.** Talks only to `potswap.io`; no API keys needed.
-
-## Install
-
-Node 20+. No install step; run it with `npx`.
-
-### Claude Desktop
-
-`claude_desktop_config.json` (Settings → Developer → Edit Config):
-
-```json
-{
-  "mcpServers": {
-    "potswap": {
-      "command": "npx",
-      "args": ["-y", "@potswap_io/mcp"],
-      "env": {
-        "SOLANA_PRIVATE_KEY": "<base58 secret or JSON byte array>",
-        "POTSWAP_MAX_TRADE_SOL": "0.5"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
-
-```bash
-claude mcp add potswap -e SOLANA_KEYPAIR_PATH=~/.config/solana/id.json -- npx -y @potswap_io/mcp
-```
-
-### Cursor
-
-`.cursor/mcp.json` in your project:
-
-```json
-{ "mcpServers": { "potswap": { "command": "npx", "args": ["-y", "@potswap_io/mcp"], "env": { "SOLANA_KEYPAIR_PATH": "/home/you/.config/solana/id.json" } } } }
-```
-
-Without a key the server still runs in read-only mode (search, quotes, trending, points of any wallet).
-
-## Configuration
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `SOLANA_PRIVATE_KEY` | — | base58 secret key (64 bytes) or JSON byte array, as exported by Phantom / `solana-keygen` |
-| `SOLANA_KEYPAIR_PATH` | — | path to a `solana-keygen` JSON file; used when `SOLANA_PRIVATE_KEY` is unset |
-| `SOLANA_RPC_URL` | Potswap's RPC proxy | your own RPC if you trade a lot |
-| `POTSWAP_MAX_TRADE_SOL` | `1` | refuse any swap whose input is worth more than this many SOL |
-| `POTSWAP_MAX_SLIPPAGE_BPS` | `300` | refuse requested slippage above this |
-| `POTSWAP_DRY_RUN` | `false` | `true` = `swap` never signs; returns what it would have done |
-| `POTSWAP_API` | `https://www.potswap.io` | base URL |
-
-Use a dedicated agent wallet with only the funds you want the agent to control. Keep the caps low until you trust the agent's behaviour.
-
-## Tools
-
-| Tool | Does |
-|---|---|
-| `search_tokens {query}` | Find tokens by name/symbol/mint |
-| `get_token {mint}` | Price, mcap, liquidity, holders, audit data, **risk badges** (`riskLevel` 0 safe → 3 danger) |
-| `get_trending {kind}` | `new`, `trending`, `top`, `graduating` lists |
-| `get_quote {inputMint, outputMint, amount}` | Best route, fee, impact, router. `amount` is in UI units (1 = 1 SOL) |
-| `swap {…, confirm: true}` | Executes at the best route and returns the signature, amounts, fee and POT points |
-| `get_balances {wallet?}` | SOL + SPL balances with USD |
-| `get_positions {wallet?}` | Holdings with USD; PnL coming |
-| `get_points {wallet?}` | Season 1 points, POT allocated / claimable, next unlock |
-| `get_leaderboard` | Top wallets by fee paid |
-
-Example prompt: *"Check BONK's risk flags, and if riskLevel is 0 or 1 buy 0.1 SOL worth."* The agent calls `get_token`, then `swap` with `confirm: true`; you can require that it shows you the quote first by leaving `POTSWAP_DRY_RUN=true` until you are comfortable.
-
-## Fees and rewards
-
-Each swap carries Potswap's 0.5% integrator fee via Jupiter's referral program; Jupiter keeps 20% of it. The fee basis is credited to the trading wallet as Season 1 points, split daily: 666,666 POT per epoch, by `fee^1.1`, capped at 10% per wallet. Points become POT tokens after the token launch; unlock 7 days after each epoch. Details: https://www.potswap.io
-
-## Development
-
-```bash
-cd mcp && npm i && npm test      # unit tests over the real MCP protocol (in-memory transport)
-npm run dev                       # run from source
-npm run sync-shared && npm run build
-```
-
-MIT © Potswap
+# @potswap_io/mcp
+
+The Solana swap tool for AI agents. One MCP server gives your agent best-route swaps across every Solana DEX (Metis, JupiterZ, DFlow and OKX compete on each order, MEV-protected), token research with risk flags, balances, and POT rewards for every trade.
+
+- **Non-custodial.** Transactions are signed on your machine with your own keypair. The key never leaves the process and is redacted from every output.
+- **Safe by default.** `swap` needs `confirm: true`; per-trade cap 1 SOL; slippage cap 3%; dry-run mode; a 0.01 SOL reserve is always kept. Every error says whether funds were debited.
+- **Pays you back.** Potswap charges a 2.5% fee inside the swap (1% on swaps of $1,000 or more). Half of its net fees buy and burn POT every epoch, and the fee you paid is credited to your wallet as POT points (Season 1). Agents earn exactly like humans.
+- **$0 to run.** Talks only to `potswap.io`; no API keys needed.
+
+## Install
+
+Node 20+. No install step; run it with `npx`.
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "potswap": {
+      "command": "npx",
+      "args": ["-y", "@potswap_io/mcp"],
+      "env": {
+        "SOLANA_PRIVATE_KEY": "<base58 secret or JSON byte array>",
+        "POTSWAP_MAX_TRADE_SOL": "0.5"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add potswap -e SOLANA_KEYPAIR_PATH=~/.config/solana/id.json -- npx -y @potswap_io/mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json` in your project:
+
+```json
+{ "mcpServers": { "potswap": { "command": "npx", "args": ["-y", "@potswap_io/mcp"], "env": { "SOLANA_KEYPAIR_PATH": "/home/you/.config/solana/id.json" } } } }
+```
+
+Without a key the server still runs in read-only mode (search, quotes, trending, points of any wallet).
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `SOLANA_PRIVATE_KEY` | — | base58 secret key (64 bytes) or JSON byte array, as exported by Phantom / `solana-keygen` |
+| `SOLANA_KEYPAIR_PATH` | — | path to a `solana-keygen` JSON file; used when `SOLANA_PRIVATE_KEY` is unset |
+| *(none)* | `~/.potswap/wallet.json` | created by `wallet_create`; loaded when neither variable is set |
+| `SOLANA_RPC_URL` | Potswap's RPC proxy | your own RPC if you trade a lot |
+| `POTSWAP_MAX_TRADE_SOL` | `1` | refuse any swap whose input is worth more than this many SOL |
+| `POTSWAP_MAX_SLIPPAGE_BPS` | `300` | refuse requested slippage above this |
+| `POTSWAP_MAX_DAILY_SOL` | `5` | daily SOL-equivalent cap across all strategies |
+| `POTSWAP_STATE_DIR` | `~/.potswap` | where the agent wallet, strategies and run logs are stored |
+| `POTSWAP_ALLOWED_TOKENS` | — | comma-separated mints; when set, every swap, strategy leg and stake must stay inside the list |
+| `POTSWAP_ALLOWED_RECIPIENTS` | — | comma-separated addresses; when set, `transfer` only sends to these |
+| `POTSWAP_DRY_RUN` | `false` | `true` = `swap`, `transfer`, stakes and strategy legs never sign; they return what they would have done |
+| `POTSWAP_API` | `https://www.potswap.io` | base URL |
+
+Use a dedicated agent wallet with only the funds you want the agent to control. Keep the caps low until you trust the agent's behaviour.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `search_tokens {query}` | Find tokens by name/symbol/mint |
+| `get_token {mint}` | Price, mcap, liquidity, holders, audit data, **risk badges** (`riskLevel` 0 safe → 3 danger) |
+| `get_trending {kind}` | `new`, `trending`, `top`, `graduating` lists |
+| `get_quote {inputMint, outputMint, amount}` | Best route, fee, impact, router. `amount` is in UI units (1 = 1 SOL) |
+| `swap {…, confirm: true}` | Executes at the best route and returns the signature, amounts, fee and POT points |
+| `get_balances {wallet?}` | SOL + SPL balances with USD |
+| `get_positions {wallet?}` | Holdings with USD value, average cost, unrealised and realised PnL (from swap history) |
+| `get_points {wallet?}` | Season 1 points, POT allocated / claimable, next unlock |
+| `get_leaderboard` | Top wallets by fee paid |
+| `get_price_history {mint, timeframe, limit}` | OHLCV candles from the token's top pool (`1m`…`1d`) |
+
+### Wallet and operations (0.3.0)
+
+| Tool | Does |
+|---|---|
+| `wallet_create {confirm: true}` | Generates a keypair into `POTSWAP_STATE_DIR/wallet.json` (mode 0600) when no wallet is configured. Returns the public key only. **Back the file up**; it is the only copy. |
+| `get_wallet` | Public key, funding instructions, active limits and allowlists, scheduler status |
+| `transfer {to, mint?, amount, confirm: true}` | Sends SOL or any SPL / Token-2022 token, creating the recipient's token account if needed. No Potswap fee. Honours `POTSWAP_ALLOWED_RECIPIENTS`, `POTSWAP_MAX_TRADE_SOL` and the 0.01 SOL reserve |
+| `get_transaction {signature}` | processed / confirmed / finalized / failed / not found, fee, and the wallet's SOL and token balance changes |
+| `get_history {wallet?, limit}` | Recent parsed transactions: swaps (in/out amounts), transfers (direction, counterparty), other |
+| `stake_sol {amount, provider, confirm: true}` | Liquid-stakes SOL into jitoSOL (default) or mSOL at the best route; normal fee and points. `unstake_sol` is the reverse |
+
+Agents that start from nothing: `wallet_create` → fund the address → `get_quote` → `swap`. Set `POTSWAP_ALLOWED_TOKENS` and `POTSWAP_ALLOWED_RECIPIENTS` before giving an agent an unattended wallet.
+
+Example prompt: *"Check BONK's risk flags, and if riskLevel is 0 or 1 buy 0.1 SOL worth."* The agent calls `get_token`, then `swap` with `confirm: true`; you can require that it shows you the quote first by leaving `POTSWAP_DRY_RUN=true` until you are comfortable.
+
+## Strategies: DCA, rebalance, take-profit / stop-loss, limit orders
+
+Standing orders that keep running without you. Every leg is an ordinary Potswap swap (fee + POT points).
+
+| Tool | Example |
+|---|---|
+| `dca_create` | `{ inputMint: SOL, outputMint: USDC, amountPerRun: 0.1, intervalMinutes: 60, totalRuns: 24, confirm: true }` |
+| `rebalance_create` | `{ targets: { SOL: 60, USDC: 40 }, driftPct: 5, checkIntervalMinutes: 60, confirm: true }` (mints, not symbols) |
+| `tpsl_create` | `{ mint: BONK, sellPct: 50, takeProfitPct: 50, stopLossPct: 20, trailingPct: 15, confirm: true }` |
+| `limit_order_create` | `{ side: 'buy', mint: BONK, amount: 0.1, triggerPriceUsd: 0.00001, condition: 'below', expiresAt?, confirm: true }` — fills once when the price crosses, then completes |
+| `strategy_list`, `strategy_runs {id}`, `strategy_pause/resume/delete {id}` | manage and audit |
+
+**Who runs the clock.** Strategies execute inside the MCP server while your host app is open. For 24/7 operation run the daemon on any always-on machine:
+
+```bash
+POTSWAP_STATE_DIR=~/.potswap SOLANA_KEYPAIR_PATH=~/.config/solana/id.json npx -y @potswap_io/mcp --daemon
+```
+
+State lives in `~/.potswap/strategies.json` (override with `POTSWAP_STATE_DIR`); a PID lock makes sure only one process trades. The first leg runs at creation; a window missed during downtime runs once, never as a burst.
+
+**Extra limits.** `POTSWAP_MAX_DAILY_SOL` (default `5`) caps the SOL-equivalent all strategies may spend per UTC day; `POTSWAP_MAX_STRATEGIES` (default `10`). After three consecutive failed legs a strategy pauses itself and tells you why. `POTSWAP_DRY_RUN=true` turns every leg into a logged quote.
+
+## Fees and rewards
+
+Each swap carries Potswap's 2.5% integrator fee via Jupiter's referral program; Jupiter keeps 20% of it, and 50% of what remains buys and burns POT each epoch. The fee basis is credited to the trading wallet as Season 1 points, split daily: 666,666 POT per epoch, by `fee^1.1`, capped at 10% per wallet. Points become POT tokens after the token launch; unlock 7 days after each epoch. Details: https://www.potswap.io
+
+## Development
+
+```bash
+cd mcp && npm i && npm test      # unit tests over the real MCP protocol (in-memory transport)
+npm run dev                       # run from source
+npm run sync-shared && npm run build
+```
+
+MIT © Potswap

package/dist/agentTools.d.ts

@@ -0,0 +1,44 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Connection } from '@solana/web3.js';
+import { type Config } from './config.js';
+import { type TradeContext } from './trade.js';
+import { type Rpc } from './transfer.js';
+/** Transaction-level RPC reads; injectable for tests. */
+export interface TxRpc {
+    getSignatureStatus(sig: string): Promise<{
+        confirmationStatus?: string;
+        err?: unknown;
+        slot?: number;
+    } | null>;
+    getParsedTransaction(sig: string): Promise<{
+        slot: number;
+        fee: number;
+        err: unknown;
+        preBalances: number[];
+        postBalances: number[];
+        accountKeys: string[];
+        preTokenBalances: {
+            mint: string;
+            owner?: string;
+            uiTokenAmount: {
+                uiAmount: number | null;
+            };
+        }[];
+        postTokenBalances: {
+            mint: string;
+            owner?: string;
+            uiTokenAmount: {
+                uiAmount: number | null;
+            };
+        }[];
+    } | null>;
+}
+export declare function txRpcFromConnection(conn: Connection): TxRpc;
+export interface AgentToolDeps {
+    trade: TradeContext;
+    config: Config;
+    rpc?: Rpc;
+    txRpc?: TxRpc;
+    schedulerActive?: () => boolean;
+}
+export declare function registerAgentTools(server: McpServer, deps: AgentToolDeps): void;

package/dist/agentTools.js

@@ -0,0 +1,179 @@
+import { Connection } from '@solana/web3.js';
+import { z } from 'zod';
+import { JITOSOL_MINT, MSOL_MINT, NO_WALLET, SOL_MINT } from './config.js';
+import { redact, redactValue } from './redact.js';
+import { createWallet } from './wallet.js';
+import { executeSwap } from './trade.js';
+import { executeTransfer, rpcFromConnection } from './transfer.js';
+import { mapSignatureStatus, normalizeHistory } from './history.js';
+import { computePositions } from './pnl.js';
+const ok = (data, summary) => ({ content: [{ type: 'text', text: redact(summary ?? JSON.stringify(data, null, 2)) }], structuredContent: redactValue(data) });
+const fail = (message, extra = {}) => ({ content: [{ type: 'text', text: redact(message) }], structuredContent: redactValue({ error: message, ...extra }), isError: true });
+const MINT = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/);
+export function txRpcFromConnection(conn) {
+    return {
+        async getSignatureStatus(sig) { const r = await conn.getSignatureStatuses([sig], { searchTransactionHistory: true }); const s = r.value[0]; return s ? { confirmationStatus: s.confirmationStatus ?? undefined, err: s.err, slot: s.slot } : null; },
+        async getParsedTransaction(sig) {
+            const t = await conn.getParsedTransaction(sig, { maxSupportedTransactionVersion: 0, commitment: 'confirmed' });
+            if (!t?.meta)
+                return null;
+            return {
+                slot: t.slot, fee: t.meta.fee, err: t.meta.err, preBalances: t.meta.preBalances, postBalances: t.meta.postBalances,
+                accountKeys: t.transaction.message.accountKeys.map((k) => k.pubkey.toBase58()),
+                preTokenBalances: (t.meta.preTokenBalances ?? []).map((b) => ({ mint: b.mint, owner: b.owner, uiTokenAmount: { uiAmount: b.uiTokenAmount.uiAmount } })),
+                postTokenBalances: (t.meta.postTokenBalances ?? []).map((b) => ({ mint: b.mint, owner: b.owner, uiTokenAmount: { uiAmount: b.uiTokenAmount.uiAmount } })),
+            };
+        },
+    };
+}
+export function registerAgentTools(server, deps) {
+    const { trade, config } = deps;
+    const api = trade.api;
+    const conn = () => new Connection(config.rpcUrl, 'confirmed');
+    const rpc = deps.rpc ?? rpcFromConnection(conn());
+    const txRpc = deps.txRpc ?? txRpcFromConnection(conn());
+    const walletOr = (w) => w ?? trade.signer?.publicKey ?? null;
+    server.registerTool('wallet_create', {
+        title: 'Create an agent wallet',
+        description: 'Generates a new keypair and stores it in the Potswap state directory (0600). Only when no wallet is configured. Returns the public key; the secret key is never shown. Back up the file.',
+        inputSchema: { confirm: z.boolean().default(false) },
+    }, async ({ confirm }) => {
+        if (trade.signer)
+            return fail(`A wallet is already configured (${trade.signer.publicKey}). Nothing was created.`);
+        if (!confirm)
+            return fail('Set confirm=true to create a wallet. Nothing was created.');
+        try {
+            const { signer, file } = createWallet(config.stateDir);
+            trade.signer = signer;
+            return ok({ publicKey: signer.publicKey, file, backup: 'Copy this file somewhere safe; it is the only copy of the secret key.' }, `Wallet created: ${signer.publicKey}\nSecret stored at ${file} (0600). Fund it with SOL to start; keep ≥ 0.01 SOL for fees.`);
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('get_wallet', {
+        title: 'Wallet, limits and status',
+        description: 'Public key, funding instructions, configured limits and allowlists, scheduler status.',
+        inputSchema: {},
+    }, async () => ok({
+        publicKey: trade.signer?.publicKey ?? null,
+        fund: trade.signer ? `Send SOL to ${trade.signer.publicKey}. Keep at least 0.01 SOL for network fees.` : NO_WALLET,
+        limits: { maxTradeSol: config.maxTradeSol, maxDailySol: config.maxDailySol, maxSlippageBps: config.maxSlippageBps, dryRun: config.dryRun },
+        allowedTokens: [...config.allowedTokens], allowedRecipients: [...config.allowedRecipients],
+        schedulerActive: !!deps.schedulerActive?.(), stateDir: config.stateDir, api: config.apiBase, rpc: config.rpcUrl.replace(/api-key=[^&]+/, 'api-key=***'),
+    }));
+    server.registerTool('transfer', {
+        title: 'Transfer SOL or a token (no Potswap fee)',
+        description: 'Sends SOL or an SPL token from the agent wallet. Requires confirm=true. Subject to POTSWAP_ALLOWED_RECIPIENTS, the per-trade cap and the SOL reserve. Every error states whether funds were debited.',
+        inputSchema: { to: z.string().min(32).max(44), mint: MINT.optional(), amount: z.number().positive(), confirm: z.boolean().default(false) },
+    }, async (a) => {
+        const out = await executeTransfer({
+            config, signer: trade.signer, rpc, balances: trade.balances, prices: (m) => api.prices(m),
+            decimalsOf: async (m) => (await api.token(m)).decimals,
+        }, { to: a.to, mint: a.mint, amount: a.amount, confirm: a.confirm });
+        if (out.kind === 'ok')
+            return ok({ signature: out.signature, explorerUrl: out.explorerUrl }, `${out.summary}. ${out.explorerUrl}`);
+        if (out.kind === 'quote-only' || out.kind === 'dry-run')
+            return ok({ [out.kind === 'dry-run' ? 'dryRun' : 'confirmRequired']: true }, out.summary);
+        return fail(out.message);
+    });
+    server.registerTool('get_transaction', {
+        title: 'Transaction status',
+        description: 'Status (processed / confirmed / finalized / failed / not found), slot, fee and the wallet balance changes for a signature.',
+        inputSchema: { signature: z.string().min(64).max(90), wallet: MINT.optional() },
+    }, async ({ signature, wallet }) => {
+        try {
+            const st = await txRpc.getSignatureStatus(signature);
+            const status = mapSignatureStatus(st);
+            const data = { signature, status, slot: st?.slot ?? null, explorerUrl: `https://solscan.io/tx/${signature}` };
+            if (status === 'confirmed' || status === 'finalized' || status === 'failed') {
+                const t = await txRpc.getParsedTransaction(signature);
+                if (t) {
+                    const w = walletOr(wallet);
+                    const idx = w ? t.accountKeys.indexOf(w) : -1;
+                    data.feeSol = t.fee / 1e9;
+                    data.error = t.err ?? null;
+                    if (idx >= 0)
+                        data.solChange = (t.postBalances[idx] - t.preBalances[idx]) / 1e9;
+                    if (w) {
+                        const pre = Object.fromEntries(t.preTokenBalances.filter((b) => b.owner === w).map((b) => [b.mint, b.uiTokenAmount.uiAmount ?? 0]));
+                        const post = Object.fromEntries(t.postTokenBalances.filter((b) => b.owner === w).map((b) => [b.mint, b.uiTokenAmount.uiAmount ?? 0]));
+                        const mints = new Set([...Object.keys(pre), ...Object.keys(post)]);
+                        data.tokenChanges = [...mints].map((m) => ({ mint: m, change: (post[m] ?? 0) - (pre[m] ?? 0) })).filter((c) => c.change !== 0);
+                    }
+                }
+            }
+            return ok(data, `${signature.slice(0, 8)}… ${status}${data.solChange !== undefined ? ` · SOL ${data.solChange >= 0 ? '+' : ''}${data.solChange}` : ''}`);
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('get_history', {
+        title: 'Recent transactions',
+        description: 'Parsed recent transactions for a wallet (swaps, transfers, other), newest first.',
+        inputSchema: { wallet: MINT.optional(), limit: z.number().int().min(1).max(100).default(25) },
+    }, async ({ wallet, limit }) => {
+        const w = walletOr(wallet);
+        if (!w)
+            return fail(NO_WALLET);
+        try {
+            const raw = await api.history(w, limit);
+            const items = normalizeHistory(raw, w);
+            return ok({ wallet: w, items }, items.map((i) => `${i.time} ${i.kind}${i.failed ? ' (failed)' : ''}: ${i.kind === 'swap' ? `${i.inAmount} ${short(i.inMint)} → ${i.outAmount} ${short(i.outMint)}` : i.kind === 'transfer' ? `${i.direction} ${i.amount} ${short(i.mint)} ${i.direction === 'out' ? 'to' : 'from'} ${i.counterparty}` : i.source ?? ''} ${i.signature.slice(0, 8)}…`).join('\n') || 'No transactions yet.');
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('get_price_history', {
+        title: 'Price history (OHLCV)',
+        description: 'Candles for a token from its top pool. Timeframes: 1m, 5m, 15m, 1h, 4h, 1d.',
+        inputSchema: { mint: MINT, timeframe: z.enum(['1m', '5m', '15m', '1h', '4h', '1d']).default('15m'), limit: z.number().int().min(1).max(1000).default(100) },
+    }, async ({ mint, timeframe, limit }) => {
+        try {
+            const d = await api.ohlcv(mint, timeframe, limit);
+            const c = d.candles;
+            return ok(d, c.length ? `${c.length} ${timeframe} candles · last close ${c[c.length - 1].close} · range ${Math.min(...c.map((x) => x.low))}–${Math.max(...c.map((x) => x.high))}` : d.reason ?? 'No candles');
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    const stakeTool = (name, title, description, from, to) => server.registerTool(name, { title, description, inputSchema: { amount: z.number().positive(), provider: z.enum(['jito', 'marinade']).default('jito'), confirm: z.boolean().default(false), maxSlippageBps: z.number().int().min(1).max(5000).optional() } }, async (a) => {
+        const out = await executeSwap(trade, { inputMint: from(a.provider), outputMint: to(a.provider), amount: a.amount, slippageBps: a.maxSlippageBps, confirm: a.confirm });
+        switch (out.kind) {
+            case 'no-wallet': return fail(out.message);
+            case 'refused': return fail(out.message, { quote: out.quote });
+            case 'quote-only': return ok({ confirmRequired: true, quote: out.quote }, `Quote only (confirm=true to execute): ${a.amount} ${out.quote.inputSymbol} → ${out.quote.outAmount} ${out.quote.outputSymbol}`);
+            case 'dry-run': return ok({ dryRun: true, quote: out.quote }, `DRY RUN: ${a.amount} ${out.quote.inputSymbol} → ${out.quote.outAmount} ${out.quote.outputSymbol}`);
+            case 'failed': return fail(out.message, { signature: out.signature });
+            case 'ok': return ok({ ...out.result }, `${name === 'stake_sol' ? 'Staked' : 'Unstaked'}: ${a.amount} ${out.result.inputSymbol} → ${out.result.outAmount} ${out.result.outputSymbol}. ${out.result.explorerUrl}`);
+        }
+    });
+    const lst = (p) => (p === 'jito' ? JITOSOL_MINT : MSOL_MINT);
+    stakeTool('stake_sol', 'Liquid-stake SOL', 'Swaps SOL into jitoSOL (Jito) or mSOL (Marinade) at the best route. Normal fee and points apply. Requires confirm=true.', () => SOL_MINT, lst);
+    stakeTool('unstake_sol', 'Unstake liquid SOL', 'Swaps jitoSOL or mSOL back into SOL at the best route. Normal fee and points apply. Requires confirm=true.', lst, () => SOL_MINT);
+    // Upgraded positions with PnL (P13.7): replaces the basic tool registered by the core server.
+    server.registerTool('get_positions', {
+        title: 'Positions with PnL',
+        description: 'Token holdings with USD value, average cost, unrealised and realised PnL from the wallet\'s swap history.',
+        inputSchema: { wallet: MINT.optional() },
+    }, async ({ wallet }) => {
+        const w = walletOr(wallet);
+        if (!w)
+            return fail(NO_WALLET);
+        try {
+            const [bal, raw] = await Promise.all([trade.balances(w), api.history(w, 100).catch(() => [])]);
+            const history = normalizeHistory(raw, w);
+            const mints = [...new Set([...Object.keys(bal), ...history.flatMap((h) => [h.inMint, h.outMint]).filter((m) => !!m)])].slice(0, 50);
+            const prices = await api.prices(mints).catch(() => ({}));
+            const positions = computePositions(history, bal, prices);
+            return ok({ wallet: w, sol: bal[SOL_MINT] ?? 0, solUsd: prices[SOL_MINT] ? (bal[SOL_MINT] ?? 0) * prices[SOL_MINT] : undefined, positions }, positions.map((p) => `${short(p.mint)}: ${p.amount}${p.valueUsd !== undefined ? ` ($${p.valueUsd.toFixed(2)})` : ''}${p.unrealisedUsd !== undefined ? ` unrealised ${p.unrealisedUsd >= 0 ? '+' : ''}$${p.unrealisedUsd.toFixed(2)}` : ''}${p.realisedUsd ? ` realised ${p.realisedUsd >= 0 ? '+' : ''}$${p.realisedUsd.toFixed(2)}` : ''}`).join('\n') || 'No positions.');
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+}
+const short = (m) => (!m ? '?' : m === SOL_MINT ? 'SOL' : m === JITOSOL_MINT ? 'jitoSOL' : m === MSOL_MINT ? 'mSOL' : m.slice(0, 4) + '…');

package/dist/api.d.ts

@@ -1,5 +1,6 @@
 import type { ExecuteResponse, OrderResponse, Token } from './shared/lib-types.js';
 import type { TerminalToken } from './shared/types.js';
+import { type FeeSchedule } from './shared/fee.js';
 export type FetchFn = typeof fetch;
 export declare class ApiError extends Error {
     status: number;
@@ -8,6 +9,8 @@ export declare class ApiError extends Error {
 export interface PublicConfig {
     referralAccount: string | null;
     referralFeeBps: number;
+    fee: FeeSchedule;
+    burnShare: number;
     seasonStart: string | null;
     pointsEnabled: boolean;
 }
@@ -25,6 +28,7 @@ export declare class PotswapApi {
         amount: string;
         taker?: string;
         slippageBps?: number;
+        feeBps?: number;
     }): Promise<OrderResponse>;
     execute(signedTransaction: string, requestId: string): Promise<ExecuteResponse>;
     searchTokens(query: string): Promise<Token[]>;
@@ -33,5 +37,22 @@ export declare class PotswapApi {
     list(kind: string): Promise<TerminalToken[]>;
     terminalToken(mint: string): Promise<TerminalToken>;
     points(wallet: string): Promise<Record<string, unknown>>;
+    history(wallet: string, limit?: number): Promise<import("./history.js").HeliusTx[]>;
+    ohlcv(mint: string, tf: string, limit?: number): Promise<{
+        mint: string;
+        pool: {
+            id: string;
+            name: string;
+        } | null;
+        candles: {
+            time: number;
+            open: number;
+            high: number;
+            low: number;
+            close: number;
+            volume: number;
+        }[];
+        reason?: string;
+    }>;
     leaderboard(): Promise<Record<string, unknown>>;
 }

package/dist/api.js

@@ -1,3 +1,4 @@
+import { DEFAULT_FEE_SCHEDULE, parseFeeSchedule } from './shared/fee.js';
 export class ApiError extends Error {
     status;
     constructor(status, message) { super(message); this.status = status; }
@@ -36,10 +37,11 @@ export class PotswapApi {
             return this.configCache.value;
         let value;
         try {
-            value = await this.req('/api/config');
+            const raw = await this.req('/api/config');
+            value = { referralAccount: raw.referralAccount ?? null, referralFeeBps: raw.referralFeeBps ?? 0, fee: parseFeeSchedule(raw.fee), burnShare: raw.burnShare ?? 0.5, seasonStart: raw.seasonStart ?? null, pointsEnabled: !!raw.pointsEnabled };
         }
         catch {
-            value = { referralAccount: null, referralFeeBps: 0, seasonStart: null, pointsEnabled: false };
+            value = { referralAccount: null, referralFeeBps: 0, fee: DEFAULT_FEE_SCHEDULE, burnShare: 0.5, seasonStart: null, pointsEnabled: false };
         }
         this.configCache = { value, at: Date.now() };
         return value;
@@ -53,7 +55,7 @@ export class PotswapApi {
             q.set('slippageBps', String(p.slippageBps));
         if (cfg.referralAccount) {
             q.set('referralAccount', cfg.referralAccount);
-            q.set('referralFee', String(cfg.referralFeeBps));
+            q.set('referralFee', String(p.feeBps ?? cfg.fee.standardBps));
         }
         return this.req(`/api/jup/swap/v2/order?${q}`);
     }
@@ -85,5 +87,7 @@ export class PotswapApi {
     list(kind) { return this.req(`/api/terminal/list/${kind}`); }
     terminalToken(mint) { return this.req(`/api/terminal/token/${mint}`); }
     points(wallet) { return this.req(`/api/points/${wallet}`); }
+    history(wallet, limit = 25) { return this.req(`/api/history/${wallet}?limit=${limit}`); }
+    ohlcv(mint, tf, limit = 100) { return this.req(`/api/terminal/ohlcv/${mint}?tf=${tf}&limit=${limit}`); }
     leaderboard() { return this.req('/api/leaderboard'); }
 }

package/dist/config.d.ts

@@ -2,18 +2,31 @@ export interface Config {
     apiBase: string;
     rpcUrl: string;
     maxTradeSol: number;
+    /** SOL-equivalent all strategies together may spend per UTC day (PRD P11.6). */
+    maxDailySol: number;
     maxSlippageBps: number;
     dryRun: boolean;
     privateKey?: string;
     keypairPath?: string;
+    /** Where strategies, run logs and a created wallet live. */
+    stateDir: string;
+    /** When non-empty, swaps/strategies/staking may only touch these mints (PRD P13.4). */
+    allowedTokens: Set<string>;
+    /** When non-empty, `transfer` may only send to these addresses (PRD P13.3). */
+    allowedRecipients: Set<string>;
 }
 export declare const DEFAULTS: {
     apiBase: string;
     maxTradeSol: number;
+    maxDailySol: number;
     maxSlippageBps: number;
     solReserve: number;
 };
 export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
 export declare const SOL_MINT = "So11111111111111111111111111111111111111112";
 export declare const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
-export declare const NO_WALLET = "Wallet not configured. Set SOLANA_PRIVATE_KEY or SOLANA_KEYPAIR_PATH. No funds were debited.";
+export declare const JITOSOL_MINT = "J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn";
+export declare const MSOL_MINT = "mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So";
+export declare const NO_WALLET = "Wallet not configured. Set SOLANA_PRIVATE_KEY or SOLANA_KEYPAIR_PATH, or run wallet_create. No funds were debited.";
+export declare const TOKEN_NOT_ALLOWED = "Token not in POTSWAP_ALLOWED_TOKENS. No funds were debited.";
+export declare const RECIPIENT_NOT_ALLOWED = "Recipient not in POTSWAP_ALLOWED_RECIPIENTS. No funds were debited.";

package/dist/config.js

@@ -1,9 +1,14 @@
+// PRD P10 / P13 — configuration from environment variables.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 export const DEFAULTS = {
     apiBase: 'https://www.potswap.io',
     maxTradeSol: 1,
+    maxDailySol: 5,
     maxSlippageBps: 300,
     solReserve: 0.01,
 };
+const list = (v) => new Set((v ?? '').split(',').map((s) => s.trim()).filter(Boolean));
 export function loadConfig(env = process.env) {
     const apiBase = (env.POTSWAP_API || DEFAULTS.apiBase).replace(/\/$/, '');
     const num = (v, d) => { const n = Number(v); return v !== undefined && v !== '' && Number.isFinite(n) && n > 0 ? n : d; };
@@ -11,12 +16,20 @@ export function loadConfig(env = process.env) {
         apiBase,
         rpcUrl: env.SOLANA_RPC_URL || `${apiBase}/api/rpc`,
         maxTradeSol: num(env.POTSWAP_MAX_TRADE_SOL, DEFAULTS.maxTradeSol),
+        maxDailySol: num(env.POTSWAP_MAX_DAILY_SOL, DEFAULTS.maxDailySol),
         maxSlippageBps: num(env.POTSWAP_MAX_SLIPPAGE_BPS, DEFAULTS.maxSlippageBps),
         dryRun: /^(1|true|yes)$/i.test(env.POTSWAP_DRY_RUN ?? ''),
         privateKey: env.SOLANA_PRIVATE_KEY || undefined,
         keypairPath: env.SOLANA_KEYPAIR_PATH || undefined,
+        stateDir: env.POTSWAP_STATE_DIR || join(homedir(), '.potswap'),
+        allowedTokens: list(env.POTSWAP_ALLOWED_TOKENS),
+        allowedRecipients: list(env.POTSWAP_ALLOWED_RECIPIENTS),
     };
 }
 export const SOL_MINT = 'So11111111111111111111111111111111111111112';
 export const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
-export const NO_WALLET = 'Wallet not configured. Set SOLANA_PRIVATE_KEY or SOLANA_KEYPAIR_PATH. No funds were debited.';
+export const JITOSOL_MINT = 'J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn';
+export const MSOL_MINT = 'mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So';
+export const NO_WALLET = 'Wallet not configured. Set SOLANA_PRIVATE_KEY or SOLANA_KEYPAIR_PATH, or run wallet_create. No funds were debited.';
+export const TOKEN_NOT_ALLOWED = 'Token not in POTSWAP_ALLOWED_TOKENS. No funds were debited.';
+export const RECIPIENT_NOT_ALLOWED = 'Recipient not in POTSWAP_ALLOWED_RECIPIENTS. No funds were debited.';