@pnlmarket/mcp-server 0.4.0

package/dist/lib/output.js

@@ -0,0 +1,175 @@
+// ─── PNL MCP — terminal output helpers ───────────────────────────
+//
+// Every tool returns text that Claude Code renders as part of its
+// reply. Plain console.log-style output reads like a log file in
+// that context. This module gives every tool a consistent visual
+// rhythm:
+//
+//   - Bold one-line answer first (so the user can stop reading early
+//     if that's all they wanted)
+//   - Markdown tables for structured data (Claude Code renders them)
+//   - Truncated addresses with full base58 in a code block for copy
+//   - ASCII status badges ([ok], [!], [locked], [live]) — no emoji
+//     per the standing brand rule
+//   - A "→ Next:" hint at the end so the agent and user both know
+//     the typical follow-up
+//
+// All helpers return strings. Compose with template literals or
+// section() + join('\n\n').
+// ─── Address / hash formatting ───────────────────────────────────
+/**
+ * Shorten a base58 pubkey for display. Keeps the first 6 and last 4
+ * characters — enough to be visually distinguishable without taking
+ * a full line.
+ *
+ *   truncAddress("9ot5o7tbtUit8j75ivdjxoUCGaY7uCcUDootdKuVhECH")
+ *   // → "9ot5o7…hECH"
+ */
+export function truncAddress(addr, leading = 6, trailing = 4) {
+    if (!addr || addr.length <= leading + trailing + 1)
+        return addr;
+    return `${addr.slice(0, leading)}…${addr.slice(-trailing)}`;
+}
+/**
+ * Format SOL from lamports with reasonable precision. Returns null
+ * when the amount is below display threshold so callers can omit
+ * the row entirely.
+ */
+export function formatSol(lamports) {
+    if (lamports == null)
+        return null;
+    const n = typeof lamports === 'string' ? Number(lamports) : lamports;
+    if (!Number.isFinite(n))
+        return null;
+    const sol = n / 1e9;
+    if (sol < 0.0001)
+        return null;
+    if (sol < 1)
+        return `${sol.toFixed(3)} SOL`;
+    if (sol < 100)
+        return `${sol.toFixed(2)} SOL`;
+    return `${sol.toFixed(1)} SOL`;
+}
+// ─── Badges & status markers ─────────────────────────────────────
+//
+// Plain-ASCII bracketed tokens read as visual cues without being
+// emoji. They survive copy-paste, terminals without unicode font
+// fallback, and screen readers.
+export const Badge = {
+    ok: '[ok]',
+    warn: '[!]',
+    err: '[err]',
+    locked: '[locked]',
+    unlocked: '[unlocked]',
+    live: '[live]',
+    ended: '[ended]',
+    pending: '[pending]',
+    draft: '[draft]',
+};
+// ─── Structural primitives ───────────────────────────────────────
+/**
+ * Render a one-line bold "headline" answer. The user can read just
+ * this and stop. Subsequent text is "if you want details".
+ */
+export function headline(text) {
+    return `**${text}**`;
+}
+/**
+ * Two-column key/value table. Used by pnl_wallet, pnl_get_market,
+ * etc. for structured "here's what we know" responses.
+ */
+export function kvTable(rows) {
+    const filtered = rows.filter((r) => r[1] != null && String(r[1]).length > 0);
+    if (filtered.length === 0)
+        return '';
+    return [
+        '| | |',
+        '|---|---|',
+        ...filtered.map(([k, v]) => `| **${k}** | ${v} |`),
+    ].join('\n');
+}
+/**
+ * Generic markdown table with headers + rows. Pads cells with one
+ * space on each side so the source reads cleanly in case the user
+ * is on a renderer that doesn't pretty-print markdown tables.
+ */
+export function table(headers, rows) {
+    const separator = headers.map(() => '---');
+    const all = [headers, separator, ...rows];
+    return all.map((r) => `| ${r.join(' | ')} |`).join('\n');
+}
+/**
+ * Code block — useful for pubkeys, tx signatures, IPFS CIDs,
+ * mnemonics, file paths. Claude Code renders these as monospace
+ * with a copy button.
+ */
+export function code(content, lang = '') {
+    return `\`\`\`${lang}\n${content}\n\`\`\``;
+}
+/**
+ * Inline code span — for short identifiers in the middle of a
+ * sentence.
+ */
+export function inline(content) {
+    return `\`${content}\``;
+}
+/**
+ * Blockquote — used for market descriptions, manifesto-style
+ * pull-quotes, important warnings.
+ */
+export function quote(text) {
+    return text
+        .trim()
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n');
+}
+/**
+ * Markdown heading — H3 by default since tool output isn't a doc.
+ */
+export function heading(text, level = 3) {
+    return `${'#'.repeat(level)} ${text}`;
+}
+/**
+ * Horizontal rule. Use sparingly to separate big sections.
+ */
+export const hr = '---';
+/**
+ * Action hint at the bottom of an output. Standardized so users
+ * recognize the pattern.
+ */
+export function next(hint) {
+    return `→ ${hint}`;
+}
+/**
+ * Wrap a tool result in the MCP content-block shape so callers
+ * don't have to repeat the boilerplate. Joins parts with two
+ * newlines so each section gets a paragraph break.
+ */
+export function reply(...parts) {
+    const text = parts
+        .filter((p) => typeof p === 'string' && p.length > 0)
+        .join('\n\n');
+    return { content: [{ type: 'text', text }] };
+}
+// ─── Common domain-specific formatters ───────────────────────────
+/**
+ * Render a Solana address: truncated for the eye, plus a code block
+ * with the full thing for copy. Optionally include a Solscan link.
+ */
+export function addressBlock(addr, opts = {}) {
+    const label = opts.label ?? 'Address';
+    const lines = [`**${label}:** \`${truncAddress(addr)}\``];
+    lines.push(code(addr));
+    if (opts.solscan) {
+        lines.push(`[View on Solscan](https://solscan.io/account/${addr})`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Render a market URL with its truncated id and the full URL on a
+ * separate line for copy.
+ */
+export function marketLink(marketId, baseUrl) {
+    return `${baseUrl}/market/${marketId}`;
+}

package/dist/lib/passphrase.d.ts

@@ -0,0 +1,16 @@
+export interface PromptOptions {
+    /** Title shown on the dialog */
+    title?: string;
+    /** Prompt text inside the dialog */
+    prompt?: string;
+    /** If true, ask twice and require they match (for setup) */
+    confirm?: boolean;
+}
+/**
+ * Request the wallet passphrase from the user, never via the agent.
+ *
+ * Throws with a helpful message if no path is available so the agent
+ * can relay the failure clearly ("set PNL_PASSPHRASE in your Claude
+ * Code mcp config and restart").
+ */
+export declare function promptPassphrase(opts?: PromptOptions): string;

package/dist/lib/passphrase.js

@@ -0,0 +1,57 @@
+import { execFileSync } from 'node:child_process';
+function fromEnv() {
+    const raw = process.env.PNL_PASSPHRASE;
+    if (raw && raw.length > 0)
+        return raw;
+    return null;
+}
+function macosPrompt(prompt, title) {
+    // osascript escapes: we use a heredoc-style applescript and inject
+    // strings as bash args (execFileSync arrays are safe from shell injection).
+    const script = `display dialog "${prompt.replace(/"/g, '\\"')}" default answer "" with hidden answer with title "${title.replace(/"/g, '\\"')}"
+return text returned of result`;
+    const out = execFileSync('osascript', ['-e', script], { encoding: 'utf8' });
+    return out.trim();
+}
+function linuxPrompt(prompt, _title) {
+    const out = execFileSync('zenity', ['--password', '--title', _title], { encoding: 'utf8' });
+    return out.trim();
+}
+/**
+ * Request the wallet passphrase from the user, never via the agent.
+ *
+ * Throws with a helpful message if no path is available so the agent
+ * can relay the failure clearly ("set PNL_PASSPHRASE in your Claude
+ * Code mcp config and restart").
+ */
+export function promptPassphrase(opts = {}) {
+    const envValue = fromEnv();
+    if (envValue)
+        return envValue;
+    const title = opts.title || 'PNL Wallet';
+    const prompt = opts.prompt || 'Enter your PNL wallet passphrase:';
+    try {
+        if (process.platform === 'darwin') {
+            const first = macosPrompt(prompt, title);
+            if (opts.confirm) {
+                const again = macosPrompt('Re-enter to confirm:', title);
+                if (first !== again)
+                    throw new Error('passphrases do not match');
+            }
+            return first;
+        }
+        if (process.platform === 'linux') {
+            const first = linuxPrompt(prompt, title);
+            if (opts.confirm) {
+                const again = linuxPrompt('Re-enter to confirm:', title);
+                if (first !== again)
+                    throw new Error('passphrases do not match');
+            }
+            return first;
+        }
+    }
+    catch (e) {
+        throw new Error(`Couldn't open the native passphrase dialog (${e instanceof Error ? e.message : String(e)}). Set the PNL_PASSPHRASE env var in your Claude Code mcp config and restart — see apps/mcp/README.md for the snippet.`);
+    }
+    throw new Error(`Native passphrase dialog isn't supported on ${process.platform} yet. Set the PNL_PASSPHRASE env var in your Claude Code mcp config and restart.`);
+}

package/dist/lib/pnl-api.d.ts

@@ -0,0 +1,65 @@
+export type MarketStatus = 'active' | 'yesWins' | 'noWins' | 'expired' | 'refund' | 'all';
+export interface MarketSummary {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    stage?: string;
+    tokenSymbol?: string;
+    targetPool?: string;
+    founderDisplayName?: string;
+    founderUsername?: string;
+    founderWallet?: string;
+    totalParticipants?: number;
+    yesPercentage?: number | null;
+    noPercentage?: number | null;
+    yesPool?: number | null;
+    noPool?: number | null;
+    totalYesStake?: number | null;
+    totalNoStake?: number | null;
+    poolBalance?: string | number | null;
+    poolProgressPercentage?: number;
+    status?: string;
+    displayStatus?: string;
+    phase?: string;
+    resolution?: string;
+    timeLeft?: string;
+    expiryTime?: string;
+    marketAddress?: string;
+    pumpFunTokenAddress?: string | null;
+    tokenMint?: string | null;
+    projectImageUrl?: string | null;
+}
+export interface MarketListResponse {
+    markets: MarketSummary[];
+    total?: number;
+    page?: number;
+    limit?: number;
+    hasMore?: boolean;
+    totalPages?: number;
+}
+/**
+ * Browse live (or historical) conviction markets.
+ *
+ * Wraps GET /api/markets/list with the documented query params. Returns
+ * the same payload the API returns — the tool layer formats it for the
+ * agent. Public, no auth, IP-rate-limited 60/min by the server.
+ */
+export declare function browseMarkets(params: {
+    status?: MarketStatus;
+    page?: number;
+    limit?: number;
+}): Promise<MarketListResponse>;
+/**
+ * Fetch a single market by id.
+ *
+ * Wraps GET /api/markets/<id>. Returns the full market object — name,
+ * description, founder, pools, YES%, status, expiry, the on-chain market
+ * address, and any computed display fields.
+ */
+export declare function getMarket(id: string): Promise<MarketSummary>;
+/**
+ * Public URL the user can open in a browser to view a market. Used to
+ * thread back into the tool output so agents can hand the user a link.
+ */
+export declare function marketUrl(id: string): string;

package/dist/lib/pnl-api.js

@@ -0,0 +1,89 @@
+// ─── PNL public read API client ──────────────────────────────────
+//
+// Thin wrappers over the two public read endpoints documented at
+// https://docs.pnl.market/docs/build/public-api. The MCP server never
+// holds keys, so this module is fetch-only.
+//
+// Base URL is configurable via PNL_API_BASE_URL — defaults to the live
+// site. Tests / staging / devnet pointed deployments can override.
+const DEFAULT_BASE_URL = 'https://pnl.market';
+function getBaseUrl() {
+    const raw = process.env.PNL_API_BASE_URL?.trim();
+    if (!raw)
+        return DEFAULT_BASE_URL;
+    // Strip trailing slash so we can append paths cleanly.
+    return raw.endsWith('/') ? raw.slice(0, -1) : raw;
+}
+async function fetchJson(url) {
+    const res = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            // Identify ourselves so the rate limiter can see who's calling.
+            'User-Agent': 'pnl-mcp-server/0.1.0 (+https://docs.pnl.market)',
+        },
+    });
+    if (!res.ok) {
+        let body = '';
+        try {
+            body = await res.text();
+        }
+        catch {
+            /* ignore */
+        }
+        throw new Error(`PNL API ${res.status} ${res.statusText} for ${url}${body ? ` — ${body.slice(0, 200)}` : ''}`);
+    }
+    const json = (await res.json());
+    // The API wraps everything in {success, data}. If we see that shape,
+    // unwrap; otherwise pass through (for future endpoints that don't wrap).
+    if (typeof json === 'object' &&
+        json !== null &&
+        'success' in json &&
+        'data' in json) {
+        const env = json;
+        if (!env.success) {
+            throw new Error(`PNL API returned success=false for ${url}${env.error ? ` — ${env.error}` : ''}`);
+        }
+        return env.data;
+    }
+    return json;
+}
+/**
+ * Browse live (or historical) conviction markets.
+ *
+ * Wraps GET /api/markets/list with the documented query params. Returns
+ * the same payload the API returns — the tool layer formats it for the
+ * agent. Public, no auth, IP-rate-limited 60/min by the server.
+ */
+export async function browseMarkets(params) {
+    const qs = new URLSearchParams();
+    if (params.status)
+        qs.set('status', params.status);
+    if (params.page != null)
+        qs.set('page', String(params.page));
+    if (params.limit != null)
+        qs.set('limit', String(params.limit));
+    const url = `${getBaseUrl()}/api/markets/list${qs.toString() ? `?${qs.toString()}` : ''}`;
+    return fetchJson(url);
+}
+/**
+ * Fetch a single market by id.
+ *
+ * Wraps GET /api/markets/<id>. Returns the full market object — name,
+ * description, founder, pools, YES%, status, expiry, the on-chain market
+ * address, and any computed display fields.
+ */
+export async function getMarket(id) {
+    if (!id)
+        throw new Error('marketId is required');
+    // Encode just in case someone passes a market address that contains
+    // characters that need encoding (unlikely for base58 but cheap to be safe).
+    const url = `${getBaseUrl()}/api/markets/${encodeURIComponent(id)}`;
+    return fetchJson(url);
+}
+/**
+ * Public URL the user can open in a browser to view a market. Used to
+ * thread back into the tool output so agents can hand the user a link.
+ */
+export function marketUrl(id) {
+    return `${getBaseUrl()}/market/${encodeURIComponent(id)}`;
+}

package/dist/lib/sign.d.ts

@@ -0,0 +1,40 @@
+import { Connection, Keypair, TransactionSignature, SendOptions } from '@solana/web3.js';
+/** Decode a base64-encoded unsigned tx, partial-sign with the local
+ *  Keypair, and return the fully-serialized signed transaction ready
+ *  to be sent via Connection.sendRawTransaction.
+ *
+ *  Uses partialSign rather than sign so the tx can carry additional
+ *  signers later (none today, but the shape generalizes). */
+export declare function signSerializedTx(txBase64: string, keypair: Keypair): Buffer;
+export interface SendAndConfirmOptions extends SendOptions {
+    /** Block-height based timeout for confirmation. Defaults to 60s.
+     *  Solana blockhashes expire after ~60-90s, so this is the
+     *  hard-stop for "will the tx still land". */
+    confirmTimeoutMs?: number;
+}
+export interface SendResult {
+    signature: TransactionSignature;
+    /** Slot the tx landed in, if confirmation succeeded. */
+    slot?: number;
+}
+/** Send a raw (already-signed) transaction and wait for it to confirm.
+ *  Throws if the tx fails on-chain or if confirmation times out. */
+export declare function sendAndConfirm(rawTx: Buffer | Uint8Array, connection?: Connection, opts?: SendAndConfirmOptions): Promise<SendResult>;
+/** Build a fresh nonce in the canonical "<unix-ms>-<hex>" format the
+ *  /api/mcp/* endpoints expect. */
+export declare function freshNonce(): string;
+/** Sign a UTF-8 challenge string with the local Keypair and return a
+ *  base58 signature suitable for the {walletAddress, nonce, signature}
+ *  payload sent to /api/mcp/profile, /api/mcp/markets/complete-*. */
+export declare function signChallenge(challenge: string, keypair: Keypair): string;
+/** Re-export the canonical challenge string format so the MCP and the
+ *  backend stay in lockstep. Mirrors apps/web/src/lib/mcp-auth.ts.
+ *  When payloadHash is supplied, the sig binds to the request body —
+ *  see signedRequestHash() below. */
+export declare function challenge(kind: 'build-create' | 'build-vote' | 'build-claim' | 'complete-create' | 'complete-vote' | 'complete-claim' | 'profile', fingerprint: string, nonce: string, payloadHash?: string): string;
+/** SHA-256 of the request body minus auth fields (walletAddress,
+ *  nonce, signature) — first 16 hex chars. Both MCP-side (before
+ *  signing) and backend (verifying) compute the same hash so the sig
+ *  is bound to the exact payload. Tampering with any payload field
+ *  invalidates the sig. */
+export declare function signedRequestHash(body: Record<string, unknown>): string;

package/dist/lib/sign.js

@@ -0,0 +1,126 @@
+import { Transaction, } from '@solana/web3.js';
+import nacl from 'tweetnacl';
+import bs58 from 'bs58';
+import { createHash } from 'node:crypto';
+import { getConnection } from './wallet.js';
+// ─── PNL MCP — transaction signing + send helpers ─────────────────
+//
+// The autosign create / vote flows fetch an unsigned transaction from
+// the PNL backend (base64-encoded), sign it locally with the user's
+// Keypair, then send it to the Solana cluster via our RPC.
+//
+// Keeping the surface small: one helper for partial-signing a
+// base64 transaction, one for send-and-confirm, one for signing a
+// raw challenge string (used by the sig-auth endpoints).
+/** Decode a base64-encoded unsigned tx, partial-sign with the local
+ *  Keypair, and return the fully-serialized signed transaction ready
+ *  to be sent via Connection.sendRawTransaction.
+ *
+ *  Uses partialSign rather than sign so the tx can carry additional
+ *  signers later (none today, but the shape generalizes). */
+export function signSerializedTx(txBase64, keypair) {
+    const buf = Buffer.from(txBase64, 'base64');
+    const tx = Transaction.from(buf);
+    tx.partialSign(keypair);
+    return tx.serialize();
+}
+/** Send a raw (already-signed) transaction and wait for it to confirm.
+ *  Throws if the tx fails on-chain or if confirmation times out. */
+export async function sendAndConfirm(rawTx, connection = getConnection(), opts = {}) {
+    const { confirmTimeoutMs = 60_000, ...sendOpts } = opts;
+    const signature = await connection.sendRawTransaction(rawTx, {
+        skipPreflight: false,
+        preflightCommitment: 'confirmed',
+        maxRetries: 3,
+        ...sendOpts,
+    });
+    // Use the latest blockhash + lastValidBlockHeight so confirmation
+    // gives up exactly when the tx becomes unlandable, rather than
+    // burning the full timeout on an already-expired tx.
+    const latest = await connection.getLatestBlockhash('confirmed');
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), confirmTimeoutMs);
+    try {
+        const result = await connection.confirmTransaction({
+            signature,
+            blockhash: latest.blockhash,
+            lastValidBlockHeight: latest.lastValidBlockHeight,
+            abortSignal: ctrl.signal,
+        }, 'confirmed');
+        if (result.value.err) {
+            throw new Error(`transaction failed on-chain: ${JSON.stringify(result.value.err)}`);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    // getSignatureStatuses for the landed slot — best-effort; never
+    // block the caller on this.
+    let slot;
+    try {
+        const status = await connection.getSignatureStatuses([signature]);
+        slot = status.value[0]?.slot;
+    }
+    catch {
+        /* ignore */
+    }
+    return { signature, slot };
+}
+/** Build a fresh nonce in the canonical "<unix-ms>-<hex>" format the
+ *  /api/mcp/* endpoints expect. */
+export function freshNonce() {
+    const ms = Date.now();
+    const random = nacl.randomBytes(8);
+    const hex = Buffer.from(random).toString('hex');
+    return `${ms}-${hex}`;
+}
+/** Sign a UTF-8 challenge string with the local Keypair and return a
+ *  base58 signature suitable for the {walletAddress, nonce, signature}
+ *  payload sent to /api/mcp/profile, /api/mcp/markets/complete-*. */
+export function signChallenge(challenge, keypair) {
+    const message = new TextEncoder().encode(challenge);
+    const signature = nacl.sign.detached(message, keypair.secretKey);
+    return bs58.encode(signature);
+}
+/** Re-export the canonical challenge string format so the MCP and the
+ *  backend stay in lockstep. Mirrors apps/web/src/lib/mcp-auth.ts.
+ *  When payloadHash is supplied, the sig binds to the request body —
+ *  see signedRequestHash() below. */
+export function challenge(kind, fingerprint, nonce, payloadHash) {
+    if (payloadHash) {
+        return `pnl-mcp:${kind}:${fingerprint}:${payloadHash}:${nonce}`;
+    }
+    return `pnl-mcp:${kind}:${fingerprint}:${nonce}`;
+}
+/** Canonical JSON: keys sorted, no whitespace, recursive. Matches
+ *  apps/web/src/lib/mcp-auth.ts (and JSON.stringify's handling of
+ *  `undefined`) so both sides hash identical bytes regardless of
+ *  whether the body has been through JSON serialization yet. */
+function canonicalJson(value) {
+    if (value === undefined)
+        return 'null';
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalJson).join(',') + ']';
+    }
+    const obj = value;
+    // Drop undefined-valued keys (mirrors JSON.stringify) so the body
+    // we hash before sending matches the body the backend receives.
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    return ('{' +
+        keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(obj[k])).join(',') +
+        '}');
+}
+/** SHA-256 of the request body minus auth fields (walletAddress,
+ *  nonce, signature) — first 16 hex chars. Both MCP-side (before
+ *  signing) and backend (verifying) compute the same hash so the sig
+ *  is bound to the exact payload. Tampering with any payload field
+ *  invalidates the sig. */
+export function signedRequestHash(body) {
+    const { walletAddress: _w, nonce: _n, signature: _s, ...payload } = body;
+    void _w;
+    void _n;
+    void _s;
+    return createHash('sha256').update(canonicalJson(payload), 'utf8').digest('hex').slice(0, 16);
+}

package/dist/lib/wallet.d.ts

@@ -0,0 +1,74 @@
+import { Connection, Keypair, PublicKey } from '@solana/web3.js';
+/** True iff the currently active RPC URL is our hosted MCP proxy.
+ *  Tools use this to decide whether to surface the BYO-Helius hint. */
+export declare function isUsingHostedRpc(): boolean;
+export interface PnlConfig {
+    autosignCapSol: number;
+    rpcUrl: string;
+}
+export declare function generateMnemonic(): string;
+export declare function isValidMnemonic(mnemonic: string): boolean;
+/** Returns a Solana Keypair derived from the BIP39 mnemonic at the
+ *  Phantom-compatible path m/44'/501'/0'/0'. */
+export declare function keypairFromMnemonic(mnemonic: string): Keypair;
+export declare function hasWallet(): boolean;
+export declare function getAddress(): string;
+export declare function isUnlocked(): boolean;
+export declare function unlockWith(passphrase: string, ttlMinutes?: number): {
+    address: string;
+};
+export declare function lock(): void;
+/** Returns the in-memory Keypair if the wallet is currently unlocked.
+ *  Throws with a "wallet locked" message otherwise. */
+export declare function requireUnlockedKeypair(): Keypair;
+export declare function unlockStatus(): {
+    unlocked: boolean;
+    secondsRemaining: number;
+};
+export interface CreatedWallet {
+    address: string;
+    /** 12-word BIP39 mnemonic. Shown to user ONCE — never stored on disk. */
+    mnemonic: string;
+}
+/** Generate a fresh BIP39 mnemonic + keypair, encrypt the secret with
+ *  the user's passphrase, write to disk. Returns the mnemonic so the
+ *  agent can display it once for the user to write down. */
+export declare function createWallet(passphrase: string): CreatedWallet;
+/** Restore a wallet from an existing BIP39 mnemonic. The user's
+ *  passphrase encrypts the derived secret on disk. */
+export declare function restoreWallet(mnemonic: string, passphrase: string, opts?: {
+    allowOverwrite?: boolean;
+}): {
+    address: string;
+};
+/** Writes the (currently unlocked) secret to a timestamped file under
+ *  ~/.config/pnl/exports/ with mode 0600 and returns the path. The
+ *  caller relays just the path to the agent — the secret never enters
+ *  the conversation transcript. */
+export declare function exportToFile(): {
+    path: string;
+    address: string;
+};
+/** Writes a freshly-generated BIP39 mnemonic to a 0600 file under
+ *  ~/.config/pnl/exports/ and returns the path. The mnemonic itself
+ *  is intentionally NOT returned in the function result — it never
+ *  enters the agent's reply transcript (which would flow through the
+ *  LLM API). The caller passes the user the path; the user `cat`s
+ *  the file locally and moves it to their password manager.
+ *
+ *  Same security model as exportToFile() for the secret key. */
+export declare function writeMnemonicToFile(mnemonic: string, address: string): {
+    path: string;
+};
+export declare function loadConfig(): PnlConfig;
+export declare function saveConfig(updates: Partial<PnlConfig>): PnlConfig;
+export declare function getRpcUrl(): string;
+export declare function getConnection(): Connection;
+export declare function getBalanceSol(pubkey: PublicKey): Promise<number>;
+export declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+export declare const WALLET_PATHS: {
+    readonly dir: string;
+    readonly wallet: string;
+    readonly config: string;
+    readonly exports: string;
+};