@potswap_io/mcp 0.1.0 → 0.3.0

package/dist/strategies/tools.js

@@ -0,0 +1,162 @@
+import { z } from 'zod';
+import { NO_WALLET } from '../config.js';
+import { redact, redactValue } from '../redact.js';
+import { newId, SOL_MINT, nextRunAfter } from './engine.js';
+import { findStrategy, runsOf } from './store.js';
+const MINT = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/);
+const MAX_STRATEGIES = Number(process.env.POTSWAP_MAX_STRATEGIES) || 10;
+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 });
+export function registerStrategyTools(server, deps) {
+    const { trade } = deps;
+    if (!deps.store)
+        return; // strategies disabled (no state dir)
+    const store = deps.store;
+    const scheduler = deps.scheduler;
+    const now = () => Date.now();
+    const base = (kind, maxSlippageBps) => ({
+        id: newId(kind, now()), createdAt: new Date(now()).toISOString(), status: 'active', nextRunAt: new Date(now()).toISOString(),
+        consecutiveFailures: 0, totals: { runs: 0, volumeUsd: 0, feeUsd: 0, pointsAdded: 0 }, maxSlippageBps,
+    });
+    const guard = (confirm) => {
+        if (!trade.signer)
+            return fail(NO_WALLET);
+        if (!confirm)
+            return fail('Set confirm=true to create a strategy. Nothing was created and no funds were debited.');
+        if (store.load().strategies.filter((s) => s.status === 'active').length >= MAX_STRATEGIES)
+            return fail(`Limit of ${MAX_STRATEGIES} active strategies reached. Pause or delete one first.`);
+        return null;
+    };
+    const created = async (s, summary) => {
+        store.update((st) => { st.strategies.push(s); });
+        // First leg right away (P11.1) when a scheduler is attached.
+        if (scheduler)
+            await scheduler.tick();
+        const fresh = findStrategy(store.load(), s.id) ?? s;
+        return ok({ strategy: fresh, schedulerActive: !!scheduler?.active, runs: runsOf(store.load(), s.id, 3) }, `${summary}\nid=${s.id}${scheduler?.active ? '' : '\nNote: no scheduler is running in this process; run `npx @potswap_io/mcp --daemon` to execute strategies 24/7.'}`);
+    };
+    server.registerTool('dca_create', {
+        title: 'Create a DCA strategy',
+        description: 'Buy a fixed amount of a token on a schedule (first run immediately). Every leg pays the Potswap fee and earns POT points. Runs while this host is open, or 24/7 with `npx @potswap_io/mcp --daemon`.',
+        inputSchema: {
+            inputMint: MINT, outputMint: MINT,
+            amountPerRun: z.number().positive().describe('UI units of the input token per run (1 = 1 SOL)'),
+            intervalMinutes: z.number().int().min(5).max(60 * 24 * 30),
+            totalRuns: z.number().int().min(1).max(1000).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.inputMint === a.outputMint)
+            return fail('inputMint and outputMint must differ. Nothing was created.');
+        const s = { ...base('dca', a.maxSlippageBps), kind: 'dca', inputMint: a.inputMint, outputMint: a.outputMint, amountPerRun: a.amountPerRun, intervalMinutes: a.intervalMinutes, totalRuns: a.totalRuns, runsDone: 0 };
+        return created(s, `DCA created: ${a.amountPerRun} per run every ${a.intervalMinutes} min${a.totalRuns ? ` × ${a.totalRuns}` : ''}.`);
+    });
+    server.registerTool('rebalance_create', {
+        title: 'Create a rebalance strategy',
+        description: 'Keep the wallet at target percentages (2–6 assets incl. SOL). Checks on an interval; trades only when an asset drifts more than driftPct, routing through SOL.',
+        inputSchema: {
+            targets: z.record(MINT, z.number().min(0).max(100)).describe('mint → percent; must sum to 100 and include SOL'),
+            driftPct: z.number().min(1).max(50).default(5),
+            checkIntervalMinutes: z.number().int().min(15).max(60 * 24 * 7).default(60),
+            minTradeUsd: z.number().min(1).default(5),
+            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;
+        const mints = Object.keys(a.targets);
+        const sum = Object.values(a.targets).reduce((x, y) => x + y, 0);
+        if (mints.length < 2 || mints.length > 6)
+            return fail('targets must list 2–6 assets. Nothing was created.');
+        if (Math.abs(sum - 100) > 0.5)
+            return fail(`targets must sum to 100 (got ${sum}). Nothing was created.`);
+        if (!(SOL_MINT in a.targets))
+            return fail('targets must include SOL (So11111111111111111111111111111111111111112). Nothing was created.');
+        const s = { ...base('rebalance', a.maxSlippageBps), kind: 'rebalance', targets: a.targets, driftPct: a.driftPct, checkIntervalMinutes: a.checkIntervalMinutes, minTradeUsd: a.minTradeUsd };
+        return created(s, `Rebalance created: ${mints.map((m) => `${m === SOL_MINT ? 'SOL' : m.slice(0, 4)} ${a.targets[m]}%`).join(' / ')}, drift ${a.driftPct}%, every ${a.checkIntervalMinutes} min.`);
+    });
+    server.registerTool('tpsl_create', {
+        title: 'Create a take-profit / stop-loss',
+        description: 'Sell a percentage of a position when its price reaches a take-profit, stop-loss or trailing-stop level (entry = price now). Checks every 30 s while a scheduler runs.',
+        inputSchema: {
+            mint: MINT, sellPct: z.number().min(1).max(100).default(100),
+            takeProfitPct: z.number().positive().optional(), stopLossPct: z.number().positive().max(99).optional(), trailingPct: z.number().positive().max(99).optional(),
+            exitMint: MINT.default(SOL_MINT), 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.takeProfitPct === undefined && a.stopLossPct === undefined && a.trailingPct === undefined)
+            return fail('Set at least one of takeProfitPct, stopLossPct, trailingPct. Nothing was created.');
+        if (a.mint === a.exitMint)
+            return fail('mint and exitMint must differ. Nothing was created.');
+        let entry;
+        try {
+            entry = (await trade.api.prices([a.mint]))[a.mint];
+        }
+        catch {
+            entry = undefined;
+        }
+        if (!entry)
+            return fail('No price available for this token right now; try again in a moment. Nothing was created.');
+        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 }));
+        return ok({ schedulerActive: !!scheduler?.active, stateFile: store.location, strategies: rows }, rows.length ? rows.map((s) => `${s.id} ${s.kind} ${s.status}${s.pausedReason ? ` (${s.pausedReason})` : ''} next=${s.nextRunAt ?? '—'} runs=${s.totals.runs} fees=$${s.totals.feeUsd.toFixed(2)}`).join('\n') : 'No strategies yet.');
+    });
+    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' || 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}.`);
+    });
+    server.registerTool('strategy_runs', { title: 'Strategy run log', description: 'Recent legs with amounts, signatures, fees, points, or the skip/fail reason.', inputSchema: { id: z.string().min(3), limit: z.number().int().min(1).max(200).default(20) } }, async ({ id, limit }) => {
+        const st = store.load();
+        if (!findStrategy(st, id))
+            return fail(`No strategy ${id}.`);
+        const runs = runsOf(st, id, limit);
+        return ok({ id, runs }, runs.length ? runs.map((r) => `${r.at} ${r.outcome}: ${r.action}${r.signature ? ` sig=${r.signature}` : ''}${r.message ? ` — ${r.message}` : ''}`).join('\n') : 'No runs yet.');
+    });
+    function mutate(id, fn) {
+        try {
+            const s = store.update((st) => { const cur = findStrategy(st, id); if (!cur)
+                return null; fn(cur); return cur; });
+            return s ? ok({ strategy: s }, `${s.id} is now ${s.status}.`) : fail(`No strategy ${id}.`);
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+}

package/dist/strategies/types.d.ts

@@ -0,0 +1,78 @@
+export type StrategyStatus = 'active' | 'paused' | 'completed';
+interface Base {
+    id: string;
+    createdAt: string;
+    status: StrategyStatus;
+    pausedReason?: string;
+    nextRunAt: string | null;
+    consecutiveFailures: number;
+    totals: {
+        runs: number;
+        volumeUsd: number;
+        feeUsd: number;
+        pointsAdded: number;
+    };
+    maxSlippageBps?: number;
+}
+export interface DcaStrategy extends Base {
+    kind: 'dca';
+    inputMint: string;
+    outputMint: string;
+    amountPerRun: number;
+    intervalMinutes: number;
+    totalRuns?: number;
+    runsDone: number;
+}
+export interface RebalanceStrategy extends Base {
+    kind: 'rebalance';
+    targets: Record<string, number>;
+    driftPct: number;
+    checkIntervalMinutes: number;
+    minTradeUsd: number;
+}
+export interface TpSlStrategy extends Base {
+    kind: 'tpsl';
+    mint: string;
+    sellPct: number;
+    exitMint: string;
+    entryPrice: number;
+    highWater: number;
+    takeProfitPct?: number;
+    stopLossPct?: number;
+    trailingPct?: number;
+}
+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;
+    strategyId: string;
+    at: string;
+    action: string;
+    outcome: RunOutcome;
+    message?: string;
+    signature?: string;
+    inAmount?: number;
+    inputSymbol?: string;
+    outAmount?: number;
+    outputSymbol?: string;
+    feeUsd?: number;
+    pointsAdded?: number;
+    solEquivalent?: number;
+}
+export interface StrategyState {
+    version: 1;
+    strategies: Strategy[];
+    runs: Run[];
+}
+export declare const EMPTY_STATE: StrategyState;
+export {};

package/dist/strategies/types.js

@@ -0,0 +1,2 @@
+// PRD P11 — strategy definitions persisted in ~/.potswap/strategies.json.
+export const EMPTY_STATE = { version: 1, strategies: [], runs: [] };

package/dist/trade.d.ts

@@ -0,0 +1,86 @@
+import type { PotswapApi } from './api.js';
+import { type Config } from './config.js';
+import type { Signer } from './wallet.js';
+export type BalancesFn = (wallet: string) => Promise<Record<string, number>>;
+export interface TradeContext {
+    api: PotswapApi;
+    config: Config;
+    signer: Signer | null;
+    balances: BalancesFn;
+}
+export interface SwapArgs {
+    inputMint: string;
+    outputMint: string;
+    amount: number;
+    slippageBps?: number;
+    confirm?: boolean;
+    /** Extra SOL-equivalent already spent in the current window (strategies' daily cap). */
+    extraSolCap?: {
+        remainingSol: number;
+        label: string;
+    };
+}
+export interface Quote {
+    inputMint: string;
+    inputSymbol: string;
+    outputMint: string;
+    outputSymbol: string;
+    inAmount: number;
+    inAmountRaw: string;
+    outAmount: number;
+    price: number;
+    priceImpactPct?: number;
+    slippageBps?: number;
+    feeBps: number;
+    feeTier: string | null;
+    feeLabel: string | null;
+    scheduledFeeBps: number;
+    inputUsd?: number;
+    router: string;
+    requestId: string;
+    expiresAt: string | null;
+}
+export interface SwapOk {
+    signature: string;
+    explorerUrl: string;
+    inAmount: number;
+    inputSymbol: string;
+    outAmount: number;
+    outputSymbol: string;
+    router: string;
+    feeBps: number;
+    feeUsd?: number;
+    pointsAdded?: number;
+    solEquivalent?: number;
+}
+export type SwapOutcome = {
+    kind: 'no-wallet';
+    message: string;
+} | {
+    kind: 'refused';
+    message: string;
+    quote: Quote;
+} | {
+    kind: 'quote-only';
+    quote: Quote;
+} | {
+    kind: 'dry-run';
+    quote: Quote;
+} | {
+    kind: 'failed';
+    message: string;
+    quote?: Quote;
+    signature?: string;
+    explorerUrl?: string;
+} | {
+    kind: 'ok';
+    result: SwapOk;
+    quote: Quote;
+};
+export declare function buildQuote(api: PotswapApi, a: {
+    inputMint: string;
+    outputMint: string;
+    amount: number;
+    slippageBps?: number;
+}): Promise<Quote>;
+export declare function executeSwap(ctx: TradeContext, a: SwapArgs): Promise<SwapOutcome>;

package/dist/trade.js

@@ -0,0 +1,86 @@
+// 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, 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';
+import { feeBpsFor } from './shared/fee.js';
+export async function buildQuote(api, a) {
+    const [inTok, outTok, cfg, px] = await Promise.all([
+        api.token(a.inputMint), api.token(a.outputMint), api.config(), api.prices([a.inputMint]).catch(() => ({})),
+    ]);
+    const inAmountRaw = toRaw(a.amount, inTok.decimals);
+    // PRD P8.12–P8.15: the fee tier depends on the USD value of the input at quote time.
+    const inputUsd = px[a.inputMint] ? a.amount * px[a.inputMint] : undefined;
+    const feeDecision = feeBpsFor(cfg.fee, inputUsd);
+    const o = await api.order({ inputMint: a.inputMint, outputMint: a.outputMint, amount: inAmountRaw, slippageBps: a.slippageBps, feeBps: feeDecision.bps });
+    if (o.errorMessage && !o.outAmount)
+        throw new Error(`${describeOrderError(o)} No funds were debited.`);
+    const outAmount = fromRaw(o.outAmount, outTok.decimals);
+    return {
+        inputMint: a.inputMint, inputSymbol: inTok.symbol, outputMint: a.outputMint, outputSymbol: outTok.symbol,
+        inAmount: a.amount, inAmountRaw, outAmount, price: outAmount / a.amount,
+        priceImpactPct: o.priceImpactPct !== undefined ? Math.abs(Number(o.priceImpactPct)) : undefined,
+        slippageBps: o.slippageBps, feeBps: o.platformFee?.feeBps ?? o.feeBps ?? 0,
+        feeTier: cfg.referralAccount ? feeDecision.tier : null, feeLabel: cfg.referralAccount ? feeDecision.label : null,
+        scheduledFeeBps: feeDecision.bps, inputUsd, router: o.router, requestId: o.requestId, expiresAt: o.expireAt ?? null,
+    };
+}
+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(() => ({}));
+        let balanceUi;
+        try {
+            balanceUi = (await ctx.balances(signer.publicKey))[a.inputMint] ?? 0;
+        }
+        catch {
+            balanceUi = undefined;
+        }
+        const inputUsd = prices[a.inputMint] ? a.amount * prices[a.inputMint] : undefined;
+        const solEquivalent = a.inputMint === SOL_MINT ? a.amount : inputUsd !== undefined && prices[SOL_MINT] ? inputUsd / prices[SOL_MINT] : undefined;
+        const refusal = checkLimits({
+            amountUi: a.amount, inputMint: a.inputMint, inputSymbol: quote.inputSymbol, isSol: a.inputMint === SOL_MINT,
+            inputUsd, solUsd: prices[SOL_MINT], slippageBps: a.slippageBps,
+            maxTradeSol: config.maxTradeSol, maxSlippageBps: config.maxSlippageBps, balanceUi,
+        });
+        if (refusal)
+            return { kind: 'refused', message: refusal, quote };
+        if (a.extraSolCap && solEquivalent !== undefined && solEquivalent > a.extraSolCap.remainingSol) {
+            return { kind: 'refused', message: `${a.extraSolCap.label} No funds were debited.`, quote };
+        }
+        if (!a.confirm)
+            return { kind: 'quote-only', quote };
+        if (config.dryRun)
+            return { kind: 'dry-run', quote };
+        const order = await api.order({ inputMint: a.inputMint, outputMint: a.outputMint, amount: quote.inAmountRaw, taker: signer.publicKey, slippageBps: a.slippageBps, feeBps: quote.scheduledFeeBps });
+        if (!order.transaction)
+            return { kind: 'failed', message: `${describeOrderError(order)} No funds were debited.`, quote };
+        const tx = VersionedTransaction.deserialize(Buffer.from(order.transaction, 'base64'));
+        signer.sign(tx);
+        const res = await api.execute(Buffer.from(tx.serialize()).toString('base64'), order.requestId);
+        if (res.status !== 'Success') {
+            return { kind: 'failed', message: friendlyError(res.error || `Swap failed (code ${res.code})`), quote, signature: res.signature, explorerUrl: res.signature ? explorer(res.signature) : undefined };
+        }
+        const outDec = (await api.token(a.outputMint)).decimals;
+        const outAmount = fromRaw(res.totalOutputAmount ?? order.outAmount, outDec);
+        const feeBps = order.platformFee?.feeBps ?? order.feeBps ?? 0;
+        const feeUsd = inputUsd !== undefined ? inputUsd * feeBps / 10_000 : undefined;
+        const cfg = await api.config();
+        const result = {
+            signature: res.signature, explorerUrl: explorer(res.signature), inAmount: a.amount, inputSymbol: quote.inputSymbol,
+            outAmount, outputSymbol: quote.outputSymbol, router: order.router, feeBps, feeUsd, pointsAdded: cfg.referralAccount ? feeUsd : 0, solEquivalent,
+        };
+        return { kind: 'ok', result, quote };
+    }
+    catch (e) {
+        return { kind: 'failed', message: friendlyError(e instanceof Error ? e.message : String(e)) };
+    }
+}

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 };
 }