mcp-server-madeonsol 2.0.0 → 3.0.1

package/README.md

@@ -15,6 +15,8 @@ MCP server for [MadeOnSol](https://madeonsol.com) Solana KOL intelligence API. U
 
 > Real-time Solana trading intelligence: track 2,000+ KOL wallets with <3s latency on paid keys and x402 pay-per-call (free-tier live feeds are 5-min delayed), score 85K+ Pump.fun deployers, surface deshred deploy signals **~500ms before on-chain confirmation**, detect multi-KOL coordination, surface bundle-cohort holdings (which same-slot wallets still hold a token's supply), verify any wallet's CURRENT on-chain holdings straight from its token accounts, and stream every DEX trade across 9+ programs. Free tier: 200 requests/day across 40+ endpoints (live feeds 5-min delayed) — no signup payment. Get a key at [madeonsol.com/pricing](https://madeonsol.com/pricing).
 
+> **New in 3.0.0 — BREAKING for x402 (keyless) mode only: five env vars are now required and startup FAILS instead of silently degrading (security fix, SDK-01).** Set `X402_PAY_TO`, `X402_FEE_PAYER`, `X402_MAX_AMOUNT_ATOMIC`, `X402_MAX_TOTAL_AMOUNT_ATOMIC` and `SVM_RPC_URL` alongside `SVM_PRIVATE_KEY`. Before, keyless mode signed whatever Solana USDC amount, recipient and fee payer a 402 challenge asked for. Now every challenge is checked BEFORE signing against a trusted merchant `payTo`, a trusted facilitator `feePayer` (which must differ from your wallet), the USDC mint, `solana:5eykt…` mainnet, the `exact` scheme, a per-call cap and a lifetime cap. Use the canonical values in the keyless section below; caps must be at least `20000` (0.02 USDC) per call to reach every endpoint. The budget is per client instance / process: not wallet-wide, not shared between processes, reset on a new instance or restart. Keyless requires the base URL exactly `https://madeonsol.com`. **API-key (`msk_`) users: no change, no new config.** HTTP mode still refuses wallet signers (SEC-02, unchanged).
+
 > **New in 2.0.0 — BREAKING: HTTP mode now requires a separate token (security fix, SEC-02).** If you run this server with `MCP_TRANSPORT=http`, you must now also set `MCP_HTTP_TOKEN` (a random secret you generate) and send it as `Authorization: Bearer <token>` on **every** request, including `GET /health` and the server-card endpoint — previously, anything that could reach the bound port could call every tool using the operator's own API key with no authentication at all. HTTP mode is now hard-restricted to literal loopback (`127.0.0.1` / `::1`), rejects `Origin`/`X-Forwarded-*` headers and duplicate `Authorization`/`Host` headers outright, exposes only `POST /mcp` plus the two GET routes, and **refuses to start** if a wallet/payment signer is configured — HTTP mode can never carry a payer key. **If you use the default `stdio` transport (Claude Desktop, Cursor, most MCP clients), nothing changes — no action needed.** This is a single shared-operator-token fix, not a new multi-user or OAuth system; each HTTP caller still shares the operator's own MadeOnSol API key. Full writeup: `docs/audit/SEC02_PRIVATE_HTTP_MCP.md`.
 >
 > **New in 1.27.1 — the server now reports MCP `instructions`.** The `initialize` response's `instructions` field (operational guidance for the calling agent — distinct from this README/package description) was never set; directories that introspect the live server (Glama) reported "no recorded MCP instructions." No new tools; still 104 total.
@@ -99,7 +101,7 @@ Restart Claude Desktop and ask: *"What are KOLs buying right now?"*
 
 ## AI agent quickstart (x402 / pay-per-call)
 
-Building an autonomous agent? Skip the signup. Point a **funded Solana wallet** at the server and every tool call **auto-pays a micropayment** over [x402](https://x402.org) — no API key, no account, no rate-limit dance.
+Building an autonomous agent? Skip the signup. Configure a **funded Solana wallet** and an explicit payment budget. Paid tool calls authorize micropayments within that budget over [x402](https://x402.org) — no API key, no account, no rate-limit dance.
 
 ```json
 {
@@ -107,7 +109,12 @@ Building an autonomous agent? Skip the signup. Point a **funded Solana wallet**
     "madeonsol": {
       "command": "mcp-server-madeonsol",
       "env": {
-        "SVM_PRIVATE_KEY": "<base58 solana private key>"
+        "SVM_PRIVATE_KEY": "<base58 solana private key>",
+        "X402_PAY_TO": "GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR",
+        "X402_FEE_PAYER": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4",
+        "X402_MAX_AMOUNT_ATOMIC": "20000",
+        "X402_MAX_TOTAL_AMOUNT_ATOMIC": "1000000",
+        "SVM_RPC_URL": "https://<your-trusted-solana-rpc>"
       }
     }
   }
@@ -116,7 +123,7 @@ Building an autonomous agent? Skip the signup. Point a **funded Solana wallet**
 
 How it works:
 
-- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription, no quota.
+- The wallet behind `SVM_PRIVATE_KEY` settles each request as a **USDC micropayment on Solana** (~$0.005–$0.02 per call, settled on-chain). No subscription; the configured authorization budget bounds spending.
 - The keyless catalog covers **25 endpoints** — the latest additions: token candles ($0.01), almost-bonded ($0.01), top-traders ($0.02), cap-table ($0.02), sniper recent deploys ($0.01), token flow ($0.01), and deployer trajectory ($0.01).
 - The free **`madeonsol_discovery`** tool needs no auth and returns every endpoint with its exact per-call price — call it first to see what each tool costs.
 - Install the x402 peer deps alongside the server (only required for this mode):
@@ -129,6 +136,34 @@ How it works:
 
 Prefer a fixed monthly bill, free tier, or no wallet? Use the developer path below.
 
+## Required payment policy (breaking keyless upgrade)
+
+Keyless Solana payments require an explicit trusted merchant, facilitator and authorization budget. API-key mode is unchanged and takes precedence over a configured wallet.
+
+Only exact payments in mainnet USDC are permitted. Set the two addresses from your trusted operator configuration, independently of a server challenge. `SVM_RPC_URL` must be your trusted HTTPS RPC; there is no public RPC fallback. The agent wallet cannot also be the facilitator fee payer.
+
+| Setting | Meaning |
+|---|---|
+| `X402_PAY_TO` | Trusted merchant wallet receiving USDC |
+| `X402_FEE_PAYER` | Trusted facilitator wallet paying transaction fees |
+| `X402_MAX_AMOUNT_ATOMIC` | Maximum per payment, as a positive integer string |
+| `X402_MAX_TOTAL_AMOUNT_ATOMIC` | Lifetime authorization allowance, as a positive integer string |
+| `SVM_RPC_URL` | Explicit trusted HTTPS Solana RPC URL |
+
+USDC uses 6 decimals: `20000` = 0.02 USDC and `1000000` = 1 USDC. Choose limits that cover the endpoints you intend to use; these examples are not a price guarantee.
+
+**Canonical MadeOnSol values (Solana mainnet USDC).** Pinned here (GitHub + npm README) so you do not have to take them from a 402:
+- merchant `payTo` / `X402_PAY_TO`: `GLu63pRCYrp4BJu5P5ciYKxgeZFW9c8TJ8jWzK3TB9AR` (also shown on https://madeonsol.com/x402 and https://madeonsol.com/.well-known/x402)
+- facilitator `feePayer` / `X402_FEE_PAYER`: `2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4`. This is the fee payer of **PayAI**, the third-party facilitator MadeOnSol's Solana rail uses. If PayAI rotates it, keyless calls fail closed (the client refuses to sign) until you update this value; a MadeOnSol release will announce the new one.
+- prices: Solana legs are 5000–20000 atomic (0.005–0.02 USDC), so `maxAmountAtomic` / `X402_MAX_AMOUNT_ATOMIC` must be at least `20000` to reach every endpoint.
+
+The budget is per client instance / process: not wallet-wide, not shared between processes, reset when a new instance or process starts. Keyless mode requires the base URL exactly `https://madeonsol.com`.
+
+
+The allowance is reserved before concurrent calls can approve/sign. An unsigned denial releases it; entering payment creation retains it even if RPC, signing or the paid response fails. It measures **authorized attempts, not settled spend**. There is no automatic refund or payment replay. A timeout cannot undo a proof already sent.
+
+The allowance is per server process; restarting starts a new allowance. Reuse the running process. Multiple MCP servers or other clients sharing a wallet need an external shared budget. Missing/invalid keyless settings stop startup; wallet signing remains restricted to stdio. The payment attempt timeout defaults to 30 seconds.
+
 ## Authentication
 
 Two options (in priority order):
@@ -389,3 +424,4 @@ Free tier returns the full REST response shape on 40+ endpoints — real wallets
 ## License
 
 MIT
+

package/dist/index.js

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
+import { SolanaPaymentBudget, createSolanaPaidFetch, solanaPaymentPolicyFromConfig } from "./solana-payment.js";
 import { VERSION } from "./version.js";
 import { createPrivateHttpServer, readHttpConfig } from "./http-security.js";
 // MCP `initialize` response `instructions` field (ServerOptions.instructions in
@@ -55,22 +56,16 @@ async function initAuth() {
         return;
     }
     if (mode === "x402" && PRIVATE_KEY) {
+        const budget = new SolanaPaymentBudget(solanaPaymentPolicyFromConfig(key => process.env[key]));
         try {
-            const { wrapFetchWithPayment } = await import("@x402/fetch");
-            const { x402Client } = await import("@x402/core/client");
-            const { ExactSvmScheme } = await import("@x402/svm/exact/client");
-            const { createKeyPairSignerFromBytes } = await import("@solana/kit");
-            const { base58 } = await import("@scure/base");
-            const signer = await createKeyPairSignerFromBytes(base58.decode(PRIVATE_KEY));
-            const client = new x402Client();
-            client.register("solana:*", new ExactSvmScheme(signer));
-            paidFetch = wrapFetchWithPayment(fetch, client);
+            paidFetch = await createSolanaPaidFetch(PRIVATE_KEY, budget, BASE_URL);
             authMode = "x402";
-            console.error(`[madeonsol-mcp] x402 payments enabled, wallet: ${signer.address}`);
+            console.error("[madeonsol-mcp] x402 payments enabled with an explicit authorization budget");
             return;
         }
         catch (err) {
-            console.error("[madeonsol-mcp] x402 setup failed:", err);
+            // Never silently fall back to unauthenticated mode after a policy/setup failure.
+            throw new Error("[madeonsol-mcp] x402 setup failed", { cause: err });
         }
     }
     console.error("\n[madeonsol-mcp] No auth configured — every tool call will fail.\n" +
@@ -735,7 +730,7 @@ function registerTools(server) {
         server.tool("madeonsol_token_buyer_quality", "0–100 buyer-quality score for a token's first-buyer cohort. 5-min cached. Full breakdown on all tiers, incl. dump_cluster_count (3+ dump-cluster wallets in the first-20 → 94% historical dump rate vs 61% base) and recycled_early_buyer_count.", { mint: z.string().describe("Token mint address (base58)") }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ mint }) => ({
             content: [{ type: "text", text: await restQuery("GET", `/tokens/${encodeURIComponent(mint)}/buyer-quality`) }],
         }));
-        server.tool("madeonsol_token_risk", "Transparent 0–100 token rug-risk/safety score (higher = riskier). Returns a band (safe/caution/danger), an explainable factors[] array (mint authority, freeze authority, liquidity, transfer fee, token-2022, burn, launch cohort, deployer bond rate, KOL signal, blacklist) each with status/points/detail, and the raw inputs that produced the score. inputs now includes sniper_footprint — the slot-window launch-snipe rollup ({ buys, buyers, sol, supply_pct|null, sniper_wallet_buys, data_available, as_of } | null; buys landing in slots deploy-1..deploy+3). data_available=false means the mint isn't observable in the trade pipeline — NOT zero snipes; null means no rollup yet. Also returns a top-level dev block (deployer self-activity, null when the mint has no deployer-pipeline row): wallet, launchpad, deployed_at, create-tx self-buy snapshot (buy_sol / buy_tokens / buy_supply_pct), post-create rollup (bought_tokens_after — catches the same-second-separate-tx dev buy — sold_tokens, sold_sol, first_sell_at, last_sell_at), LIVE on-chain holdings (holdings_tokens, holdings_supply_pct — pump.fun 1B denominator, null elsewhere — wallet_empty: is the dev wallet empty NOW), and transferred_out (tokens left without a sell; null = unknown, never a guess). PRO/ULTRA only — BASIC receives HTTP 403.", { mint: z.string().describe("Token mint address (base58)") }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ mint }) => ({
+        server.tool("madeonsol_token_risk", "Transparent 0–100 token rug-risk/safety score (higher = riskier). Returns a band (safe/caution/danger), an explainable factors[] array (mint authority, freeze authority, liquidity, transfer fee, token-2022, burn, launch cohort, deployer bond rate, KOL signal, blacklist) each with status/points/detail, and the raw inputs that produced the score. inputs now includes sniper_footprint — the slot-window launch-snipe rollup ({ buys, buyers, sol, supply_pct|null, sniper_wallet_buys, data_available, as_of } | null; buys landing in slots deploy-1..deploy+3). data_available=false means the mint isn't observable in the trade pipeline — NOT zero snipes; null means no rollup yet. Also returns a top-level dev block (deployer self-activity, null when the mint has no deployer-pipeline row): wallet, launchpad, deployed_at, create-tx self-buy snapshot (buy_sol / buy_tokens / buy_supply_pct), post-create rollup (bought_tokens_after — catches the same-second-separate-tx dev buy — sold_tokens, sold_sol, first_sell_at, last_sell_at), LIVE on-chain holdings (holdings_tokens, holdings_supply_pct — pump.fun 1B denominator, null elsewhere — wallet_empty: is the dev wallet empty NOW), and transfer_status (suspected / none_detected / unknown; transferred_out is its deprecated boolean view). score_version v2 (2026-09-21): the LP factor is 'unknown' unless LP custody is verified — a token-supply burn (token_supply_burn_detected, alias burn_detected) is never LP evidence; assessment.unknown_inputs lists inputs that could not be observed (the band is then never 'safe') and assessment.not_assessed lists dimensions not measured for this token. A failed score-critical read returns HTTP 503 code risk_inputs_unavailable (retry) instead of a score. PRO/ULTRA only — BASIC receives HTTP 403.", { mint: z.string().describe("Token mint address (base58)") }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ mint }) => ({
             content: [{ type: "text", text: await restQuery("GET", `/tokens/${encodeURIComponent(mint)}/risk`) }],
         }));
         server.tool("madeonsol_token_bundle", "Bundle-cohort holdings for a token — which same-slot bundle wallets bought it and how much of supply they still hold (held_pct_of_supply). Rug/insider signal. Returns a `bundle` block (wallet_count, bundle_kind atomic_tx/same_slot/none, held_ratio, held_pct_of_supply [the headline — net held / circulating supply, null if unknown], fully_exited, buy_volume, tokens_held) plus a `wallets[]` array (rank, wallet, held_ratio, has_sold, atomic, is_kol). BASIC get the bundle block only (empty wallets[]); PRO adds top-10 flags-only wallets; ULTRA returns the full cohort with enriched identities (kol_name, win_rate, bot_confidence, tokens_held).", { mint: z.string().describe("Token mint address (base58)") }, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true }, async ({ mint }) => ({

package/dist/solana-payment.d.ts

@@ -0,0 +1,59 @@
+export declare const SOLANA_PAYMENT_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export declare const SOLANA_PAYMENT_ASSET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+interface ApprovedOffer {
+    scheme: "exact";
+    network: typeof SOLANA_PAYMENT_NETWORK;
+    asset: string;
+    payTo: string;
+    amount: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        feePayer: string;
+    };
+}
+interface ApprovedChallenge {
+    x402Version: 2;
+    resource: {
+        url: string;
+    };
+    accepts: ApprovedOffer[];
+}
+export interface SolanaPaymentProposal {
+    readonly url: string;
+    readonly network: string;
+    readonly asset: string;
+    readonly payTo: string;
+    readonly feePayer: string;
+    readonly amountAtomic: string;
+}
+export interface SolanaPaymentPolicy {
+    /** Trusted merchant wallet, obtained independently of a payment challenge. */
+    payTo: string;
+    /** Trusted facilitator wallet; must not be the paying agent's wallet. */
+    feePayer: string;
+    /** Positive atomic USDC integers (6 decimals); numbers are not accepted. */
+    maxAmountAtomic: string | bigint;
+    maxTotalAmountAtomic: string | bigint;
+    /** Explicit trusted HTTPS RPC; there is no public RPC fallback. */
+    rpcUrl: string;
+    /** Whole payment attempt deadline, default 30 seconds. */
+    timeoutMs?: number;
+    /** Optional additional approval; only literal true permits signing. */
+    beforePayment?: (proposal: SolanaPaymentProposal) => boolean | Promise<boolean>;
+}
+/** Lifetime authorization allowance, not settled spend. Share one long-lived instance.
+ * Retained after entering payment creation, including uncertain/failed outcomes.
+ */
+export declare class SolanaPaymentBudget {
+    #private;
+    readonly policy: Readonly<SolanaPaymentPolicy>;
+    constructor(policy: SolanaPaymentPolicy);
+    get authorizedAmountAtomic(): string;
+    select(envelope: unknown, requestUrl: string): ApprovedChallenge;
+    /** Atomic synchronous reservation before any approval/signing await. */
+    reserve(atomic: string): () => void;
+}
+export declare function solanaPaymentPolicyFromConfig(get: (key: string) => string | undefined): SolanaPaymentPolicy;
+/** One challenge and at most one paid request. No automatic payment replay. */
+export declare function createSolanaPaidFetch(privateKey: string, budget: SolanaPaymentBudget, baseUrl: string, transport?: typeof fetch): Promise<typeof fetch>;
+export {};

package/dist/solana-payment.js

@@ -0,0 +1,259 @@
+// Canonical source. Mirrored into the two Solana adapters by
+// packages/sync-solana-payment.mjs; CI rejects drift between published copies.
+export const SOLANA_PAYMENT_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export const SOLANA_PAYMENT_ASSET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+function fail(message) { throw new Error(`Solana payment policy: ${message}`); }
+const MAX_AMOUNT = (1n << 64n) - 1n;
+function amount(value) {
+    if (typeof value !== "bigint" && (typeof value !== "string" || !/^[1-9][0-9]{0,19}$/.test(value))) {
+        return fail("amount must be a positive atomic integer string or bigint");
+    }
+    const parsed = BigInt(value);
+    if (parsed <= 0n || parsed > MAX_AMOUNT)
+        return fail("amount exceeds uint64 range");
+    return parsed;
+}
+function wallet(value) {
+    if (typeof value !== "string" || !/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value))
+        return fail("invalid wallet address");
+    const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    let decoded = 0n;
+    for (const char of value)
+        decoded = decoded * 58n + BigInt(alphabet.indexOf(char));
+    const bytes = decoded === 0n ? 0 : Math.ceil(decoded.toString(16).length / 2);
+    if (decoded === 0n || bytes + (value.match(/^1*/)?.[0].length ?? 0) !== 32)
+        return fail("invalid wallet address");
+    return value;
+}
+function httpsUrl(value) {
+    if (typeof value !== "string")
+        return fail("invalid HTTPS URL");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return fail("invalid HTTPS URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash)
+        return fail("HTTPS URL without credentials or fragment required");
+    return url;
+}
+/** Lifetime authorization allowance, not settled spend. Share one long-lived instance.
+ * Retained after entering payment creation, including uncertain/failed outcomes.
+ */
+export class SolanaPaymentBudget {
+    policy;
+    #authorized = 0n;
+    #max;
+    #total;
+    constructor(policy) {
+        if (!policy)
+            fail("paymentPolicy is required for keyless payments");
+        const payTo = wallet(policy.payTo), feePayer = wallet(policy.feePayer);
+        this.#max = amount(policy.maxAmountAtomic);
+        this.#total = amount(policy.maxTotalAmountAtomic);
+        const rpcUrl = httpsUrl(policy.rpcUrl).href;
+        const timeoutMs = policy.timeoutMs ?? 30_000;
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647)
+            fail("invalid timeoutMs");
+        if (policy.beforePayment !== undefined && typeof policy.beforePayment !== "function")
+            fail("invalid beforePayment hook");
+        this.policy = Object.freeze({ payTo, feePayer, rpcUrl, timeoutMs,
+            maxAmountAtomic: this.#max.toString(), maxTotalAmountAtomic: this.#total.toString(), beforePayment: policy.beforePayment });
+    }
+    get authorizedAmountAtomic() { return this.#authorized.toString(); }
+    select(envelope, requestUrl) {
+        const challenge = envelope;
+        if (!challenge || challenge.x402Version !== 2 || !Array.isArray(challenge.accepts) ||
+            challenge.accepts.length < 1 || challenge.accepts.length > 32)
+            fail("unsupported payment challenge");
+        const request = httpsUrl(requestUrl);
+        if (challenge.resource !== undefined) {
+            const resource = httpsUrl(challenge.resource?.url);
+            // The current server advertises its path without the request query.
+            if (resource.origin !== request.origin || resource.pathname !== request.pathname ||
+                (resource.search && resource.search !== request.search))
+                fail("resource mismatch");
+        }
+        for (const offer of challenge.accepts) {
+            if (!offer || offer.scheme !== "exact" || offer.network !== SOLANA_PAYMENT_NETWORK ||
+                offer.asset !== SOLANA_PAYMENT_ASSET || offer.payTo !== this.policy.payTo ||
+                offer.extra?.feePayer !== this.policy.feePayer)
+                continue;
+            if (typeof offer.amount !== "string")
+                continue;
+            let cost;
+            try {
+                cost = amount(offer.amount);
+            }
+            catch {
+                continue;
+            }
+            if (cost > this.#max || !Number.isSafeInteger(offer.maxTimeoutSeconds) || offer.maxTimeoutSeconds <= 0)
+                continue;
+            // Rebuild instead of forwarding arbitrary remote fields/extensions to a signer.
+            const accepted = Object.freeze({ scheme: "exact", network: SOLANA_PAYMENT_NETWORK,
+                asset: SOLANA_PAYMENT_ASSET, payTo: this.policy.payTo, amount: cost.toString(),
+                maxTimeoutSeconds: offer.maxTimeoutSeconds, extra: Object.freeze({ feePayer: this.policy.feePayer }) });
+            return { x402Version: 2, resource: { url: request.href }, accepts: [accepted] };
+        }
+        return fail("no permitted exact mainnet USDC offer");
+    }
+    /** Atomic synchronous reservation before any approval/signing await. */
+    reserve(atomic) {
+        const cost = amount(atomic);
+        if (cost > this.#max || this.#authorized + cost > this.#total)
+            fail("authorization budget exceeded");
+        this.#authorized += cost;
+        let released = false;
+        return () => { if (!released) {
+            this.#authorized -= cost;
+            released = true;
+        } };
+    }
+}
+export function solanaPaymentPolicyFromConfig(get) {
+    const required = (name) => get(name) || fail(`${name} is required in keyless mode`);
+    return {
+        payTo: required("X402_PAY_TO"), feePayer: required("X402_FEE_PAYER"),
+        maxAmountAtomic: required("X402_MAX_AMOUNT_ATOMIC"), maxTotalAmountAtomic: required("X402_MAX_TOTAL_AMOUNT_ATOMIC"),
+        rpcUrl: required("SVM_RPC_URL"),
+    };
+}
+async function challengeBody(response) {
+    const header = response.headers.get("PAYMENT-REQUIRED");
+    if (header) {
+        if (header.length > 65_536)
+            fail("payment header too large");
+        // The protocol library decodes the header. Do not buffer an unrelated body.
+        void response.body?.cancel().catch(() => { });
+        return undefined;
+    }
+    if (!response.body)
+        return undefined;
+    const reader = response.body.getReader();
+    let size = 0;
+    const chunks = [];
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 65_536)
+                fail("payment challenge too large");
+            chunks.push(value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return fail("invalid payment challenge JSON");
+    }
+}
+/** One challenge and at most one paid request. No automatic payment replay. */
+export async function createSolanaPaidFetch(privateKey, budget, baseUrl, transport = fetch) {
+    const origin = httpsUrl(baseUrl).origin;
+    const { x402Client, x402HTTPClient } = await import("@x402/core/client");
+    const { ExactSvmScheme } = await import("@x402/svm/exact/client");
+    const { createKeyPairSignerFromBytes } = await import("@solana/kit");
+    const { base58 } = await import("@scure/base");
+    const signer = await createKeyPairSignerFromBytes(base58.decode(privateKey));
+    if (signer.address === budget.policy.feePayer)
+        fail("the agent wallet cannot pay facilitator gas");
+    return async (input, init) => {
+        const original = new Request(input, init);
+        if (httpsUrl(original.url).origin !== origin)
+            fail("request origin mismatch");
+        if (original.headers.has("PAYMENT-SIGNATURE") || original.headers.has("X-PAYMENT"))
+            fail("payment already attempted");
+        const controller = new AbortController();
+        const deadline = Date.now() + budget.policy.timeoutMs;
+        const check = () => {
+            if (Date.now() >= deadline && !controller.signal.aborted)
+                controller.abort(new Error("Solana payment timeout"));
+            controller.signal.throwIfAborted();
+        };
+        const abort = () => controller.abort(original.signal.reason);
+        original.signal.addEventListener("abort", abort, { once: true });
+        if (original.signal.aborted)
+            abort();
+        const timer = setTimeout(() => controller.abort(new Error("Solana payment timeout")), budget.policy.timeoutMs);
+        let onAbort = () => { };
+        const cancelled = new Promise((_, reject) => {
+            onAbort = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        const bounded = async (work) => {
+            const result = await Promise.race([work, cancelled]);
+            check();
+            return result;
+        };
+        let release;
+        let creating = false;
+        try {
+            check();
+            const request = new Request(original, { redirect: "error", signal: controller.signal });
+            const retry = request.clone();
+            const response = await bounded(transport(request));
+            if (response.status !== 402)
+                return response;
+            const client = new x402Client();
+            const http = new x402HTTPClient(client);
+            const body = await bounded(challengeBody(response));
+            // v2 normally uses PAYMENT-REQUIRED; accept the same validated envelope
+            // in JSON too. The upstream HTTP decoder's body fallback is v1-only.
+            let envelope;
+            try {
+                envelope = response.headers.has("PAYMENT-REQUIRED")
+                    ? http.getPaymentRequiredResponse(name => response.headers.get(name))
+                    : body;
+            }
+            catch {
+                return fail("invalid payment challenge header");
+            }
+            const required = budget.select(envelope, request.url);
+            const offer = required.accepts[0];
+            release = budget.reserve(offer.amount);
+            if (budget.policy.beforePayment) {
+                const approved = await bounded(Promise.resolve(budget.policy.beforePayment(Object.freeze({ url: request.url,
+                    network: offer.network, asset: offer.asset, payTo: offer.payTo,
+                    feePayer: budget.policy.feePayer, amountAtomic: offer.amount }))));
+                if (approved !== true)
+                    fail("payment declined");
+            }
+            check();
+            // RPC work can finish after our deadline. Guard the actual signer too so
+            // an abandoned payment creation cannot sign later in the background.
+            const guardedSigner = { ...signer, signTransactions: async (...args) => {
+                    check();
+                    return signer.signTransactions(...args);
+                } };
+            client.register(SOLANA_PAYMENT_NETWORK, new ExactSvmScheme(guardedSigner, { rpcUrl: budget.policy.rpcUrl }));
+            creating = true;
+            const payload = await bounded(client.createPaymentPayload(required));
+            check();
+            for (const [name, value] of Object.entries(http.encodePaymentSignatureHeader(payload)))
+                retry.headers.set(name, value);
+            return await bounded(transport(retry));
+        }
+        finally {
+            if (!creating)
+                release?.();
+            clearTimeout(timer);
+            original.signal.removeEventListener("abort", abort);
+            controller.signal.removeEventListener("abort", onAbort);
+        }
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "2.0.0";
+export declare const VERSION = "3.0.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED by ../gen-version.mjs (npm prebuild) from package.json. Do not edit.
-export const VERSION = "2.0.0";
+export const VERSION = "3.0.1";