@dritan/mcp 0.3.1 → 0.5.0

package/.env.example

@@ -1,5 +1,6 @@
 DRITAN_API_KEY=
 DRITAN_BASE_URL=https://us-east.dritan.dev
+DRITAN_CONTROL_BASE_URL=https://api.dritan.dev
 DRITAN_WS_BASE_URL=wss://us-east.dritan.dev
 SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
 METEORA_THS_BASE_URL=https://ths.dritan.dev

package/README.md

@@ -6,7 +6,8 @@ MCP server for personal agents to use `dritan-sdk` for market data and swap exec
 
 - Node.js 20+
 - `solana-keygen` available in `PATH`
-- Dritan API key (`DRITAN_API_KEY`)
+- Optional: Dritan API key (`DRITAN_API_KEY`) for market/swap tools.
+- For paid onboarding without an existing key, use x402 tools.
 
 ## Setup
 
@@ -41,6 +42,10 @@ npm run build && npm start
 - `wallet_create_local`
 - `wallet_get_address`
 - `wallet_get_balance`
+- `wallet_transfer_sol`
+- `x402_get_pricing`
+- `x402_create_api_key_quote`
+- `x402_create_api_key`
 - `dritan_health`
 - `market_get_snapshot`
 - `token_search`
@@ -74,7 +79,11 @@ npm run build && npm start
 - Wallets default to `~/.config/dritan-mcp/wallets`.
 - Private keys never leave local files; only public address/signature are returned.
 - `swap_sign_and_broadcast` signs locally, then broadcasts via Dritan.
+- Agent onboarding without `DRITAN_API_KEY` should present two options:
+  - Option 1: paid x402 flow (`x402_get_pricing` -> `x402_create_api_key_quote` -> user funds agent wallet -> `wallet_transfer_sol` -> `x402_create_api_key`).
+  - Option 2: user gets a free key at `https://dritan.dev`.
 - `token_get_ohlcv_chart` returns a shareable chart URL plus a ready-to-send markdown image snippet.
+- `token_get_ohlcv_chart` supports `chartType: "line-volume" | "candlestick"` (default is `line-volume`).
 - Ticker workflow for chart requests: `token_search` -> extract mint -> `token_get_ohlcv` or `token_get_ohlcv_chart`.
 - If users ask for `$WIF` style symbols, always resolve mint with `token_search` first.
 - If Solana CLI is missing, run `system_check_prereqs` and follow returned install steps.

package/dist/index.js

@@ -7,9 +7,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { DritanClient, MeteoraThsClient, } from "dritan-sdk";
-import { Connection, Keypair, VersionedTransaction, clusterApiUrl } from "@solana/web3.js";
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, VersionedTransaction, clusterApiUrl, } from "@solana/web3.js";
 import { z } from "zod";
 const DEFAULT_WALLET_DIR = join(homedir(), ".config", "dritan-mcp", "wallets");
+const LAMPORTS_PER_SOL = 1_000_000_000;
 const STREAM_DEXES = [
     "pumpamm",
     "pumpfun",
@@ -31,20 +32,42 @@ const server = new Server({
         tools: {},
     },
     instructions: [
-        "This server requires a DRITAN_API_KEY environment variable to use market data and swap tools.",
-        "Get your API key at https://dritan.dev and configure it:",
+        "This server supports two API-key onboarding options when DRITAN_API_KEY is missing:",
+        "1) x402 pay-per-use key flow: create wallet, receive SOL, create quote, forward payment, claim key.",
+        "2) Free key flow: user creates a free API key at https://dritan.dev.",
+        "After key is obtained, set DRITAN_API_KEY and continue with market/swap tools.",
+        "Suggested setup command:",
         "  claude mcp add dritan-mcp -e DRITAN_API_KEY=<your-key> -- npx @dritan/mcp@latest",
-        "Without the key, only system_check_prereqs and wallet tools (create_local, get_address, get_balance) will work.",
     ].join("\n"),
 });
+function getControlBaseUrl() {
+    return process.env.DRITAN_CONTROL_BASE_URL ?? "https://api.dritan.dev";
+}
+function missingApiKeyError() {
+    return new Error([
+        "Missing DRITAN_API_KEY in environment.",
+        "Option 1 (paid): use x402 tools (x402_get_pricing, x402_create_api_key_quote, x402_create_api_key) and wallet tools.",
+        "Option 2 (free): create a free key at https://dritan.dev and set DRITAN_API_KEY.",
+    ].join(" "));
+}
 function getDritanClient() {
     const apiKey = process.env.DRITAN_API_KEY;
     if (!apiKey) {
-        throw new Error("Missing DRITAN_API_KEY in environment");
+        throw missingApiKeyError();
     }
     return new DritanClient({
         apiKey,
         baseUrl: process.env.DRITAN_BASE_URL,
+        controlBaseUrl: getControlBaseUrl(),
+        wsBaseUrl: process.env.DRITAN_WS_BASE_URL,
+    });
+}
+function getX402Client() {
+    return new DritanClient({
+        // x402 endpoints are public; SDK constructor still needs a string.
+        apiKey: process.env.DRITAN_API_KEY ?? "x402_public_endpoints",
+        baseUrl: process.env.DRITAN_BASE_URL,
+        controlBaseUrl: getControlBaseUrl(),
         wsBaseUrl: process.env.DRITAN_WS_BASE_URL,
     });
 }
@@ -61,7 +84,7 @@ async function searchTokens(client, query, options) {
     // Backward-compatible fallback for environments where dritan-sdk hasn't been upgraded yet.
     const apiKey = process.env.DRITAN_API_KEY;
     if (!apiKey) {
-        throw new Error("Missing DRITAN_API_KEY in environment");
+        throw missingApiKeyError();
     }
     const baseUrl = process.env.DRITAN_BASE_URL ?? "https://us-east.dritan.dev";
     const url = new URL("/token/search", baseUrl);
@@ -89,6 +112,65 @@ async function searchTokens(client, query, options) {
         return { ok: true, raw: text };
     }
 }
+async function x402GetPricing(client) {
+    const sdkMethod = client.getX402Pricing;
+    if (typeof sdkMethod === "function") {
+        return await sdkMethod.call(client);
+    }
+    const url = new URL("/v1/x402/pricing", getControlBaseUrl());
+    const response = await fetch(url.toString(), { method: "GET" });
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`x402 pricing failed (${response.status}): ${text}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+async function x402CreateQuote(client, input) {
+    const sdkMethod = client.createX402ApiKeyQuote;
+    if (typeof sdkMethod === "function") {
+        return await sdkMethod.call(client, input);
+    }
+    const url = new URL("/v1/x402/api-keys/quote", getControlBaseUrl());
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`x402 quote failed (${response.status}): ${text}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+async function x402CreateApiKey(client, input) {
+    const sdkMethod = client.createX402ApiKey;
+    if (typeof sdkMethod === "function") {
+        return await sdkMethod.call(client, input);
+    }
+    const url = new URL("/v1/x402/api-keys", getControlBaseUrl());
+    const response = await fetch(url.toString(), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+    });
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`x402 create key failed (${response.status}): ${text}`);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
 async function checkDritanHealth() {
     const baseUrl = process.env.DRITAN_BASE_URL ?? "https://us-east.dritan.dev";
     const url = new URL("/health", baseUrl).toString();
@@ -117,7 +199,7 @@ function formatChartLabel(ts) {
         return String(ts);
     return date.toISOString().replace("T", " ").slice(0, 16);
 }
-function buildOhlcvChartUrl(mint, timeframe, bars, width, height) {
+function buildLineVolumeOhlcvChartUrl(mint, timeframe, bars, width, height) {
     const labels = bars.map((bar) => formatChartLabel(bar.time));
     const closeSeries = bars.map((bar) => Number(bar.close.toFixed(12)));
     const volumeSeries = bars.map((bar) => Number(bar.volume.toFixed(12)));
@@ -166,6 +248,66 @@ function buildOhlcvChartUrl(mint, timeframe, bars, width, height) {
     // so pinning `v=4` prevents runtime render errors like "Cannot read properties of undefined (reading 'options')".
     return `https://quickchart.io/chart?w=${width}&h=${height}&f=png&v=4&c=${encoded}`;
 }
+function buildCandlestickOhlcvChartUrl(mint, timeframe, bars, width, height) {
+    const labels = bars.map((bar) => formatChartLabel(bar.time));
+    const candles = bars.map((bar, index) => ({
+        x: labels[index],
+        o: Number(bar.open.toFixed(12)),
+        h: Number(bar.high.toFixed(12)),
+        l: Number(bar.low.toFixed(12)),
+        c: Number(bar.close.toFixed(12)),
+    }));
+    const volumeSeries = bars.map((bar) => Number(bar.volume.toFixed(12)));
+    const volumeColors = bars.map((bar) => bar.close >= bar.open ? "rgba(16,185,129,0.25)" : "rgba(239,68,68,0.25)");
+    const config = {
+        type: "candlestick",
+        data: {
+            labels,
+            datasets: [
+                {
+                    label: "OHLC",
+                    data: candles,
+                    color: {
+                        up: "#10b981",
+                        down: "#ef4444",
+                        unchanged: "#94a3b8",
+                    },
+                },
+                {
+                    type: "bar",
+                    label: "Volume",
+                    data: volumeSeries,
+                    backgroundColor: volumeColors,
+                    borderWidth: 0,
+                    yAxisID: "volume",
+                },
+            ],
+        },
+        options: {
+            plugins: {
+                legend: { display: true },
+                title: {
+                    display: true,
+                    text: `${mint} ${timeframe.toUpperCase()} Candlestick`,
+                },
+            },
+            scales: {
+                x: { type: "category" },
+                y: { type: "linear", position: "left" },
+                volume: { type: "linear", position: "right", grid: { drawOnChartArea: false } },
+            },
+        },
+    };
+    const encoded = encodeURIComponent(JSON.stringify(config));
+    // Pin Chart.js v4 for stable scale behavior and financial chart rendering.
+    return `https://quickchart.io/chart?w=${width}&h=${height}&f=png&v=4&c=${encoded}`;
+}
+function buildOhlcvChartUrl(chartType, mint, timeframe, bars, width, height) {
+    if (chartType === "candlestick") {
+        return buildCandlestickOhlcvChartUrl(mint, timeframe, bars, width, height);
+    }
+    return buildLineVolumeOhlcvChartUrl(mint, timeframe, bars, width, height);
+}
 function getPlatformInstallHint(binary) {
     switch (process.platform) {
         case "darwin":
@@ -276,6 +418,31 @@ const walletPathSchema = z.object({
 const walletBalanceSchema = walletPathSchema.extend({
     rpcUrl: z.string().url().optional(),
 });
+const walletTransferSchema = z
+    .object({
+    walletPath: z.string().min(1),
+    toAddress: z.string().min(32),
+    lamports: z.number().int().positive().optional(),
+    sol: z.number().positive().optional(),
+    rpcUrl: z.string().url().optional(),
+})
+    .refine((v) => v.lamports != null || v.sol != null, {
+    message: "Either lamports or sol is required",
+    path: ["lamports"],
+});
+const x402QuoteSchema = z.object({
+    durationMinutes: z.number().int().min(1).max(60 * 24 * 30),
+    name: z.string().min(1).max(120).optional(),
+    scopes: z.array(z.string().min(1).max(120)).max(64).optional(),
+    payerWallet: z.string().min(32).max(80).optional(),
+});
+const x402CreateApiKeySchema = z.object({
+    quoteId: z.string().min(1),
+    paymentTxSignature: z.string().min(40),
+    payerWallet: z.string().min(32).max(80).optional(),
+    name: z.string().min(1).max(120).optional(),
+    scopes: z.array(z.string().min(1).max(120)).max(64).optional(),
+});
 const marketSnapshotSchema = z.object({
     mint: z.string().min(1),
     mode: z.enum(["price", "metadata", "risk", "first-buyers", "aggregated"]).default("aggregated"),
@@ -300,6 +467,7 @@ const tokenOhlcvSchema = z.object({
     timeTo: z.number().int().positive().optional(),
 });
 const tokenOhlcvChartSchema = tokenOhlcvSchema.extend({
+    chartType: z.enum(["line-volume", "candlestick"]).default("line-volume"),
     includeActive: z.boolean().default(true),
     maxPoints: z.number().int().min(10).max(500).default(120),
     width: z.number().int().min(300).max(2000).default(1200),
@@ -397,6 +565,58 @@ const tools = [
             },
         },
     },
+    {
+        name: "wallet_transfer_sol",
+        description: "Send SOL from a local wallet to a destination wallet (used in x402 paid key flow).",
+        inputSchema: {
+            type: "object",
+            required: ["walletPath", "toAddress"],
+            properties: {
+                walletPath: { type: "string" },
+                toAddress: { type: "string" },
+                lamports: { type: "number", description: "Integer lamports to transfer" },
+                sol: { type: "number", description: "SOL amount to transfer (used when lamports is not provided)" },
+                rpcUrl: { type: "string" },
+            },
+        },
+    },
+    {
+        name: "x402_get_pricing",
+        description: "Get x402 pricing and receiver wallet for paid time-limited API keys.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "x402_create_api_key_quote",
+        description: "Create an x402 payment quote for a time-limited API key (returns quoteId, receiverWallet, and exact SOL amount).",
+        inputSchema: {
+            type: "object",
+            required: ["durationMinutes"],
+            properties: {
+                durationMinutes: { type: "number", description: "Minutes for key validity (1 to 43200)." },
+                name: { type: "string", description: "Optional key name." },
+                payerWallet: { type: "string", description: "Optional payer wallet to lock quote payer." },
+                scopes: { type: "array", items: { type: "string" }, description: "Optional scopes." },
+            },
+        },
+    },
+    {
+        name: "x402_create_api_key",
+        description: "Claim a paid x402 API key using quoteId and payment transaction signature.",
+        inputSchema: {
+            type: "object",
+            required: ["quoteId", "paymentTxSignature"],
+            properties: {
+                quoteId: { type: "string" },
+                paymentTxSignature: { type: "string" },
+                payerWallet: { type: "string" },
+                name: { type: "string" },
+                scopes: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
     {
         name: "dritan_health",
         description: "Check data plane health endpoint via Dritan SDK.",
@@ -515,7 +735,7 @@ const tools = [
     },
     {
         name: "token_get_ohlcv_chart",
-        description: "Build a shareable chart URL from token OHLCV candles so agents can send an actual chart in chat (resolve ticker with token_search first).",
+        description: "Build a shareable chart URL from token OHLCV candles so agents can send an actual chart in chat (resolve ticker with token_search first). Supports line-volume or candlestick charts.",
         inputSchema: {
             type: "object",
             required: ["mint", "timeframe"],
@@ -523,6 +743,11 @@ const tools = [
                 mint: { type: "string" },
                 timeframe: { type: "string", description: "e.g. 1m, 5m, 1h, 1d" },
                 timeTo: { type: "number" },
+                chartType: {
+                    type: "string",
+                    enum: ["line-volume", "candlestick"],
+                    description: "Chart style. Default line-volume.",
+                },
                 includeActive: { type: "boolean" },
                 maxPoints: { type: "number" },
                 width: { type: "number" },
@@ -754,6 +979,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const apiKeySet = !!process.env.DRITAN_API_KEY;
                 return ok({
                     ready: solanaCli.ok && apiKeySet,
+                    readyForX402Onboarding: solanaCli.ok,
                     checks: [
                         solanaCli,
                         {
@@ -761,11 +987,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             name: "DRITAN_API_KEY",
                             hint: apiKeySet
                                 ? "API key is configured."
-                                : "Missing DRITAN_API_KEY. Get your key at https://dritan.dev and set it as an environment variable.",
+                                : "Missing DRITAN_API_KEY. You can either use x402 onboarding tools or get a free key at https://dritan.dev.",
                         },
                     ],
                     nextAction: !apiKeySet
-                        ? "Set DRITAN_API_KEY environment variable. Get your key at https://dritan.dev"
+                        ? "Choose one: (1) x402 paid onboarding flow with wallet tools, or (2) get a free key at https://dritan.dev and set DRITAN_API_KEY."
                         : !solanaCli.ok
                             ? "Install Solana CLI using installHint, then retry wallet_create_local."
                             : "Environment ready.",
@@ -799,6 +1025,81 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     sol: lamports / 1_000_000_000,
                 });
             }
+            case "wallet_transfer_sol": {
+                const input = walletTransferSchema.parse(args);
+                const walletPath = resolve(input.walletPath);
+                const keypair = loadKeypairFromPath(walletPath);
+                const rpcUrl = getRpcUrl(input.rpcUrl);
+                const conn = new Connection(rpcUrl, "confirmed");
+                const lamportsRaw = input.lamports != null ? input.lamports : Math.round((input.sol ?? 0) * LAMPORTS_PER_SOL);
+                if (!Number.isSafeInteger(lamportsRaw) || lamportsRaw <= 0) {
+                    throw new Error("Transfer amount must be a positive safe integer number of lamports.");
+                }
+                const toPubkey = new PublicKey(input.toAddress);
+                const latest = await conn.getLatestBlockhash("confirmed");
+                const tx = new Transaction({
+                    feePayer: keypair.publicKey,
+                    recentBlockhash: latest.blockhash,
+                }).add(SystemProgram.transfer({
+                    fromPubkey: keypair.publicKey,
+                    toPubkey,
+                    lamports: lamportsRaw,
+                }));
+                tx.sign(keypair);
+                const signature = await conn.sendRawTransaction(tx.serialize(), {
+                    skipPreflight: false,
+                    maxRetries: 3,
+                });
+                const confirmation = await conn.confirmTransaction({
+                    signature,
+                    blockhash: latest.blockhash,
+                    lastValidBlockHeight: latest.lastValidBlockHeight,
+                }, "confirmed");
+                if (confirmation.value.err) {
+                    throw new Error(`Transfer failed: ${JSON.stringify(confirmation.value.err)}`);
+                }
+                return ok({
+                    walletPath,
+                    fromAddress: keypair.publicKey.toBase58(),
+                    toAddress: toPubkey.toBase58(),
+                    rpcUrl,
+                    lamports: lamportsRaw,
+                    sol: lamportsRaw / LAMPORTS_PER_SOL,
+                    signature,
+                    explorerUrl: `https://solscan.io/tx/${signature}`,
+                });
+            }
+            case "x402_get_pricing": {
+                const client = getX402Client();
+                const pricing = await x402GetPricing(client);
+                return ok({
+                    ...(pricing ?? {}),
+                    onboardingOptions: [
+                        "Option 1 (paid x402): create wallet -> receive user SOL -> x402 quote -> forward payment -> claim key.",
+                        "Option 2 (free): user gets API key at https://dritan.dev and provides it as DRITAN_API_KEY.",
+                    ],
+                });
+            }
+            case "x402_create_api_key_quote": {
+                const input = x402QuoteSchema.parse(args);
+                const client = getX402Client();
+                const quote = await x402CreateQuote(client, input);
+                return ok({
+                    ...(quote ?? {}),
+                    nextSteps: [
+                        "If user picked paid flow, ensure agent has a local wallet (wallet_create_local + wallet_get_address).",
+                        "User funds the agent wallet.",
+                        "Transfer quoted SOL amount to receiver wallet using wallet_transfer_sol.",
+                        "Claim key with x402_create_api_key using returned tx signature.",
+                    ],
+                });
+            }
+            case "x402_create_api_key": {
+                const input = x402CreateApiKeySchema.parse(args);
+                const client = getX402Client();
+                const created = await x402CreateApiKey(client, input);
+                return ok(created);
+            }
             case "market_get_snapshot": {
                 const input = marketSnapshotSchema.parse(args);
                 const client = getDritanClient();
@@ -868,10 +1169,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (trimmedBars.length === 0) {
                     throw new Error(`No OHLCV data available for ${input.mint} (${input.timeframe})`);
                 }
-                const chartUrl = buildOhlcvChartUrl(input.mint, input.timeframe, trimmedBars, input.width, input.height);
+                const chartUrl = buildOhlcvChartUrl(input.chartType, input.mint, input.timeframe, trimmedBars, input.width, input.height);
                 return ok({
                     mint: input.mint,
                     timeframe: input.timeframe,
+                    chartType: input.chartType,
                     points: trimmedBars.length,
                     chartUrl,
                     markdown: `![${input.mint} ${input.timeframe} chart](${chartUrl})`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dritan/mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "MCP server for Dritan SDK market data and local Solana wallet swap execution",
@@ -34,7 +34,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.4",
     "@solana/web3.js": "^1.98.4",
-    "dritan-sdk": "^0.6.0",
+    "dritan-sdk": "^0.9.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {