@potswap_io/mcp 0.2.0 → 0.3.0

package/README.md

@@ -52,12 +52,15 @@ Without a key the server still runs in read-only mode (search, quotes, trending,
 |---|---|---|
 | `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 strategies and run logs are stored |
-| `POTSWAP_DRY_RUN` | `false` | `true` = `swap` never signs; returns what it would have done |
+| `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.
@@ -72,13 +75,27 @@ Use a dedicated agent wallet with only the funds you want the agent to control.
 | `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_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
+## 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).
 
@@ -87,6 +104,7 @@ Standing orders that keep running without you. Every leg is an ordinary Potswap
 | `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:

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

@@ -37,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

@@ -87,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

@@ -8,6 +8,12 @@ export interface Config {
     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;
@@ -19,4 +25,8 @@ export declare const DEFAULTS: {
 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,3 +1,6 @@
+// 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,
@@ -5,6 +8,7 @@ export const DEFAULTS = {
     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; };
@@ -17,8 +21,15 @@ export function loadConfig(env = process.env) {
         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.';

package/dist/history.d.ts

@@ -0,0 +1,72 @@
+export interface HeliusTx {
+    signature: string;
+    timestamp: number;
+    type?: string;
+    source?: string;
+    fee?: number;
+    feePayer?: string;
+    transactionError?: unknown;
+    nativeTransfers?: {
+        fromUserAccount?: string;
+        toUserAccount?: string;
+        amount?: number;
+    }[];
+    tokenTransfers?: {
+        fromUserAccount?: string;
+        toUserAccount?: string;
+        tokenAmount?: number;
+        mint?: string;
+    }[];
+    events?: {
+        swap?: {
+            nativeInput?: {
+                account: string;
+                amount: string;
+            } | null;
+            nativeOutput?: {
+                account: string;
+                amount: string;
+            } | null;
+            tokenInputs?: {
+                userAccount: string;
+                mint: string;
+                rawTokenAmount: {
+                    tokenAmount: string;
+                    decimals: number;
+                };
+            }[];
+            tokenOutputs?: {
+                userAccount: string;
+                mint: string;
+                rawTokenAmount: {
+                    tokenAmount: string;
+                    decimals: number;
+                };
+            }[];
+        };
+    };
+}
+export declare const SOL = "So11111111111111111111111111111111111111112";
+export interface HistoryItem {
+    signature: string;
+    time: string;
+    kind: 'swap' | 'transfer' | 'other';
+    source?: string;
+    feeSol: number;
+    failed: boolean;
+    /** For swaps: what the wallet gave and got. For transfers: amount and direction. */
+    inMint?: string;
+    inAmount?: number;
+    outMint?: string;
+    outAmount?: number;
+    direction?: 'in' | 'out';
+    counterparty?: string;
+    mint?: string;
+    amount?: number;
+}
+export declare function normalizeHistory(txs: HeliusTx[], wallet: string): HistoryItem[];
+export type TxStatus = 'not found' | 'processed' | 'confirmed' | 'finalized' | 'failed';
+export declare function mapSignatureStatus(s: {
+    confirmationStatus?: string;
+    err?: unknown;
+} | null): TxStatus;

package/dist/history.js

@@ -0,0 +1,53 @@
+export const SOL = 'So11111111111111111111111111111111111111112';
+export function normalizeHistory(txs, wallet) {
+    return txs.map((t) => {
+        const base = { signature: t.signature, time: new Date((t.timestamp ?? 0) * 1000).toISOString(), kind: 'other', source: t.source, feeSol: (t.fee ?? 0) / 1e9, failed: !!t.transactionError };
+        const sw = t.events?.swap;
+        if (sw) {
+            // Determine what this wallet put in and took out.
+            let inMint, inAmount = 0, outMint, outAmount = 0;
+            if (sw.nativeInput && sw.nativeInput.account === wallet) {
+                inMint = SOL;
+                inAmount = Number(sw.nativeInput.amount) / 1e9;
+            }
+            if (sw.nativeOutput && sw.nativeOutput.account === wallet) {
+                outMint = SOL;
+                outAmount = Number(sw.nativeOutput.amount) / 1e9;
+            }
+            for (const i of sw.tokenInputs ?? [])
+                if (i.userAccount === wallet) {
+                    inMint = i.mint;
+                    inAmount += Number(i.rawTokenAmount.tokenAmount) / 10 ** i.rawTokenAmount.decimals;
+                }
+            for (const o of sw.tokenOutputs ?? [])
+                if (o.userAccount === wallet) {
+                    outMint = o.mint;
+                    outAmount += Number(o.rawTokenAmount.tokenAmount) / 10 ** o.rawTokenAmount.decimals;
+                }
+            if (inMint || outMint)
+                return { ...base, kind: 'swap', inMint, inAmount, outMint, outAmount };
+        }
+        const tt = (t.tokenTransfers ?? []).find((x) => x.fromUserAccount === wallet || x.toUserAccount === wallet);
+        if (tt && tt.mint && tt.tokenAmount) {
+            const out = tt.fromUserAccount === wallet;
+            return { ...base, kind: 'transfer', direction: out ? 'out' : 'in', counterparty: out ? tt.toUserAccount : tt.fromUserAccount, mint: tt.mint, amount: tt.tokenAmount };
+        }
+        const nt = (t.nativeTransfers ?? []).find((x) => (x.fromUserAccount === wallet || x.toUserAccount === wallet) && (x.amount ?? 0) > 0);
+        if (nt) {
+            const out = nt.fromUserAccount === wallet;
+            return { ...base, kind: 'transfer', direction: out ? 'out' : 'in', counterparty: out ? nt.toUserAccount : nt.fromUserAccount, mint: SOL, amount: (nt.amount ?? 0) / 1e9 };
+        }
+        return base;
+    });
+}
+export function mapSignatureStatus(s) {
+    if (!s)
+        return 'not found';
+    if (s.err)
+        return 'failed';
+    if (s.confirmationStatus === 'finalized')
+        return 'finalized';
+    if (s.confirmationStatus === 'confirmed')
+        return 'confirmed';
+    return 'processed';
+}

package/dist/pnl.d.ts

@@ -0,0 +1,16 @@
+import type { HistoryItem } from './history.js';
+export interface Position {
+    mint: string;
+    amount: number;
+    avgCostUsd?: number;
+    costBasisUsd?: number;
+    valueUsd?: number;
+    unrealisedUsd?: number;
+    realisedUsd: number;
+}
+/**
+ * Walks swaps oldest→newest. A swap "buys" its outMint at (inAmount × price(inMint at the time)) and
+ * "sells" its inMint. Price history is approximated with current prices unless the item carries `inUsd`.
+ * Good enough for an agent dashboard; exact fills come from the on-chain record.
+ */
+export declare function computePositions(history: HistoryItem[], balances: Record<string, number>, prices: Record<string, number>, quoteMints?: Set<string>): Position[];

package/dist/pnl.js

@@ -0,0 +1,45 @@
+import { SOL } from './history.js';
+/**
+ * Walks swaps oldest→newest. A swap "buys" its outMint at (inAmount × price(inMint at the time)) and
+ * "sells" its inMint. Price history is approximated with current prices unless the item carries `inUsd`.
+ * Good enough for an agent dashboard; exact fills come from the on-chain record.
+ */
+export function computePositions(history, balances, prices, quoteMints = new Set([SOL])) {
+    const lots = {};
+    const items = [...history].filter((h) => h.kind === 'swap' && !h.failed).sort((a, b) => a.time.localeCompare(b.time));
+    for (const h of items) {
+        const inUsd = h.inUsd ?? (h.inMint && prices[h.inMint] ? (h.inAmount ?? 0) * prices[h.inMint] : undefined);
+        // sell side
+        if (h.inMint && !quoteMints.has(h.inMint) && h.inAmount) {
+            const l = (lots[h.inMint] ??= { amount: 0, cost: 0, realised: 0 });
+            const avg = l.amount > 0 ? l.cost / l.amount : 0;
+            const sold = Math.min(h.inAmount, l.amount);
+            const proceeds = h.outMint && prices[h.outMint] ? (h.outAmount ?? 0) * prices[h.outMint] : inUsd ?? 0;
+            l.realised += proceeds - sold * avg;
+            l.amount -= sold;
+            l.cost -= sold * avg;
+            if (l.amount < 1e-12) {
+                l.amount = 0;
+                l.cost = 0;
+            }
+        }
+        // buy side
+        if (h.outMint && !quoteMints.has(h.outMint) && h.outAmount && inUsd !== undefined) {
+            const l = (lots[h.outMint] ??= { amount: 0, cost: 0, realised: 0 });
+            l.amount += h.outAmount;
+            l.cost += inUsd;
+        }
+    }
+    const mints = new Set([...Object.keys(balances), ...Object.keys(lots)].filter((m) => !quoteMints.has(m)));
+    return [...mints].map((mint) => {
+        const amount = balances[mint] ?? 0;
+        const l = lots[mint];
+        const avg = l && l.amount > 0 ? l.cost / l.amount : undefined;
+        const price = prices[mint];
+        const value = price !== undefined ? amount * price : undefined;
+        return {
+            mint, amount, avgCostUsd: avg, costBasisUsd: avg !== undefined ? amount * avg : undefined, valueUsd: value,
+            unrealisedUsd: value !== undefined && avg !== undefined ? value - amount * avg : undefined, realisedUsd: l?.realised ?? 0,
+        };
+    }).filter((p) => p.amount > 0 || p.realisedUsd !== 0).sort((a, b) => (b.valueUsd ?? 0) - (a.valueUsd ?? 0));
+}

package/dist/runtime.js

@@ -2,15 +2,15 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { PotswapApi } from './api.js';
 import { loadSigner } from './wallet.js';
-import { FileStore, defaultStateDir } from './strategies/store.js';
+import { FileStore } from './strategies/store.js';
 import { acquireLock } from './strategies/lock.js';
 import { Scheduler } from './strategies/scheduler.js';
 export function createRuntime(config) {
-    const signer = loadSigner(config);
+    const signer = loadSigner({ privateKey: config.privateKey, keypairPath: config.keypairPath, stateDir: config.stateDir });
     const api = new PotswapApi(config.apiBase);
     const balances = rpcBalances(config.rpcUrl);
     const trade = { api, config, signer, balances };
-    const dir = defaultStateDir();
+    const dir = config.stateDir;
     const store = new FileStore(dir);
     const lock = acquireLock(dir);
     const scheduler = lock.acquired ? new Scheduler({ store, trade, maxDailySol: config.maxDailySol }) : null;

package/dist/server.d.ts

@@ -3,9 +3,11 @@ import { type FetchFn } from './api.js';
 import { SOL_MINT, USDC_MINT, type Config } from './config.js';
 import { type BalancesFn } from './trade.js';
 import { type Signer } from './wallet.js';
+import { type TxRpc } from './agentTools.js';
+import type { Rpc } from './transfer.js';
 import type { StrategyStore } from './strategies/store.js';
 import type { Scheduler } from './strategies/scheduler.js';
-export declare const VERSION = "0.2.0";
+export declare const VERSION = "0.3.0";
 export interface ServerDeps {
     config?: Config;
     signer?: Signer | null;
@@ -15,6 +17,9 @@ export interface ServerDeps {
     /** Strategy persistence and scheduler (P11); defaults are created from config when omitted. */
     strategyStore?: StrategyStore;
     scheduler?: Scheduler;
+    /** Transfer / transaction RPC surfaces; injectable for tests (P13). */
+    rpc?: Rpc;
+    txRpc?: TxRpc;
 }
 export declare function createServer(deps?: ServerDeps): McpServer;
 export { SOL_MINT, USDC_MINT };

package/dist/server.js

@@ -9,7 +9,8 @@ import { redact, redactValue } from './redact.js';
 import { loadSigner } from './wallet.js';
 import { riskBadges, riskLevel } from './shared/risk.js';
 import { registerStrategyTools } from './strategies/tools.js';
-export const VERSION = '0.2.0';
+import { registerAgentTools } from './agentTools.js';
+export const VERSION = '0.3.0';
 const ok = (data, summary) => ({
     content: [{ type: 'text', text: redact(summary ?? JSON.stringify(data, null, 2)) }], structuredContent: redactValue(data),
 });
@@ -18,7 +19,7 @@ const fail = (message, extra = {}) => ({
 });
 export function createServer(deps = {}) {
     const config = deps.config ?? loadConfig();
-    const signer = deps.signer !== undefined ? deps.signer : loadSigner(config);
+    const signer = deps.signer !== undefined ? deps.signer : loadSigner({ privateKey: config.privateKey, keypairPath: config.keypairPath, stateDir: config.stateDir });
     const api = new PotswapApi(config.apiBase, deps.fetchFn);
     const readBalances = deps.balances ?? rpcBalances(config.rpcUrl);
     const trade = { api, config, signer, balances: readBalances };
@@ -114,26 +115,6 @@ export function createServer(deps = {}) {
             return fail(msg(e));
         }
     });
-    server.registerTool('get_positions', {
-        title: 'Positions',
-        description: 'Token holdings with 24h price change (PnL arrives in a later version).',
-        inputSchema: { wallet: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).optional() },
-    }, async ({ wallet }) => {
-        const w = walletOr(wallet);
-        if (!w)
-            return fail(NO_WALLET);
-        try {
-            const bal = await readBalances(w);
-            const mints = Object.keys(bal).filter((m) => m !== SOL_MINT).slice(0, 20);
-            const infos = mints.length ? await api.searchTokens(mints.join(',')).catch(() => []) : [];
-            const prices = await api.prices([SOL_MINT, ...mints]).catch(() => ({}));
-            const positions = mints.map((m) => { const t = infos.find((x) => x.id === m); return { mint: m, symbol: t?.symbol ?? m.slice(0, 4), amount: bal[m], usd: prices[m] ? bal[m] * prices[m] : undefined }; });
-            return ok({ wallet: w, sol: bal[SOL_MINT] ?? 0, solUsd: prices[SOL_MINT] ? (bal[SOL_MINT] ?? 0) * prices[SOL_MINT] : undefined, positions });
-        }
-        catch (e) {
-            return fail(msg(e));
-        }
-    });
     server.registerTool('get_points', {
         title: 'POT points',
         description: "Season 1 points for a wallet: this epoch, all-time, POT allocated and claimable, next unlock. Defaults to the agent wallet.",
@@ -165,6 +146,7 @@ export function createServer(deps = {}) {
             return fail(msg(e));
         }
     });
+    registerAgentTools(server, { trade, config, rpc: deps.rpc, txRpc: deps.txRpc, schedulerActive: () => !!deps.scheduler?.active });
     registerStrategyTools(server, { trade, store: deps.strategyStore, scheduler: deps.scheduler });
     return server;
 }

package/dist/strategies/engine.d.ts

@@ -1,4 +1,4 @@
-import type { DcaStrategy, RebalanceStrategy, Run, Strategy, TpSlStrategy } from './types.js';
+import type { DcaStrategy, LimitStrategy, RebalanceStrategy, Run, Strategy, TpSlStrategy } from './types.js';
 export declare const SOL_MINT = "So11111111111111111111111111111111111111112";
 /** True when a time-based strategy should run at `now`. */
 export declare function isDue(s: Strategy, now: number): boolean;
@@ -36,5 +36,8 @@ export declare function tpslDecision(s: TpSlStrategy, price: number | undefined)
 /** SOL-equivalent spent by all strategies in the UTC day containing `now` (P11.6). */
 export declare function solSpentToday(runs: Run[], now: number): number;
 export declare function dcaLegFor(s: DcaStrategy): Leg;
+/** Limit order decision (P13.10): 'fill' when the condition holds, 'expired' past expiresAt, else null. */
+export declare function limitDecision(s: LimitStrategy, price: number | undefined, now: number): 'fill' | 'expired' | null;
+export declare function limitLegFor(s: LimitStrategy): Leg;
 export declare const MAX_CONSECUTIVE_FAILURES = 3;
 export declare function newId(prefix: string, now?: number): string;

package/dist/strategies/engine.js

@@ -92,6 +92,23 @@ export function solSpentToday(runs, now) {
 export function dcaLegFor(s) {
     return { inputMint: s.inputMint, outputMint: s.outputMint, amount: s.amountPerRun, reason: `DCA run ${s.runsDone + 1}${s.totalRuns ? `/${s.totalRuns}` : ''}` };
 }
+/** Limit order decision (P13.10): 'fill' when the condition holds, 'expired' past expiresAt, else null. */
+export function limitDecision(s, price, now) {
+    if (s.expiresAt && Date.parse(s.expiresAt) <= now)
+        return 'expired';
+    if (price === undefined || !(price > 0))
+        return null;
+    if (s.condition === 'below' && price <= s.triggerPriceUsd)
+        return 'fill';
+    if (s.condition === 'above' && price >= s.triggerPriceUsd)
+        return 'fill';
+    return null;
+}
+export function limitLegFor(s) {
+    return s.side === 'buy'
+        ? { inputMint: s.quoteMint, outputMint: s.mint, amount: s.amount, reason: `limit buy (${s.condition} ${s.triggerPriceUsd})` }
+        : { inputMint: s.mint, outputMint: s.quoteMint, amount: s.amount, reason: `limit sell (${s.condition} ${s.triggerPriceUsd})` };
+}
 export const MAX_CONSECUTIVE_FAILURES = 3;
 const round = (n) => Math.floor(n * 1e9) / 1e9;
 const pct = (n) => n.toFixed(1);

package/dist/strategies/scheduler.d.ts

@@ -30,6 +30,7 @@ export declare class Scheduler {
     private runDca;
     private runRebalance;
     private checkTpSl;
+    private checkLimit;
     private execute;
     private record;
     private bumpFailure;

package/dist/strategies/scheduler.js

@@ -1,6 +1,6 @@
 import { executeSwap } from '../trade.js';
 import { log } from '../redact.js';
-import { dcaIsComplete, dcaLegFor, isDue, MAX_CONSECUTIVE_FAILURES, nextRunAfter, newId, rebalancePlan, solSpentToday, tpslDecision } from './engine.js';
+import { dcaIsComplete, dcaLegFor, isDue, limitDecision, limitLegFor, MAX_CONSECUTIVE_FAILURES, nextRunAfter, newId, rebalancePlan, solSpentToday, tpslDecision } from './engine.js';
 export class Scheduler {
     store;
     trade;
@@ -59,6 +59,8 @@ export class Scheduler {
                 continue;
             if (s.kind === 'tpsl')
                 await this.checkTpSl(s);
+            else if (s.kind === 'limit')
+                await this.checkLimit(s);
             else if (isDue(s, now))
                 await (s.kind === 'dca' ? this.runDca(s) : this.runRebalance(s));
         }
@@ -137,6 +139,27 @@ export class Scheduler {
         if (out.kind === 'ok' || out.kind === 'dry-run')
             this.complete(s.id);
     }
+    // ---- Limit orders (P13.10)
+    async checkLimit(s) {
+        let price;
+        try {
+            price = (await this.trade.api.prices([s.mint]))[s.mint];
+        }
+        catch {
+            price = undefined;
+        }
+        const d = limitDecision(s, price, this.now());
+        if (d === 'expired') {
+            this.record(s, 'check', 'completed', 'Expired unfilled.');
+            this.complete(s.id);
+            return;
+        }
+        if (d !== 'fill')
+            return;
+        const out = await this.execute(s, limitLegFor(s));
+        if (out.kind === 'ok' || out.kind === 'dry-run')
+            this.complete(s.id);
+    }
     // ---- shared leg execution with caps, run log, failure counting (P11.6–P11.8, P11.13)
     async execute(s, leg) {
         const now = this.now();
@@ -205,7 +228,7 @@ export class Scheduler {
     advance(id) {
         this.store.update((st) => {
             const cur = st.strategies.find((x) => x.id === id);
-            if (cur && cur.status === 'active' && cur.kind !== 'tpsl')
+            if (cur && cur.status === 'active' && cur.kind !== 'tpsl' && cur.kind !== 'limit')
                 cur.nextRunAt = nextRunAfter(cur, this.now());
         });
     }

package/dist/strategies/tools.js

@@ -110,6 +110,25 @@ export function registerStrategyTools(server, deps) {
         const s = { ...base('tpsl', a.maxSlippageBps), kind: 'tpsl', mint: a.mint, sellPct: a.sellPct, exitMint: a.exitMint, entryPrice: entry, highWater: entry, takeProfitPct: a.takeProfitPct, stopLossPct: a.stopLossPct, trailingPct: a.trailingPct, nextRunAt: null };
         return created(s, `TP/SL created at entry ${entry}: ${[a.takeProfitPct && `TP +${a.takeProfitPct}%`, a.stopLossPct && `SL −${a.stopLossPct}%`, a.trailingPct && `trailing ${a.trailingPct}%`].filter(Boolean).join(', ')}, sells ${a.sellPct}%.`);
     });
+    server.registerTool('limit_order_create', {
+        title: 'Create a limit order (price-triggered swap)',
+        description: 'Buy or sell a token when its USD price crosses a level. Runs through the strategy scheduler (needs this host open or the daemon). Fills once at the best route with the normal fee and points, then completes.',
+        inputSchema: {
+            side: z.enum(['buy', 'sell']), mint: MINT, quoteMint: MINT.default(SOL_MINT),
+            amount: z.number().positive().describe('Input amount in UI units: quote (SOL) amount for buys, token amount for sells'),
+            triggerPriceUsd: z.number().positive(), condition: z.enum(['above', 'below']),
+            expiresAt: z.string().datetime().optional(), maxSlippageBps: z.number().int().min(1).max(5000).optional(),
+            confirm: z.boolean().default(false),
+        },
+    }, async (a) => {
+        const g = guard(a.confirm);
+        if (g)
+            return g;
+        if (a.mint === a.quoteMint)
+            return fail('mint and quoteMint must differ. Nothing was created.');
+        const s = { ...base('limit', a.maxSlippageBps), kind: 'limit', side: a.side, mint: a.mint, quoteMint: a.quoteMint, amount: a.amount, triggerPriceUsd: a.triggerPriceUsd, condition: a.condition, expiresAt: a.expiresAt, nextRunAt: null };
+        return created(s, `Limit ${a.side} created: ${a.amount} ${a.side === 'buy' ? 'quote' : 'tokens'} when price ${a.condition} $${a.triggerPriceUsd}${a.expiresAt ? ` until ${a.expiresAt}` : ''}.`);
+    });
     server.registerTool('strategy_list', { title: 'List strategies', description: 'All strategies with status, next run, totals and last result.', inputSchema: {} }, async () => {
         const st = store.load();
         const rows = st.strategies.map((s) => ({ ...s, lastRun: runsOf(st, s.id, 1)[0] ?? null }));
@@ -118,7 +137,7 @@ export function registerStrategyTools(server, deps) {
     const byId = { id: z.string().min(3) };
     server.registerTool('strategy_pause', { title: 'Pause a strategy', description: 'Stops future legs; keeps history.', inputSchema: byId }, async ({ id }) => mutate(id, (s) => { s.status = 'paused'; s.pausedReason = 'paused by user'; s.nextRunAt = null; }));
     server.registerTool('strategy_resume', { title: 'Resume a strategy', description: 'Re-activates a paused strategy; the next run is scheduled from now.', inputSchema: byId }, async ({ id }) => mutate(id, (s) => { if (s.status === 'completed')
-        throw new Error('Completed strategies cannot be resumed; create a new one.'); s.status = 'active'; s.pausedReason = undefined; s.consecutiveFailures = 0; s.nextRunAt = s.kind === 'tpsl' ? null : nextRunAfter(s, now()); }));
+        throw new Error('Completed strategies cannot be resumed; create a new one.'); s.status = 'active'; s.pausedReason = undefined; s.consecutiveFailures = 0; s.nextRunAt = s.kind === 'tpsl' || s.kind === 'limit' ? null : nextRunAfter(s, now()); }));
     server.registerTool('strategy_delete', { title: 'Delete a strategy', description: 'Removes the strategy; its run history is kept.', inputSchema: byId }, async ({ id }) => {
         const existed = store.update((st) => { const n = st.strategies.length; st.strategies = st.strategies.filter((s) => s.id !== id); return n !== st.strategies.length; });
         return existed ? ok({ deleted: id }, `Deleted ${id}.`) : fail(`No strategy ${id}.`);

package/dist/strategies/types.d.ts

@@ -41,7 +41,17 @@ export interface TpSlStrategy extends Base {
     stopLossPct?: number;
     trailingPct?: number;
 }
-export type Strategy = DcaStrategy | RebalanceStrategy | TpSlStrategy;
+export interface LimitStrategy extends Base {
+    kind: 'limit';
+    side: 'buy' | 'sell';
+    mint: string;
+    quoteMint: string;
+    amount: number;
+    triggerPriceUsd: number;
+    condition: 'above' | 'below';
+    expiresAt?: string;
+}
+export type Strategy = DcaStrategy | RebalanceStrategy | TpSlStrategy | LimitStrategy;
 export type RunOutcome = 'ok' | 'skipped' | 'failed' | 'dry-run' | 'no-op' | 'completed';
 export interface Run {
     id: string;

package/dist/trade.js

@@ -1,7 +1,7 @@
 // Swap execution shared by the `swap` tool (P10) and the strategy scheduler (P11).
 // One path: quote → limits → fresh order as taker → local signature → execute.
 import { VersionedTransaction } from '@solana/web3.js';
-import { NO_WALLET, SOL_MINT } from './config.js';
+import { NO_WALLET, SOL_MINT, TOKEN_NOT_ALLOWED } from './config.js';
 import { checkLimits } from './limits.js';
 import { explorer, fromRaw, toRaw } from './format.js';
 import { describeOrderError, friendlyError } from './shared/errors.js';
@@ -31,6 +31,9 @@ export async function executeSwap(ctx, a) {
     const { api, config, signer } = ctx;
     if (!signer)
         return { kind: 'no-wallet', message: NO_WALLET };
+    if (config.allowedTokens.size && (!config.allowedTokens.has(a.inputMint) || !config.allowedTokens.has(a.outputMint))) {
+        return { kind: 'failed', message: TOKEN_NOT_ALLOWED };
+    }
     try {
         const quote = await buildQuote(api, a);
         const prices = await api.prices([SOL_MINT, a.inputMint]).catch(() => ({}));

package/dist/transfer.d.ts

@@ -0,0 +1,49 @@
+import { Connection, type Commitment } from '@solana/web3.js';
+import { type Config } from './config.js';
+import type { Signer } from './wallet.js';
+/** Minimal RPC surface so tests can mock it. */
+export interface Rpc {
+    getLatestBlockhash(commitment?: Commitment): Promise<{
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+    getAccountOwner(address: string): Promise<string | null>;
+    sendRawTransaction(raw: Uint8Array): Promise<string>;
+    confirmTransaction(sig: string, blockhash: string, lastValidBlockHeight: number): Promise<{
+        err: unknown | null;
+    }>;
+}
+export declare function rpcFromConnection(conn: Connection): Rpc;
+export interface TransferArgs {
+    to: string;
+    mint?: string;
+    amount: number;
+    decimals?: number;
+    confirm: boolean;
+}
+export type TransferOutcome = {
+    kind: 'no-wallet' | 'refused' | 'failed';
+    message: string;
+} | {
+    kind: 'quote-only';
+    summary: string;
+} | {
+    kind: 'dry-run';
+    summary: string;
+} | {
+    kind: 'ok';
+    signature: string;
+    explorerUrl: string;
+    summary: string;
+};
+export interface TransferContext {
+    config: Config;
+    signer: Signer | null;
+    rpc: Rpc;
+    balances: (wallet: string) => Promise<Record<string, number>>;
+    prices: (mints: string[]) => Promise<Record<string, number>>;
+    decimalsOf: (mint: string) => Promise<number>;
+    /** Program that owns the mint (Token vs Token-2022); defaults to the classic Token program. */
+    getMintOwner?: (mint: string) => Promise<string | null>;
+}
+export declare function executeTransfer(ctx: TransferContext, a: TransferArgs): Promise<TransferOutcome>;

package/dist/transfer.js

@@ -0,0 +1,86 @@
+// PRD P13.2/P13.3 — SOL and SPL transfers built locally, no Potswap fee, recipient allowlist + caps.
+import { Connection, PublicKey, SystemProgram, Transaction } from '@solana/web3.js';
+import { createAssociatedTokenAccountIdempotentInstruction, createTransferCheckedInstruction, getAssociatedTokenAddressSync, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '@solana/spl-token';
+import { DEFAULTS, NO_WALLET, RECIPIENT_NOT_ALLOWED, SOL_MINT } from './config.js';
+import { toRaw } from './format.js';
+export function rpcFromConnection(conn) {
+    return {
+        getLatestBlockhash: (c) => conn.getLatestBlockhash(c ?? 'confirmed'),
+        getAccountOwner: async (a) => { const info = await conn.getAccountInfo(new PublicKey(a)); return info ? info.owner.toBase58() : null; },
+        sendRawTransaction: (raw) => conn.sendRawTransaction(raw, { skipPreflight: false, maxRetries: 3 }),
+        confirmTransaction: async (signature, blockhash, lastValidBlockHeight) => { const r = await conn.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, 'confirmed'); return { err: r.value.err }; },
+    };
+}
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+export async function executeTransfer(ctx, a) {
+    const { config, signer } = ctx;
+    if (!signer)
+        return { kind: 'no-wallet', message: NO_WALLET };
+    if (!BASE58.test(a.to))
+        return { kind: 'refused', message: 'Invalid recipient address. No funds were debited.' };
+    if (config.allowedRecipients.size && !config.allowedRecipients.has(a.to))
+        return { kind: 'refused', message: RECIPIENT_NOT_ALLOWED };
+    if (!(a.amount > 0))
+        return { kind: 'refused', message: 'Amount must be positive. No funds were debited.' };
+    const mint = a.mint ?? SOL_MINT;
+    const isSol = mint === SOL_MINT;
+    // Caps: per-transfer in SOL-equivalent, SOL reserve, balance.
+    let prices = {};
+    try {
+        prices = await ctx.prices([SOL_MINT, mint]);
+    }
+    catch {
+        prices = {};
+    }
+    const solEq = isSol ? a.amount : prices[mint] && prices[SOL_MINT] ? (a.amount * prices[mint]) / prices[SOL_MINT] : undefined;
+    if (solEq !== undefined && solEq > config.maxTradeSol)
+        return { kind: 'refused', message: `Refused by safety limit: ≈ ${solEq.toFixed(3)} SOL is above POTSWAP_MAX_TRADE_SOL (${config.maxTradeSol}). No funds were debited.` };
+    let bal = {};
+    try {
+        bal = await ctx.balances(signer.publicKey);
+    }
+    catch {
+        bal = {};
+    }
+    const have = bal[mint] ?? 0;
+    const spendable = isSol ? Math.max(have - DEFAULTS.solReserve, 0) : have;
+    if (a.amount > spendable)
+        return { kind: 'refused', message: isSol ? `Insufficient SOL: balance ${have.toFixed(4)}, keep at least ${DEFAULTS.solReserve} SOL for fees. No funds were debited.` : `Insufficient balance (${have}). No funds were debited.` };
+    const summary = `${a.amount} ${isSol ? 'SOL' : mint.slice(0, 4) + '…'} → ${a.to}`;
+    if (!a.confirm)
+        return { kind: 'quote-only', summary: `Transfer not sent (confirm=true to send): ${summary}` };
+    if (config.dryRun)
+        return { kind: 'dry-run', summary: `DRY RUN, nothing signed: ${summary}` };
+    try {
+        const from = new PublicKey(signer.publicKey);
+        const to = new PublicKey(a.to);
+        const tx = new Transaction();
+        if (isSol) {
+            tx.add(SystemProgram.transfer({ fromPubkey: from, toPubkey: to, lamports: BigInt(toRaw(a.amount, 9)) }));
+        }
+        else {
+            const mintPk = new PublicKey(mint);
+            const decimals = a.decimals ?? (await ctx.decimalsOf(mint));
+            const owner = await ctx.getMintOwner?.(mint);
+            const program = owner === TOKEN_2022_PROGRAM_ID.toBase58() ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
+            const src = getAssociatedTokenAddressSync(mintPk, from, false, program);
+            const dst = getAssociatedTokenAddressSync(mintPk, to, true, program);
+            if (!(await ctx.rpc.getAccountOwner(dst.toBase58())))
+                tx.add(createAssociatedTokenAccountIdempotentInstruction(from, dst, to, mintPk, program));
+            tx.add(createTransferCheckedInstruction(src, mintPk, dst, from, BigInt(toRaw(a.amount, decimals)), decimals, [], program));
+        }
+        const { blockhash, lastValidBlockHeight } = await ctx.rpc.getLatestBlockhash('confirmed');
+        tx.recentBlockhash = blockhash;
+        tx.feePayer = from;
+        signer.signLegacy(tx);
+        const signature = await ctx.rpc.sendRawTransaction(tx.serialize());
+        const conf = await ctx.rpc.confirmTransaction(signature, blockhash, lastValidBlockHeight);
+        if (conf.err)
+            return { kind: 'failed', message: `Transfer failed on-chain: ${JSON.stringify(conf.err)}. Check https://solscan.io/tx/${signature}` };
+        return { kind: 'ok', signature, explorerUrl: `https://solscan.io/tx/${signature}`, summary: `Sent ${summary}` };
+    }
+    catch (e) {
+        const m = e instanceof Error ? e.message : String(e);
+        return { kind: 'failed', message: `${m}${/blockhash|expired/i.test(m) ? ' The transaction expired before landing; no funds were debited.' : ''}` };
+    }
+}

package/dist/wallet.d.ts

@@ -1,10 +1,22 @@
-import { type VersionedTransaction } from '@solana/web3.js';
+import { type VersionedTransaction, type Transaction } from '@solana/web3.js';
 export interface Signer {
     publicKey: string;
     sign(tx: VersionedTransaction): VersionedTransaction;
+    signLegacy(tx: Transaction): Transaction;
 }
+export declare const WALLET_FILE = "wallet.json";
 export declare function parseSecret(raw: string): Uint8Array;
+/**
+ * Resolution order: SOLANA_PRIVATE_KEY → SOLANA_KEYPAIR_PATH → `<stateDir>/wallet.json`
+ * (created by `wallet_create`). Returns null when none exists.
+ */
 export declare function loadSigner(opts: {
     privateKey?: string;
     keypairPath?: string;
+    stateDir?: string;
 }): Signer | null;
+/** PRD P13.1 — creates `<stateDir>/wallet.json` (0600). Refuses to overwrite. */
+export declare function createWallet(stateDir: string): {
+    signer: Signer;
+    file: string;
+};

package/dist/wallet.js

@@ -1,8 +1,10 @@
-// PRD P10.2/P10.9 — load the agent's keypair; the secret never leaves this module.
-import { readFileSync } from 'node:fs';
+// PRD P10.2 / P10.9 / P13.1 — load or create the agent's keypair; the secret never leaves this module.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { Keypair } from '@solana/web3.js';
 import bs58 from 'bs58';
 import { registerSecret } from './redact.js';
+export const WALLET_FILE = 'wallet.json';
 export function parseSecret(raw) {
     const s = raw.trim();
     if (s.startsWith('[')) {
@@ -24,6 +26,21 @@ export function parseSecret(raw) {
         return Keypair.fromSeed(bytes).secretKey;
     throw new Error(`Private key has ${bytes.length} bytes; expected 64 (or a 32-byte seed)`);
 }
+function toSigner(kp, raw) {
+    // Register every encoding the secret could leak in, not just the one supplied.
+    registerSecret(raw.trim());
+    registerSecret(bs58.encode(kp.secretKey));
+    registerSecret(JSON.stringify(Array.from(kp.secretKey)));
+    return {
+        publicKey: kp.publicKey.toBase58(),
+        sign(tx) { tx.sign([kp]); return tx; },
+        signLegacy(tx) { tx.sign(kp); return tx; },
+    };
+}
+/**
+ * Resolution order: SOLANA_PRIVATE_KEY → SOLANA_KEYPAIR_PATH → `<stateDir>/wallet.json`
+ * (created by `wallet_create`). Returns null when none exists.
+ */
 export function loadSigner(opts) {
     let raw = opts.privateKey;
     if (!raw && opts.keypairPath) {
@@ -31,18 +48,30 @@ export function loadSigner(opts) {
             raw = readFileSync(opts.keypairPath, 'utf8');
         }
         catch {
-            throw new Error(`Cannot read keypair file at SOLANA_KEYPAIR_PATH`);
+            throw new Error('Cannot read keypair file at SOLANA_KEYPAIR_PATH');
         }
     }
+    if (!raw && opts.stateDir) {
+        const file = join(opts.stateDir, WALLET_FILE);
+        if (existsSync(file))
+            raw = readFileSync(file, 'utf8');
+    }
     if (!raw)
         return null;
-    const kp = Keypair.fromSecretKey(parseSecret(raw));
-    // Register every encoding the secret could leak in, not just the one supplied.
-    registerSecret(raw.trim());
-    registerSecret(bs58.encode(kp.secretKey));
-    registerSecret(JSON.stringify(Array.from(kp.secretKey)));
-    return {
-        publicKey: kp.publicKey.toBase58(),
-        sign(tx) { tx.sign([kp]); return tx; },
-    };
+    return toSigner(Keypair.fromSecretKey(parseSecret(raw)), raw);
+}
+/** PRD P13.1 — creates `<stateDir>/wallet.json` (0600). Refuses to overwrite. */
+export function createWallet(stateDir) {
+    mkdirSync(stateDir, { recursive: true });
+    const file = join(stateDir, WALLET_FILE);
+    if (existsSync(file))
+        throw new Error(`A wallet already exists at ${file}. Back it up and remove it first if you really want a new one.`);
+    const kp = Keypair.generate();
+    const raw = JSON.stringify(Array.from(kp.secretKey));
+    writeFileSync(file, raw, { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch { /* Windows */ }
+    return { signer: toSigner(kp, raw), file };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@potswap_io/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Potswap MCP server: best-route Solana swaps, DCA / rebalance / take-profit strategies for AI agents, non-custodial, earns POT.",
   "license": "MIT",
   "type": "module",
@@ -41,6 +41,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
+    "@solana/spl-token": "^0.4.15",
     "@solana/web3.js": "^1.99.0",
     "bs58": "^6.0.0",
     "zod": "^4.6.7"