@potswap_io/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Potswap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @potswap_io/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Solana swap tool for AI agents. One MCP server gives your agent best-route swaps across every Solana DEX (Metis, JupiterZ, DFlow and OKX compete on each order, MEV-protected), token research with risk flags, balances, and POT rewards for every trade.
+
+- **Non-custodial.** Transactions are signed on your machine with your own keypair. The key never leaves the process and is redacted from every output.
+- **Safe by default.** `swap` needs `confirm: true`; per-trade cap 1 SOL; slippage cap 3%; dry-run mode; a 0.01 SOL reserve is always kept. Every error says whether funds were debited.
+- **Pays you back.** Potswap charges a 0.5% fee inside the swap and returns it to the trading wallet as POT points (Season 1). Agents earn exactly like humans.
+- **$0 to run.** Talks only to `potswap.io`; no API keys needed.
+
+## Install
+
+Node 20+. No install step; run it with `npx`.
+
+### Claude Desktop
+
+`claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "potswap": {
+      "command": "npx",
+      "args": ["-y", "@potswap_io/mcp"],
+      "env": {
+        "SOLANA_PRIVATE_KEY": "<base58 secret or JSON byte array>",
+        "POTSWAP_MAX_TRADE_SOL": "0.5"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add potswap -e SOLANA_KEYPAIR_PATH=~/.config/solana/id.json -- npx -y @potswap_io/mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json` in your project:
+
+```json
+{ "mcpServers": { "potswap": { "command": "npx", "args": ["-y", "@potswap_io/mcp"], "env": { "SOLANA_KEYPAIR_PATH": "/home/you/.config/solana/id.json" } } } }
+```
+
+Without a key the server still runs in read-only mode (search, quotes, trending, points of any wallet).
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `SOLANA_PRIVATE_KEY` | — | base58 secret key (64 bytes) or JSON byte array, as exported by Phantom / `solana-keygen` |
+| `SOLANA_KEYPAIR_PATH` | — | path to a `solana-keygen` JSON file; used when `SOLANA_PRIVATE_KEY` is unset |
+| `SOLANA_RPC_URL` | Potswap's RPC proxy | your own RPC if you trade a lot |
+| `POTSWAP_MAX_TRADE_SOL` | `1` | refuse any swap whose input is worth more than this many SOL |
+| `POTSWAP_MAX_SLIPPAGE_BPS` | `300` | refuse requested slippage above this |
+| `POTSWAP_DRY_RUN` | `false` | `true` = `swap` never signs; returns what it would have done |
+| `POTSWAP_API` | `https://www.potswap.io` | base URL |
+
+Use a dedicated agent wallet with only the funds you want the agent to control. Keep the caps low until you trust the agent's behaviour.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `search_tokens {query}` | Find tokens by name/symbol/mint |
+| `get_token {mint}` | Price, mcap, liquidity, holders, audit data, **risk badges** (`riskLevel` 0 safe → 3 danger) |
+| `get_trending {kind}` | `new`, `trending`, `top`, `graduating` lists |
+| `get_quote {inputMint, outputMint, amount}` | Best route, fee, impact, router. `amount` is in UI units (1 = 1 SOL) |
+| `swap {…, confirm: true}` | Executes at the best route and returns the signature, amounts, fee and POT points |
+| `get_balances {wallet?}` | SOL + SPL balances with USD |
+| `get_positions {wallet?}` | Holdings with USD; PnL coming |
+| `get_points {wallet?}` | Season 1 points, POT allocated / claimable, next unlock |
+| `get_leaderboard` | Top wallets by fee paid |
+
+Example prompt: *"Check BONK's risk flags, and if riskLevel is 0 or 1 buy 0.1 SOL worth."* The agent calls `get_token`, then `swap` with `confirm: true`; you can require that it shows you the quote first by leaving `POTSWAP_DRY_RUN=true` until you are comfortable.
+
+## Fees and rewards
+
+Each swap carries Potswap's 0.5% integrator fee via Jupiter's referral program; Jupiter keeps 20% of it. The fee basis is credited to the trading wallet as Season 1 points, split daily: 666,666 POT per epoch, by `fee^1.1`, capped at 10% per wallet. Points become POT tokens after the token launch; unlock 7 days after each epoch. Details: https://www.potswap.io
+
+## Development
+
+```bash
+cd mcp && npm i && npm test      # unit tests over the real MCP protocol (in-memory transport)
+npm run dev                       # run from source
+npm run sync-shared && npm run build
+```
+
+MIT © Potswap

package/dist/api.d.ts

@@ -0,0 +1,37 @@
+import type { ExecuteResponse, OrderResponse, Token } from './shared/lib-types.js';
+import type { TerminalToken } from './shared/types.js';
+export type FetchFn = typeof fetch;
+export declare class ApiError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export interface PublicConfig {
+    referralAccount: string | null;
+    referralFeeBps: number;
+    seasonStart: string | null;
+    pointsEnabled: boolean;
+}
+export declare class PotswapApi {
+    private base;
+    private fetchFn;
+    private configCache;
+    private tokenCache;
+    constructor(base: string, fetchFn?: FetchFn);
+    private req;
+    config(): Promise<PublicConfig>;
+    order(p: {
+        inputMint: string;
+        outputMint: string;
+        amount: string;
+        taker?: string;
+        slippageBps?: number;
+    }): Promise<OrderResponse>;
+    execute(signedTransaction: string, requestId: string): Promise<ExecuteResponse>;
+    searchTokens(query: string): Promise<Token[]>;
+    token(mint: string): Promise<Token>;
+    prices(mints: string[]): Promise<Record<string, number>>;
+    list(kind: string): Promise<TerminalToken[]>;
+    terminalToken(mint: string): Promise<TerminalToken>;
+    points(wallet: string): Promise<Record<string, unknown>>;
+    leaderboard(): Promise<Record<string, unknown>>;
+}

package/dist/api.js

@@ -0,0 +1,89 @@
+export class ApiError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+export class PotswapApi {
+    base;
+    fetchFn;
+    configCache = null;
+    tokenCache = new Map();
+    constructor(base, fetchFn = fetch) { this.base = base; this.fetchFn = fetchFn; }
+    async req(path, init, retry = true) {
+        const res = await this.fetchFn(this.base + path, { ...init, headers: { accept: 'application/json', ...init?.headers } });
+        if (res.status === 429 || res.status === 503) {
+            if (retry) {
+                await new Promise((r) => setTimeout(r, 1100));
+                return this.req(path, init, false);
+            }
+            throw new ApiError(res.status, 'Potswap is busy; retry in a few seconds. No funds were debited.');
+        }
+        const text = await res.text();
+        let data = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = { error: text };
+        }
+        if (!res.ok) {
+            const msg = data?.error ?? data?.message ?? `HTTP ${res.status}`;
+            throw new ApiError(res.status, msg);
+        }
+        return data;
+    }
+    async config() {
+        if (this.configCache && Date.now() - this.configCache.at < 300_000)
+            return this.configCache.value;
+        let value;
+        try {
+            value = await this.req('/api/config');
+        }
+        catch {
+            value = { referralAccount: null, referralFeeBps: 0, seasonStart: null, pointsEnabled: false };
+        }
+        this.configCache = { value, at: Date.now() };
+        return value;
+    }
+    async order(p) {
+        const cfg = await this.config();
+        const q = new URLSearchParams({ inputMint: p.inputMint, outputMint: p.outputMint, amount: p.amount });
+        if (p.taker)
+            q.set('taker', p.taker);
+        if (p.slippageBps !== undefined)
+            q.set('slippageBps', String(p.slippageBps));
+        if (cfg.referralAccount) {
+            q.set('referralAccount', cfg.referralAccount);
+            q.set('referralFee', String(cfg.referralFeeBps));
+        }
+        return this.req(`/api/jup/swap/v2/order?${q}`);
+    }
+    execute(signedTransaction, requestId) {
+        return this.req('/api/jup/swap/v2/execute', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ signedTransaction, requestId }) });
+    }
+    async searchTokens(query) {
+        const list = await this.req(`/api/jup/tokens/v2/search?query=${encodeURIComponent(query)}`);
+        for (const t of list)
+            this.tokenCache.set(t.id, t);
+        return list;
+    }
+    async token(mint) {
+        const hit = this.tokenCache.get(mint);
+        if (hit)
+            return hit;
+        const list = await this.searchTokens(mint);
+        const t = list.find((x) => x.id === mint);
+        if (!t)
+            throw new ApiError(404, `Unknown token ${mint}`);
+        return t;
+    }
+    async prices(mints) {
+        if (!mints.length)
+            return {};
+        const d = await this.req(`/api/price/v3?ids=${mints.join(',')}`.replace('/api/price', '/api/jup/price'));
+        return Object.fromEntries(Object.entries(d).map(([k, v]) => [k, v.usdPrice]));
+    }
+    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}`); }
+    leaderboard() { return this.req('/api/leaderboard'); }
+}

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface Config {
+    apiBase: string;
+    rpcUrl: string;
+    maxTradeSol: number;
+    maxSlippageBps: number;
+    dryRun: boolean;
+    privateKey?: string;
+    keypairPath?: string;
+}
+export declare const DEFAULTS: {
+    apiBase: string;
+    maxTradeSol: number;
+    maxSlippageBps: number;
+    solReserve: number;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+export declare const SOL_MINT = "So11111111111111111111111111111111111111112";
+export declare const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const NO_WALLET = "Wallet not configured. Set SOLANA_PRIVATE_KEY or SOLANA_KEYPAIR_PATH. No funds were debited.";

package/dist/config.js

@@ -0,0 +1,22 @@
+export const DEFAULTS = {
+    apiBase: 'https://www.potswap.io',
+    maxTradeSol: 1,
+    maxSlippageBps: 300,
+    solReserve: 0.01,
+};
+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; };
+    return {
+        apiBase,
+        rpcUrl: env.SOLANA_RPC_URL || `${apiBase}/api/rpc`,
+        maxTradeSol: num(env.POTSWAP_MAX_TRADE_SOL, DEFAULTS.maxTradeSol),
+        maxSlippageBps: num(env.POTSWAP_MAX_SLIPPAGE_BPS, DEFAULTS.maxSlippageBps),
+        dryRun: /^(1|true|yes)$/i.test(env.POTSWAP_DRY_RUN ?? ''),
+        privateKey: env.SOLANA_PRIVATE_KEY || undefined,
+        keypairPath: env.SOLANA_KEYPAIR_PATH || undefined,
+    };
+}
+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.';

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+export declare function toRaw(amount: number | string, decimals: number): string;
+export declare const fromRaw: (raw: string | number | bigint, decimals: number) => number;
+export declare const explorer: (sig: string) => string;

package/dist/format.js

@@ -0,0 +1,7 @@
+export function toRaw(amount, decimals) {
+    const [i = '0', f = ''] = String(amount).replace(/,/g, '.').split('.');
+    const frac = (f + '0'.repeat(decimals)).slice(0, decimals);
+    return (BigInt(i || '0') * 10n ** BigInt(decimals) + BigInt(frac || '0')).toString();
+}
+export const fromRaw = (raw, decimals) => Number(BigInt(raw)) / 10 ** decimals;
+export const explorer = (sig) => `https://solscan.io/tx/${sig}`;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Potswap MCP server over stdio. Configure via env (see README).
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer, VERSION } from './server.js';
+import { loadConfig } from './config.js';
+import { log } from './redact.js';
+const config = loadConfig();
+const server = createServer({ config });
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log(`potswap-mcp v${VERSION} ready · api=${config.apiBase} · maxTradeSol=${config.maxTradeSol} · maxSlippageBps=${config.maxSlippageBps}${config.dryRun ? ' · DRY RUN' : ''}${config.privateKey || config.keypairPath ? '' : ' · no wallet (read-only)'}`);

package/dist/limits.d.ts

@@ -0,0 +1,13 @@
+export interface LimitInput {
+    amountUi: number;
+    inputMint: string;
+    inputSymbol: string;
+    inputUsd?: number;
+    solUsd?: number;
+    isSol: boolean;
+    slippageBps?: number;
+    maxTradeSol: number;
+    maxSlippageBps: number;
+    balanceUi?: number;
+}
+export declare function checkLimits(i: LimitInput): string | null;

package/dist/limits.js

@@ -0,0 +1,23 @@
+// PRD P10.6 — safety limits applied before anything is signed.
+import { DEFAULTS } from './config.js';
+export function checkLimits(i) {
+    if (!(i.amountUi > 0))
+        return 'Amount must be a positive number in UI units (1 = 1 SOL). No funds were debited.';
+    if (i.slippageBps !== undefined && i.slippageBps > i.maxSlippageBps) {
+        return `Refused by safety limit: slippage ${i.slippageBps / 100}% is above POTSWAP_MAX_SLIPPAGE_BPS (${i.maxSlippageBps / 100}%). No funds were debited.`;
+    }
+    const solEquivalent = i.isSol ? i.amountUi : i.inputUsd !== undefined && i.solUsd ? i.inputUsd / i.solUsd : undefined;
+    if (solEquivalent !== undefined && solEquivalent > i.maxTradeSol) {
+        const hint = i.amountUi >= 1_000_000 ? ' Hint: amount is in UI units (1 = 1 SOL), not lamports.' : '';
+        return `Refused by safety limit: ${i.amountUi} ${i.inputSymbol} ≈ ${solEquivalent.toFixed(3)} SOL is above POTSWAP_MAX_TRADE_SOL (${i.maxTradeSol}).${hint} No funds were debited.`;
+    }
+    if (i.balanceUi !== undefined) {
+        const spendable = i.isSol ? Math.max(i.balanceUi - DEFAULTS.solReserve, 0) : i.balanceUi;
+        if (i.amountUi > spendable) {
+            return i.isSol
+                ? `Insufficient SOL: balance ${i.balanceUi.toFixed(4)}, keep at least ${DEFAULTS.solReserve} SOL for fees. No funds were debited.`
+                : `Insufficient ${i.inputSymbol} balance (${i.balanceUi}). No funds were debited.`;
+        }
+    }
+    return null;
+}

package/dist/redact.d.ts

@@ -0,0 +1,5 @@
+export declare function registerSecret(s: string): void;
+export declare function redact(text: string): string;
+export declare function redactValue<T>(v: T): T;
+/** stderr logger (stdout is the MCP transport); always redacted. */
+export declare function log(...parts: unknown[]): void;

package/dist/redact.js

@@ -0,0 +1,23 @@
+// PRD P10.9 — anything that might contain a secret passes through redact() before leaving the process.
+const secrets = new Set();
+export function registerSecret(s) { if (s && s.length >= 16)
+    secrets.add(s); }
+export function redact(text) {
+    let out = text;
+    for (const s of secrets) {
+        if (out.includes(s))
+            out = out.split(s).join('[REDACTED]');
+        // JSON byte arrays can be re-serialised with different spacing: compare whitespace-free.
+        if (s.startsWith('[') && out.replace(/\s+/g, '').includes(s.replace(/\s+/g, ''))) {
+            out = out.replace(/\[\s*(?:\d{1,3}\s*,\s*){63}\d{1,3}\s*\]/g, '[REDACTED]');
+        }
+    }
+    return out;
+}
+export function redactValue(v) {
+    return JSON.parse(redact(JSON.stringify(v)));
+}
+/** stderr logger (stdout is the MCP transport); always redacted. */
+export function log(...parts) {
+    process.stderr.write(redact(parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(p))).join(' ')) + '\n');
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type FetchFn } from './api.js';
+import { SOL_MINT, USDC_MINT, type Config } from './config.js';
+import { type Signer } from './wallet.js';
+export declare const VERSION = "0.1.0";
+export interface ServerDeps {
+    config?: Config;
+    signer?: Signer | null;
+    fetchFn?: FetchFn;
+    /** Balance reader; defaults to an RPC connection. Injectable for tests. */
+    balances?: (wallet: string) => Promise<Record<string, number>>;
+}
+export declare function createServer(deps?: ServerDeps): McpServer;
+export { SOL_MINT, USDC_MINT };

package/dist/server.js

@@ -0,0 +1,249 @@
+// PRD P10 — the Potswap MCP server. Tools are thin, safe wrappers over the Potswap API.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Connection, PublicKey, VersionedTransaction } from '@solana/web3.js';
+import { z } from 'zod';
+import { PotswapApi, ApiError } from './api.js';
+import { loadConfig, NO_WALLET, SOL_MINT, USDC_MINT } from './config.js';
+import { checkLimits } from './limits.js';
+import { explorer, fromRaw, toRaw } from './format.js';
+import { redact, redactValue } from './redact.js';
+import { loadSigner } from './wallet.js';
+import { describeOrderError, friendlyError } from './shared/errors.js';
+import { riskBadges, riskLevel } from './shared/risk.js';
+export const VERSION = '0.1.0';
+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 createServer(deps = {}) {
+    const config = deps.config ?? loadConfig();
+    const signer = deps.signer !== undefined ? deps.signer : loadSigner(config);
+    const api = new PotswapApi(config.apiBase, deps.fetchFn);
+    const readBalances = deps.balances ?? rpcBalances(config.rpcUrl);
+    const server = new McpServer({ name: 'potswap', version: VERSION });
+    const walletOr = (w) => w ?? signer?.publicKey ?? null;
+    server.registerTool('search_tokens', {
+        title: 'Search Solana tokens',
+        description: 'Find tokens by name, symbol or mint address. Returns up to 20 with price, market cap and liquidity.',
+        inputSchema: { query: z.string().min(1).max(64) },
+    }, async ({ query }) => {
+        try {
+            const list = (await api.searchTokens(query)).slice(0, 20);
+            const tokens = list.map(slimToken);
+            return ok({ tokens }, tokens.map((t) => `${t.symbol} (${t.name}) ${t.mint} price=${t.usdPrice ?? '?'} mcap=${t.mcap ?? '?'}${t.isVerified ? ' ✓' : ''}`).join('\n') || 'No tokens found');
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_token', {
+        title: 'Token details and risk flags',
+        description: 'Full token record: price, mcap, liquidity, holders, 5m/1h/6h/24h stats, audit data and risk badges (riskLevel 0 safe … 3 danger).',
+        inputSchema: { mint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/) },
+    }, async ({ mint }) => {
+        try {
+            const t = await api.terminalToken(mint);
+            const badges = riskBadges(t);
+            return ok({ token: t, riskBadges: badges, riskLevel: riskLevel(badges) }, `${t.symbol} (${t.name})\nprice=${t.usdPrice} mcap=${t.mcap} liquidity=${t.liquidity} holders=${t.holderCount}\nrisk ${riskLevel(badges)}/3: ${badges.map((b) => b.label).join(', ')}`);
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_trending', {
+        title: 'Trending / new / top / graduating tokens',
+        description: 'Discovery lists from Potswap (edge-cached, refreshed every 15 s).',
+        inputSchema: { kind: z.enum(['new', 'trending', 'top', 'graduating']).default('trending'), limit: z.number().int().min(1).max(50).default(20) },
+    }, async ({ kind, limit }) => {
+        try {
+            const list = (await api.list(kind)).slice(0, limit);
+            const rows = list.map((t) => ({ mint: t.id, symbol: t.symbol, name: t.name, usdPrice: t.usdPrice, mcap: t.mcap, liquidity: t.liquidity, holders: t.holderCount, change5m: t.stats5m?.priceChange, change1h: t.stats1h?.priceChange, bondingProgress: t.bondingProgress, riskLevel: riskLevel(riskBadges(t)) }));
+            return ok({ kind, tokens: rows }, rows.map((r) => `${r.symbol} ${r.mint} mcap=${r.mcap} 5m=${r.change5m} risk=${r.riskLevel}`).join('\n'));
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_quote', {
+        title: 'Get a swap quote',
+        description: 'Best route across Metis, JupiterZ, DFlow and OKX. Amount is in UI units of the input token (1 = 1 SOL). Includes the Potswap fee (returned to the wallet as POT points).',
+        inputSchema: quoteShape,
+    }, async (a) => {
+        try {
+            const q = await buildQuote(api, a);
+            return ok(q, `${a.amount} ${q.inputSymbol} → ${q.outAmount} ${q.outputSymbol} via ${q.router} (fee ${q.feeBps} bps, impact ${q.priceImpactPct}%)`);
+        }
+        catch (e) {
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('swap', {
+        title: 'Swap tokens (signs with the agent wallet)',
+        description: 'Executes a swap at the best route. Requires confirm=true; otherwise returns the quote only. Protected by POTSWAP_MAX_TRADE_SOL and POTSWAP_MAX_SLIPPAGE_BPS. Every error states whether funds were debited.',
+        inputSchema: { ...quoteShape, confirm: z.boolean().default(false), maxSlippageBps: z.number().int().min(1).max(5000).optional() },
+    }, async (a) => {
+        if (!signer)
+            return fail(NO_WALLET);
+        try {
+            const q = await buildQuote(api, a);
+            const slippageBps = a.slippageBps ?? a.maxSlippageBps;
+            const prices = await api.prices([SOL_MINT, a.inputMint]).catch(() => ({}));
+            let balanceUi;
+            try {
+                balanceUi = (await readBalances(signer.publicKey))[a.inputMint] ?? 0;
+            }
+            catch {
+                balanceUi = undefined;
+            }
+            const refusal = checkLimits({
+                amountUi: a.amount, inputMint: a.inputMint, inputSymbol: q.inputSymbol, isSol: a.inputMint === SOL_MINT,
+                inputUsd: prices[a.inputMint] ? a.amount * prices[a.inputMint] : undefined, solUsd: prices[SOL_MINT],
+                slippageBps, maxTradeSol: config.maxTradeSol, maxSlippageBps: config.maxSlippageBps, balanceUi,
+            });
+            if (refusal)
+                return fail(refusal, { quote: q });
+            if (!a.confirm)
+                return ok({ confirmRequired: true, quote: q }, `Quote only (confirm=true to execute): ${a.amount} ${q.inputSymbol} → ${q.outAmount} ${q.outputSymbol} via ${q.router}`);
+            if (config.dryRun)
+                return ok({ dryRun: true, quote: q }, `DRY RUN, nothing signed: ${a.amount} ${q.inputSymbol} → ${q.outAmount} ${q.outputSymbol}`);
+            const order = await api.order({ inputMint: a.inputMint, outputMint: a.outputMint, amount: q.inAmountRaw, taker: signer.publicKey, slippageBps });
+            if (!order.transaction)
+                return fail(`${describeOrderError(order)} No funds were debited.`, { quote: q });
+            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 fail(friendlyError(res.error || `Swap failed (code ${res.code})`), { 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 = prices[a.inputMint] ? a.amount * prices[a.inputMint] * feeBps / 10_000 : undefined;
+            const cfg = await api.config();
+            const result = { signature: res.signature, explorerUrl: explorer(res.signature), inAmount: a.amount, inputSymbol: q.inputSymbol, outAmount, outputSymbol: q.outputSymbol, router: order.router, feeBps, feeUsd, pointsAdded: cfg.referralAccount ? feeUsd : 0 };
+            return ok(result, `Swapped ${a.amount} ${q.inputSymbol} → ${outAmount} ${q.outputSymbol} via ${order.router}. ${explorer(res.signature)}`);
+        }
+        catch (e) {
+            return fail(friendlyError(msg(e)));
+        }
+    });
+    server.registerTool('get_balances', {
+        title: 'Wallet balances',
+        description: 'SOL and SPL token balances with USD values. Defaults to the agent wallet.',
+        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);
+            const prices = await api.prices(mints.slice(0, 50)).catch(() => ({}));
+            const rows = mints.map((m) => ({ mint: m, amount: bal[m], usd: prices[m] ? bal[m] * prices[m] : undefined })).sort((x, y) => (y.usd ?? 0) - (x.usd ?? 0));
+            const total = rows.reduce((s, r) => s + (r.usd ?? 0), 0);
+            return ok({ wallet: w, totalUsd: total, balances: rows }, `${w}\ntotal ≈ $${total.toFixed(2)}\n` + rows.map((r) => `${r.mint === SOL_MINT ? 'SOL' : r.mint}: ${r.amount}${r.usd !== undefined ? ` ($${r.usd.toFixed(2)})` : ''}`).join('\n'));
+        }
+        catch (e) {
+            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.",
+        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 {
+            return ok({ enabled: true, ...(await api.points(w)) });
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 503)
+                return ok({ enabled: false, wallet: w, note: 'The points engine is not enabled yet. Swaps made now still pay the Potswap fee; points start with Season 1.' });
+            return fail(msg(e));
+        }
+    });
+    server.registerTool('get_leaderboard', {
+        title: 'Leaderboard',
+        description: 'Top wallets by Potswap fee paid, with POT allocated.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok({ enabled: true, ...(await api.leaderboard()) });
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 503)
+                return ok({ enabled: false, note: 'The points engine is not enabled yet.' });
+            return fail(msg(e));
+        }
+    });
+    return server;
+}
+const quoteShape = {
+    inputMint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).describe('Mint of the token to sell (SOL = So11111111111111111111111111111111111111112)'),
+    outputMint: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{32,44}$/).describe('Mint of the token to buy'),
+    amount: z.number().positive().describe('Amount in UI units of the input token (1 = 1 SOL)'),
+    slippageBps: z.number().int().min(1).max(5000).optional().describe('Fixed slippage in bps; omit for auto'),
+};
+async function buildQuote(api, a) {
+    const [inTok, outTok] = await Promise.all([api.token(a.inputMint), api.token(a.outputMint)]);
+    const inAmountRaw = toRaw(a.amount, inTok.decimals);
+    const o = await api.order({ inputMint: a.inputMint, outputMint: a.outputMint, amount: inAmountRaw, slippageBps: a.slippageBps });
+    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, router: o.router, requestId: o.requestId,
+        expiresAt: o.expireAt ?? null,
+    };
+}
+function slimToken(t) {
+    return { mint: t.id, symbol: t.symbol, name: t.name, decimals: t.decimals, usdPrice: t.usdPrice, mcap: t.mcap, liquidity: t.liquidity, isVerified: t.isVerified ?? false };
+}
+function msg(e) { return e instanceof Error ? e.message : String(e); }
+function rpcBalances(rpcUrl) {
+    return async (wallet) => {
+        const conn = new Connection(rpcUrl, 'confirmed');
+        const owner = new PublicKey(wallet);
+        const out = {};
+        const [lamports, spl, t22] = await Promise.all([
+            conn.getBalance(owner),
+            conn.getParsedTokenAccountsByOwner(owner, { programId: new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA') }),
+            conn.getParsedTokenAccountsByOwner(owner, { programId: new PublicKey('TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb') }).catch(() => ({ value: [] })),
+        ]);
+        out[SOL_MINT] = lamports / 1e9;
+        for (const { account } of [...spl.value, ...t22.value]) {
+            const info = account.data.parsed?.info;
+            const ui = Number(info?.tokenAmount?.uiAmount ?? 0);
+            if (info && ui > 0)
+                out[info.mint] = (out[info.mint] ?? 0) + ui;
+        }
+        return out;
+    };
+}
+export { SOL_MINT, USDC_MINT };

package/dist/shared/errors.d.ts

@@ -0,0 +1,5 @@
+import type { OrderResponse } from './lib-types.js';
+/** Maps /order error codes (transaction empty) to user copy. */
+export declare function describeOrderError(o: Pick<OrderResponse, 'errorCode' | 'errorMessage'>): string;
+/** User-facing error copy. Every message states whether funds were debited. */
+export declare function friendlyError(msg: string): string;

package/dist/shared/errors.js

@@ -0,0 +1,24 @@
+/** Maps /order error codes (transaction empty) to user copy. */
+export function describeOrderError(o) {
+    const map = {
+        1: 'Insufficient balance for this swap.',
+        2: 'Not enough SOL to pay network fees. Keep at least 0.01 SOL.',
+        3: 'Amount too small for this route. Try a larger amount.',
+    };
+    return (o.errorCode && map[o.errorCode]) || o.errorMessage || 'Could not build the swap. Try again.';
+}
+/** User-facing error copy. Every message states whether funds were debited. */
+export function friendlyError(msg) {
+    const m = msg.toLowerCase();
+    if (m.includes('user rejected') || m.includes('rejected the request'))
+        return 'You rejected the transaction in your wallet. No funds were debited.';
+    if (m.includes('slippage') || m.includes('0x1771') || m.includes('6001'))
+        return 'Price moved beyond your slippage tolerance. No funds were debited. Try again or raise slippage in settings.';
+    if (m.includes('insufficient'))
+        return 'Insufficient balance for this swap, including network fees. No funds were debited.';
+    if (m.includes('expired') || m.includes('-1005') || m.includes('block height'))
+        return 'The quote expired before the transaction landed. No funds were debited. Please try again.';
+    if (m.includes('failed to land') || m.includes('-1000'))
+        return 'The network was congested and the transaction did not land. No funds were debited. Please try again.';
+    return `${msg} If the transaction did not land, no funds were debited.`;
+}

package/dist/shared/lib-types.d.ts

@@ -0,0 +1,42 @@
+export interface Token {
+    id: string;
+    symbol: string;
+    name: string;
+    icon?: string;
+    decimals: number;
+    isVerified?: boolean;
+    usdPrice?: number;
+}
+export interface OrderResponse {
+    router: 'metis' | 'jupiterz' | 'dflow' | 'okx' | string;
+    inAmount: string;
+    outAmount: string;
+    inUsdValue?: number;
+    outUsdValue?: number;
+    priceImpactPct?: string | number;
+    slippageBps?: number;
+    feeBps?: number;
+    feeMint?: string;
+    platformFee?: {
+        amount: string;
+        feeBps: number;
+        feeMint: string;
+    };
+    transaction: string | null;
+    requestId: string;
+    lastValidBlockHeight?: number;
+    expireAt?: string;
+    errorCode?: number;
+    errorMessage?: string;
+    mode?: string;
+    transactionVersion?: number;
+}
+export interface ExecuteResponse {
+    status: 'Success' | 'Failed';
+    signature?: string;
+    code: number;
+    error?: string;
+    totalInputAmount?: string;
+    totalOutputAmount?: string;
+}
+export type SwapStage = 'idle' | 'signing' | 'sending' | 'confirming' | 'success' | 'failed';

package/dist/shared/lib-types.js

@@ -0,0 +1 @@
+export {};

package/dist/shared/risk.d.ts

@@ -0,0 +1,15 @@
+import type { TerminalToken } from './types.js';
+export type Tone = 'good' | 'warn' | 'bad' | 'muted';
+export interface Badge {
+    key: string;
+    icon: string;
+    label: string;
+    tone: Tone;
+    tip: string;
+}
+export declare const TOP_HOLDER_WARN = 30;
+export declare const DEV_BALANCE_WARN = 10;
+export declare const DEV_MINTS_WARN = 20;
+export declare function riskBadges(t: Pick<TerminalToken, 'audit' | 'isVerified'>): Badge[];
+/** 0 (safe) … 3 (danger) summary used for row colouring. */
+export declare function riskLevel(badges: Badge[]): number;

package/dist/shared/risk.js

@@ -0,0 +1,35 @@
+export const TOP_HOLDER_WARN = 30; // %
+export const DEV_BALANCE_WARN = 10; // %
+export const DEV_MINTS_WARN = 20;
+export function riskBadges(t) {
+    const a = t.audit;
+    if (!a)
+        return [{ key: 'unaudited', icon: '?', label: 'Unaudited', tone: 'muted', tip: 'No audit data for this token yet.' }];
+    const out = [];
+    out.push(a.mintAuthorityDisabled
+        ? { key: 'mint', icon: '🔒', label: 'Mint revoked', tone: 'good', tip: 'Nobody can mint more supply.' }
+        : { key: 'mint', icon: '🖨️', label: 'Mintable', tone: 'bad', tip: 'The creator can still mint new supply.' });
+    out.push(a.freezeAuthorityDisabled
+        ? { key: 'freeze', icon: '🧊', label: 'Freeze revoked', tone: 'good', tip: 'Token accounts cannot be frozen.' }
+        : { key: 'freeze', icon: '❄️', label: 'Freezable', tone: 'bad', tip: 'The creator can freeze your tokens.' });
+    if (a.topHoldersPercentage !== undefined && a.topHoldersPercentage > TOP_HOLDER_WARN) {
+        out.push({ key: 'top', icon: '⚠', label: `Top holders ${a.topHoldersPercentage.toFixed(0)}%`, tone: 'warn', tip: 'A few wallets hold a large share of the supply.' });
+    }
+    if (a.devBalancePercentage !== undefined && a.devBalancePercentage > DEV_BALANCE_WARN) {
+        out.push({ key: 'dev', icon: '🧑‍💻', label: `Dev holds ${a.devBalancePercentage.toFixed(0)}%`, tone: 'warn', tip: 'The deployer wallet still holds a large share.' });
+    }
+    if (a.devMints !== undefined && a.devMints > DEV_MINTS_WARN) {
+        out.push({ key: 'serial', icon: '🔁', label: `Dev launched ${a.devMints.toLocaleString()} tokens`, tone: 'bad', tip: 'This deployer has launched many tokens before.' });
+    }
+    if (t.isVerified)
+        out.push({ key: 'verified', icon: '✓', label: 'Verified', tone: 'good', tip: 'On Jupiter\'s verified list.' });
+    return out;
+}
+/** 0 (safe) … 3 (danger) summary used for row colouring. */
+export function riskLevel(badges) {
+    const bad = badges.filter((b) => b.tone === 'bad').length;
+    const warn = badges.filter((b) => b.tone === 'warn').length;
+    if (badges.some((b) => b.key === 'unaudited'))
+        return 1;
+    return Math.min(3, bad * 2 + warn);
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,50 @@
+export interface TokenStats {
+    priceChange?: number;
+    buyVolume?: number;
+    sellVolume?: number;
+    numBuys?: number;
+    numSells?: number;
+    numTraders?: number;
+    numNetBuyers?: number;
+}
+export interface TokenAudit {
+    mintAuthorityDisabled?: boolean;
+    freezeAuthorityDisabled?: boolean;
+    topHoldersPercentage?: number;
+    devBalancePercentage?: number;
+    devMigrations?: number;
+    devMints?: number;
+}
+export interface TerminalToken {
+    id: string;
+    symbol: string;
+    name: string;
+    icon?: string;
+    decimals: number;
+    usdPrice?: number;
+    mcap?: number;
+    fdv?: number;
+    liquidity?: number;
+    holderCount?: number;
+    organicScore?: number;
+    organicScoreLabel?: string;
+    launchpad?: string;
+    graduatedPool?: string;
+    graduatedAt?: string;
+    firstPool?: {
+        id: string;
+        createdAt: string;
+    };
+    createdAt?: string;
+    tags?: string[];
+    audit?: TokenAudit;
+    stats5m?: TokenStats;
+    stats1h?: TokenStats;
+    stats6h?: TokenStats;
+    stats24h?: TokenStats;
+    isVerified?: boolean;
+    /** Added by the graduating list: estimated bonding-curve progress 0–1. */
+    bondingProgress?: number;
+}
+export type ListKind = 'new' | 'trending' | 'top' | 'graduating';
+export declare const LIST_KINDS: ListKind[];

package/dist/shared/types.js

@@ -0,0 +1 @@
+export const LIST_KINDS = ['new', 'trending', 'top', 'graduating'];

package/dist/wallet.d.ts

@@ -0,0 +1,10 @@
+import { type VersionedTransaction } from '@solana/web3.js';
+export interface Signer {
+    publicKey: string;
+    sign(tx: VersionedTransaction): VersionedTransaction;
+}
+export declare function parseSecret(raw: string): Uint8Array;
+export declare function loadSigner(opts: {
+    privateKey?: string;
+    keypairPath?: string;
+}): Signer | null;

package/dist/wallet.js

@@ -0,0 +1,48 @@
+// PRD P10.2/P10.9 — load the agent's keypair; the secret never leaves this module.
+import { readFileSync } from 'node:fs';
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+import { registerSecret } from './redact.js';
+export function parseSecret(raw) {
+    const s = raw.trim();
+    if (s.startsWith('[')) {
+        const arr = JSON.parse(s);
+        if (!Array.isArray(arr) || arr.length !== 64 || !arr.every((n) => Number.isInteger(n) && n >= 0 && n < 256))
+            throw new Error('Keypair JSON must be an array of 64 bytes');
+        return Uint8Array.from(arr);
+    }
+    let bytes;
+    try {
+        bytes = bs58.decode(s);
+    }
+    catch {
+        throw new Error('Private key is not valid base58 or a JSON byte array');
+    }
+    if (bytes.length === 64)
+        return bytes;
+    if (bytes.length === 32)
+        return Keypair.fromSeed(bytes).secretKey;
+    throw new Error(`Private key has ${bytes.length} bytes; expected 64 (or a 32-byte seed)`);
+}
+export function loadSigner(opts) {
+    let raw = opts.privateKey;
+    if (!raw && opts.keypairPath) {
+        try {
+            raw = readFileSync(opts.keypairPath, 'utf8');
+        }
+        catch {
+            throw new Error(`Cannot read keypair file at SOLANA_KEYPAIR_PATH`);
+        }
+    }
+    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; },
+    };
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@potswap_io/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Potswap MCP server: best-route Solana swaps for AI agents, non-custodial, earns POT.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "potswap-mcp": "dist/index.js"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "sync-shared": "node scripts/sync-shared.mjs",
+    "prepublishOnly": "npm run sync-shared && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nahargeva/potswap"
+  },
+  "homepage": "https://www.potswap.io",
+  "keywords": [
+    "mcp",
+    "solana",
+    "swap",
+    "jupiter",
+    "ai-agent",
+    "potswap",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@solana/web3.js": "^1.99.0",
+    "bs58": "^6.0.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  }
+}