@potswap_io/mcp 0.4.0 → 0.6.0

package/README.md

@@ -78,6 +78,7 @@ Use a dedicated agent wallet with only the funds you want the agent to control.
 | `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 |
+| `observe_publish`, `observe_query`, `observe_verify`, `observe_consume` | Signed, slot-anchored market observations on the open index: publish with your wallet, read everyone's with a per-publisher median, verify locally, record that you used one (earns the publisher Season 2 rewards). `limit_order_create` can trigger on the observation median (`priceSource: observations`) |
 | `get_launch_status` | Launch-pool meter (SOL / 500 target, from chain), season and day, fee split, unclaimed reward balances and the public claim ladder |
 | `get_price_history {mint, timeframe, limit}` | OHLCV candles from the token's top pool (`1m`…`1d`) |
 
@@ -124,7 +125,12 @@ Each swap carries Potswap's 2.5% integrator fee via Jupiter's referral program (
 
 **Season 0 (now, before the token):** 60% of the net fee fills the **launch pool**; when it reaches 500 SOL the POT token launches on its own liquidity pool. 20% of your net fee is set aside as your **reward balance** (in SOL): after launch it buys POT for you, when you say so (`claim now` at market, or a limit claim at your price). 20% runs the project. Every day you trade in Season 0 earns a slice of the **250M POT airdrop** (25% of supply), replayed day by day after launch: fee basis `fee^1.1`, capped at 10% of the day per wallet, round trips within 10 minutes count 25%.
 
-**Seasons 1+ (30 days each):** `20M × 0.85^(n−1)` POT per season shared daily by fee basis; 30% of the net fee buys and burns POT, 20% keeps feeding reward balances, 50% team and operations. Levels (Larva → Bee → Queen, up to ×1.25) persist across seasons. `get_points` shows your balance, level and season; `get_launch_status` shows the meter. Only protocol fees enter the pool: nothing can be deposited. Details: https://www.potswap.io
+**Seasons 1+ (30 days each):** `20M × 0.85^(n−1)` POT per season shared daily by fee basis; 30% of the net fee buys and burns POT, 20% keeps feeding reward balances, 50% team and operations. Levels (Larva → Bee → Queen, up to ×1.25) persist across seasons. `get_points` shows your balance, level and season; `get_launch_status` shows the meter. Only protocol fees enter the pool: nothing can be deposited. Full documentation: https://potswap-docs.pages.dev (every tool, configuration, limits, economy; also as /llms.txt for agents).
+
+## Also available
+
+- **`@potswap_io/sdk`** — the same engine as a typed library for bots, scripts and other agent frameworks. The MCP server is built on it.
+- **`@potswap_io/cli`** — the `potswap` command: `npx -y @potswap_io/cli quote SOL USDC 0.1`; swaps, transfers, wallet, points, launch meter, strategy management and `potswap daemon`.
 
 ## Development
 

package/dist/agentTools.d.ts

@@ -1,8 +1,8 @@
 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';
+import { type Config } from '@potswap_io/sdk';
+import { type TradeContext } from '@potswap_io/sdk';
+import { type Rpc } from '@potswap_io/sdk';
 /** Transaction-level RPC reads; injectable for tests. */
 export interface TxRpc {
     getSignatureStatus(sig: string): Promise<{

package/dist/agentTools.js

@@ -1,12 +1,12 @@
 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';
+import { JITOSOL_MINT, MSOL_MINT, NO_WALLET, SOL_MINT } from '@potswap_io/sdk';
+import { redact, redactValue } from '@potswap_io/sdk';
+import { createWallet } from '@potswap_io/sdk';
+import { executeSwap } from '@potswap_io/sdk';
+import { executeTransfer, rpcFromConnection } from '@potswap_io/sdk';
+import { mapSignatureStatus, normalizeHistory } from '@potswap_io/sdk';
+import { computePositions } from '@potswap_io/sdk';
 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}$/);

package/dist/index.js

@@ -2,9 +2,9 @@
 // Potswap MCP server over stdio, or `--daemon` to run strategies headlessly (PRD P11.11).
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer, VERSION } from './server.js';
-import { loadConfig } from './config.js';
-import { log } from './redact.js';
-import { createRuntime } from './runtime.js';
+import { loadConfig } from '@potswap_io/sdk';
+import { log } from '@potswap_io/sdk';
+import { createRuntime } from '@potswap_io/sdk';
 const config = loadConfig();
 const daemon = process.argv.includes('--daemon');
 const rt = createRuntime(config);

package/dist/observationTools.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Config, type TradeContext } from '@potswap_io/sdk';
+export interface ObservationToolDeps {
+    trade: TradeContext;
+    config: Config;
+    getSlot?: () => Promise<number>;
+}
+export declare function registerObservationTools(server: McpServer, deps: ObservationToolDeps): void;

package/dist/observationTools.js

@@ -0,0 +1,72 @@
+import { Connection } from '@solana/web3.js';
+import { z } from 'zod';
+import { NO_WALLET, OBSERVATION_KINDS, aggregate, redact, redactValue, signConsumption, signObservation, verifyObservation } from '@potswap_io/sdk';
+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}$/);
+const KIND = z.enum(OBSERVATION_KINDS);
+export function registerObservationTools(server, deps) {
+    const { trade, config } = deps;
+    const api = trade.api;
+    const getSlot = deps.getSlot ?? (() => new Connection(config.rpcUrl, 'confirmed').getSlot());
+    server.registerTool('observe_publish', {
+        title: 'Publish a signed observation',
+        description: 'Signs a market observation (price, liquidity, volume24h, holders, risk, route) with the agent wallet, anchored to the current slot, and posts it to the open Potswap index. Free; no funds move. Other agents can verify and consume it; verified consumption earns the publisher Season 2 rewards.',
+        inputSchema: { kind: KIND, mint: MINT, value: z.number().finite(), unit: z.string().min(1).max(16).optional(), source: z.string().min(1).max(64), ttlSec: z.number().int().min(10).max(86400).default(300), note: z.string().max(280).optional() },
+    }, async (a) => {
+        if (!trade.signer)
+            return fail(NO_WALLET);
+        try {
+            const slot = await getSlot();
+            const obs = signObservation(trade.signer, { ...a, slot });
+            const r = await api.publishObservation(obs);
+            return ok({ ...obs, ...r }, `Published ${a.kind} for ${a.mint.slice(0, 4)}… = ${a.value} ${obs.unit} (id ${obs.id}, slot ${slot}, ttl ${obs.ttlSec}s)${r.duplicate ? ' — already indexed' : ''}.`);
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('observe_query', {
+        title: 'Query observations',
+        description: 'Fresh observations from the open index, newest first, with a per-publisher median aggregate when mint and kind are given. Free, no wallet needed.',
+        inputSchema: { mint: MINT.optional(), kind: KIND.optional(), publisher: MINT.optional(), limit: z.number().int().min(1).max(200).default(50), includeStale: z.boolean().default(false) },
+    }, async (a) => {
+        try {
+            const r = await api.observations({ mint: a.mint, kind: a.kind, publisher: a.publisher, limit: a.limit, fresh: !a.includeStale });
+            const agg = a.mint && a.kind ? aggregate(r.items, a.kind, a.mint, r.now ?? Date.now()) : undefined;
+            return ok({ ...r, ...(agg ? { aggregate: agg } : {}) }, agg
+                ? `${agg.count} fresh ${a.kind} observation(s) from ${agg.publishers} publisher(s)${agg.median !== null ? ` · median ${agg.median} · spread ${agg.spreadPct?.toFixed(2)}%` : ''}`
+                : `${r.items.length} observation(s)` + (r.items.length ? `\n` + r.items.slice(0, 10).map((o) => `${new Date(o.observedAt).toISOString()} ${o.kind} ${o.mint.slice(0, 4)}… = ${o.value} ${o.unit} by ${o.publisher.slice(0, 4)}… (${o.source})`).join('\n') : ''));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+    server.registerTool('observe_verify', {
+        title: 'Verify an observation',
+        description: 'Checks an observation locally: schema, id, Ed25519 signature by its publisher, freshness; for price observations also the deviation from the current Potswap price.',
+        inputSchema: { observation: z.record(z.string(), z.unknown()) },
+    }, async ({ observation }) => {
+        const o = observation;
+        let referencePrice = null;
+        if (o.kind === 'price' && o.mint)
+            referencePrice = (await api.prices([o.mint]).catch(() => ({})))[o.mint] ?? null;
+        const v = verifyObservation(observation, { referencePrice });
+        return ok({ ...v, referencePrice }, v.ok ? `Valid${v.fresh ? ', fresh' : ', expired'}${v.deviationPct !== undefined && v.deviationPct !== null ? ` · ${v.deviationPct >= 0 ? '+' : ''}${v.deviationPct.toFixed(2)}% vs current price` : ''}.` : `Invalid: ${v.reason}`);
+    });
+    server.registerTool('observe_consume', {
+        title: 'Record that you used an observation',
+        description: 'Signs a receipt with the agent wallet saying this observation informed a decision. Receipts weight the publisher\'s Season 2 rewards. Free.',
+        inputSchema: { id: z.string().regex(/^[0-9a-f]{32}$/) },
+    }, async ({ id }) => {
+        if (!trade.signer)
+            return fail(NO_WALLET);
+        try {
+            const r = await api.consumeObservation(signConsumption(trade.signer, id));
+            return ok(r, `Receipt recorded for ${id} (publisher ${String(r.publisher).slice(0, 4)}…)${r.duplicate ? ' — already recorded' : ''}.`);
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    });
+}

package/dist/server.d.ts

@@ -1,13 +1,13 @@
 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 BalancesFn } from './trade.js';
-import { type Signer } from './wallet.js';
+import { type FetchFn } from '@potswap_io/sdk';
+import { SOL_MINT, USDC_MINT, type Config } from '@potswap_io/sdk';
+import { type BalancesFn } from '@potswap_io/sdk';
+import { type Signer } from '@potswap_io/sdk';
 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.4.0";
+import type { Rpc } from '@potswap_io/sdk';
+import type { StrategyStore } from '@potswap_io/sdk';
+import type { Scheduler } from '@potswap_io/sdk';
+export declare const VERSION = "0.6.0";
 export interface ServerDeps {
     config?: Config;
     signer?: Signer | null;
@@ -20,6 +20,8 @@ export interface ServerDeps {
     /** Transfer / transaction RPC surfaces; injectable for tests (P13). */
     rpc?: Rpc;
     txRpc?: TxRpc;
+    /** Current slot for observation anchoring; injectable for tests (P15). */
+    getSlot?: () => Promise<number>;
 }
 export declare function createServer(deps?: ServerDeps): McpServer;
 export { SOL_MINT, USDC_MINT };

package/dist/server.js

@@ -2,15 +2,16 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Connection, PublicKey } 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 { buildQuote, executeSwap } from './trade.js';
-import { redact, redactValue } from './redact.js';
-import { loadSigner } from './wallet.js';
-import { riskBadges, riskLevel } from './shared/risk.js';
+import { PotswapApi, ApiError } from '@potswap_io/sdk';
+import { loadConfig, NO_WALLET, SOL_MINT, USDC_MINT } from '@potswap_io/sdk';
+import { buildQuote, executeSwap } from '@potswap_io/sdk';
+import { redact, redactValue } from '@potswap_io/sdk';
+import { loadSigner } from '@potswap_io/sdk';
+import { riskBadges, riskLevel } from '@potswap_io/sdk';
 import { registerStrategyTools } from './strategies/tools.js';
 import { registerAgentTools } from './agentTools.js';
-export const VERSION = '0.4.0';
+import { registerObservationTools } from './observationTools.js';
+export const VERSION = '0.6.0';
 const ok = (data, summary) => ({
     content: [{ type: 'text', text: redact(summary ?? JSON.stringify(data, null, 2)) }], structuredContent: redactValue(data),
 });
@@ -148,6 +149,7 @@ export function createServer(deps = {}) {
     });
     registerAgentTools(server, { trade, config, rpc: deps.rpc, txRpc: deps.txRpc, schedulerActive: () => !!deps.scheduler?.active });
     registerStrategyTools(server, { trade, store: deps.strategyStore, scheduler: deps.scheduler });
+    registerObservationTools(server, { trade, config, getSlot: deps.getSlot });
     return server;
 }
 const quoteShape = {

package/dist/strategies/tools.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { TradeContext } from '../trade.js';
-import { type StrategyStore } from './store.js';
-import type { Scheduler } from './scheduler.js';
+import type { TradeContext } from '@potswap_io/sdk';
+import { type StrategyStore } from '@potswap_io/sdk';
+import type { Scheduler } from '@potswap_io/sdk';
 export interface StrategyDeps {
     trade: TradeContext;
     store?: StrategyStore;

package/dist/strategies/tools.js

@@ -1,8 +1,8 @@
 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';
+import { NO_WALLET } from '@potswap_io/sdk';
+import { redact, redactValue } from '@potswap_io/sdk';
+import { newId, SOL_MINT, nextRunAfter } from '@potswap_io/sdk';
+import { findStrategy, runsOf } from '@potswap_io/sdk';
 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) });
@@ -112,12 +112,14 @@ export function registerStrategyTools(server, deps) {
     });
     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.',
+        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. priceSource=observations uses the median of fresh signed observations instead of the price API.',
         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(),
+            priceSource: z.enum(['potswap', 'observations']).default('potswap').describe('observations = median of fresh signed observations from at least minPublishers publishers (PRD P15)'),
+            minPublishers: z.number().int().min(1).max(50).default(2),
             confirm: z.boolean().default(false),
         },
     }, async (a) => {
@@ -126,7 +128,7 @@ export function registerStrategyTools(server, deps) {
             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 };
+        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, ...(a.priceSource === 'observations' ? { priceSource: 'observations', minPublishers: a.minPublishers } : {}) };
         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 () => {

package/package.json

@@ -1,59 +1,57 @@
-{
-  "name": "@potswap_io/mcp",
-  "version": "0.4.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",
-  "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": "git+https://github.com/potswap-io/mcp.git"
-  },
-  "homepage": "https://www.potswap.io",
-  "keywords": [
-    "mcp",
-    "solana",
-    "swap",
-    "jupiter",
-    "ai-agent",
-    "potswap",
-    "model-context-protocol"
-  ],
-  "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"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.5",
-    "tsx": "^4.23.15",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.5",
-    "vitest": "^5.0.5"
-  },
-  "bugs": {
-    "url": "https://github.com/potswap-io/mcp/issues"
-  }
-}
+{
+  "name": "@potswap_io/mcp",
+  "version": "0.6.0",
+  "description": "Potswap MCP server: best-route Solana swaps, wallet, transfers, staking, DCA / rebalance / take-profit / limit strategies and POT rewards for AI agents. Non-custodial; built on @potswap_io/sdk.",
+  "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",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/potswap-io/mcp.git"
+  },
+  "homepage": "https://www.potswap.io",
+  "keywords": [
+    "mcp",
+    "solana",
+    "swap",
+    "jupiter",
+    "ai-agent",
+    "potswap",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@potswap_io/sdk": "^0.2.0",
+    "@solana/web3.js": "^1.99.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"
+  },
+  "bugs": {
+    "url": "https://github.com/potswap-io/mcp/issues"
+  }
+}