@hugen/plugin-x402-solana 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,117 @@
+# @hugen/plugin-x402-solana
+
+Solana USDC payments for ElizaOS agents via the [x402 protocol](https://www.x402.org/).
+
+**The first Solana x402 payment plugin for ElizaOS.** Enables agents to pay for any x402-protected API using Solana USDC — automatically handling 402 responses, signing SPL token transfers, and retrying with payment proof.
+
+## Why?
+
+The existing `@elizaos/plugin-x402` only supports EVM chains (Base, Ethereum). This plugin adds **Solana mainnet** support, giving agents access to the growing ecosystem of x402 APIs that accept Solana USDC.
+
+- 75+ x402 API endpoints already accept Solana USDC payments
+- Powered by `@x402/svm` (Coinbase official) and `@x402/fetch`
+- Zero configuration beyond a Solana private key
+
+## Installation
+
+```bash
+npm install @hugen/plugin-x402-solana
+```
+
+## Agent Configuration
+
+Add the plugin to your ElizaOS character config:
+
+```json
+{
+  "plugins": ["@hugen/plugin-x402-solana"],
+  "settings": {
+    "secrets": {
+      "SOLANA_PRIVATE_KEY": "your-base58-encoded-solana-keypair"
+    }
+  }
+}
+```
+
+The wallet needs USDC (SPL token) on Solana mainnet and a small amount of SOL for transaction fees.
+
+## How It Works
+
+```
+Agent says: "Search Hacker News for AI agent news"
+    ↓
+Plugin calls: GET https://scout.hugen.tokyo/scout/hn?q=AI+agents
+    ↓
+Server returns: 402 Payment Required (with Solana USDC payment option)
+    ↓
+Plugin signs: Solana USDC transfer ($0.005)
+    ↓
+Plugin retries: GET with X-PAYMENT header
+    ↓
+Server returns: 200 OK + search results
+    ↓
+Agent receives: Structured data to answer the user
+```
+
+## Available Action
+
+### FETCH_X402_SOLANA
+
+Fetches data from any x402-protected API with automatic Solana USDC payment.
+
+**Parameters:**
+| Name | Required | Description |
+|------|----------|-------------|
+| `url` | Yes | Full URL of the x402 API endpoint |
+| `method` | No | HTTP method (GET or POST, default: GET) |
+| `body` | No | JSON body for POST requests |
+
+**Example URLs:**
+- `https://scout.hugen.tokyo/scout/hn?q=AI+agents` — Search Hacker News ($0.005)
+- `https://scout.hugen.tokyo/scout/report?q=MCP+servers` — 14-source intelligence report ($0.005)
+- `https://defi.hugen.tokyo/defi/token?chain=1&address=0x...` — Token security audit ($0.005)
+- `https://domain.hugen.tokyo/domain/full?domain=example.com` — Full domain intelligence ($0.01)
+- `https://intel.hugen.tokyo/intel/token-report` — AI-synthesized token DD ($0.50)
+
+## Security Configuration
+
+The plugin includes built-in security controls configurable via plugin config:
+
+```json
+{
+  "plugins": ["@hugen/plugin-x402-solana"],
+  "pluginConfig": {
+    "@hugen/plugin-x402-solana": {
+      "allowedDomains": "scout.hugen.tokyo,defi.hugen.tokyo",
+      "maxPaymentUsd": "1.00",
+      "allowAnyDomain": "false",
+      "fetchTimeoutMs": "30000"
+    }
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `allowedDomains` | `*.hugen.tokyo` (9 domains) | Comma-separated domain allowlist |
+| `maxPaymentUsd` | `1.00` | Maximum USDC payment per request |
+| `allowAnyDomain` | `false` | Set `true` to disable domain allowlist |
+| `fetchTimeoutMs` | `30000` | Request timeout in milliseconds |
+
+**Security features:**
+- SSRF protection: blocks private IPs (IPv4 + IPv6 + IPv4-mapped IPv6)
+- Domain allowlist: only approved domains by default
+- Payment limit: rejects 402 requirements exceeding the USD threshold
+- Request timeout: prevents hung requests from blocking the agent
+
+## Technical Details
+
+- Uses `@x402/svm` v2.5.0 (Coinbase official) for Solana transaction signing
+- Uses `@x402/fetch` for automatic 402 → payment → retry flow
+- Base58 + JSON array key format support (no external dependency)
+- Requires Node.js 20+ (`@solana/kit` requirement)
+- Compatible with ElizaOS 2.0.0-alpha.3+
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/dist/__tests__/security.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests for security (URL validation, SSRF protection, IPv6) and base58 decoding.
+ *
+ * Uses Node.js built-in test runner (node --test).
+ */
+export {};

package/dist/__tests__/security.test.js

@@ -0,0 +1,233 @@
+/**
+ * Tests for security (URL validation, SSRF protection, IPv6) and base58 decoding.
+ *
+ * Uses Node.js built-in test runner (node --test).
+ */
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { validateUrl, maskQueryParams, configureSecurityPolicy, createMaxPaymentPolicy } from "../security.js";
+import { decodeBase58, parsePrivateKey } from "../client.js";
+// Minimal mock runtime for per-runtime config
+const mockRuntime = {};
+beforeEach(() => {
+    configureSecurityPolicy(mockRuntime, {});
+});
+// --- Base58 Decoding (#4 fix) ---
+describe("decodeBase58", () => {
+    it("decodes '1' to exactly 1 zero byte", () => {
+        const result = decodeBase58("1");
+        assert.equal(result.length, 1);
+        assert.equal(result[0], 0);
+    });
+    it("decodes '11' to exactly 2 zero bytes", () => {
+        const result = decodeBase58("11");
+        assert.equal(result.length, 2);
+        assert.equal(result[0], 0);
+        assert.equal(result[1], 0);
+    });
+    it("decodes '2' to [1]", () => {
+        const result = decodeBase58("2");
+        assert.equal(result.length, 1);
+        assert.equal(result[0], 1);
+    });
+    it("decodes '1A' to [0, 9]", () => {
+        // '1' = leading zero, 'A' = index 9 in base58
+        const result = decodeBase58("1A");
+        assert.equal(result.length, 2);
+        assert.equal(result[0], 0);
+        assert.equal(result[1], 9);
+    });
+    it("throws on invalid base58 characters", () => {
+        assert.throws(() => decodeBase58("0OIl"), /Invalid base58 character/);
+    });
+});
+// --- parsePrivateKey ---
+describe("parsePrivateKey", () => {
+    it("parses JSON array format", () => {
+        const jsonKey = JSON.stringify(Array.from({ length: 64 }, (_, i) => i));
+        const result = parsePrivateKey(jsonKey);
+        assert.equal(result.length, 64);
+        assert.equal(result[0], 0);
+        assert.equal(result[63], 63);
+    });
+    it("rejects invalid JSON array values", () => {
+        assert.throws(() => parsePrivateKey("[256, 0, 0]"), /numbers 0-255/);
+    });
+    it("rejects non-array JSON (object with { triggers base58 error)", () => {
+        assert.throws(() => parsePrivateKey('{"key": "value"}'), /Invalid base58 character/);
+    });
+    it("trims whitespace before parsing", () => {
+        const jsonKey = "  " + JSON.stringify(Array.from({ length: 64 }, () => 42)) + "  ";
+        const result = parsePrivateKey(jsonKey);
+        assert.equal(result.length, 64);
+    });
+    it("falls back to base58 for non-JSON input", () => {
+        const result = parsePrivateKey("2");
+        assert.ok(result.length > 0);
+    });
+    it("parses 64-char hex string as 32-byte private key", () => {
+        const hex = "ab".repeat(32); // 64 hex chars = 32 bytes
+        const result = parsePrivateKey(hex);
+        assert.equal(result.length, 32);
+        assert.equal(result[0], 0xab);
+    });
+    it("parses 128-char hex string as 64-byte keypair", () => {
+        const hex = "cd".repeat(64); // 128 hex chars = 64 bytes
+        const result = parsePrivateKey(hex);
+        assert.equal(result.length, 64);
+        assert.equal(result[0], 0xcd);
+    });
+    it("parses 0x-prefixed hex string", () => {
+        const hex = "0x" + "ef".repeat(32);
+        const result = parsePrivateKey(hex);
+        assert.equal(result.length, 32);
+        assert.equal(result[0], 0xef);
+    });
+});
+// --- URL Validation ---
+describe("validateUrl", () => {
+    it("allows known hugen.tokyo domains", () => {
+        configureSecurityPolicy(mockRuntime, {});
+        assert.doesNotThrow(() => validateUrl("https://scout.hugen.tokyo/scout/hn?q=test", mockRuntime));
+        assert.doesNotThrow(() => validateUrl("https://defi.hugen.tokyo/defi/token?chain=1", mockRuntime));
+        assert.doesNotThrow(() => validateUrl("https://intel.hugen.tokyo/intel/token-report", mockRuntime));
+    });
+    it("blocks unknown domains by default", () => {
+        configureSecurityPolicy(mockRuntime, {});
+        assert.throws(() => validateUrl("https://evil.com/steal", mockRuntime), /not in allowlist/);
+    });
+    it("blocks HTTP (non-HTTPS)", () => {
+        configureSecurityPolicy(mockRuntime, {});
+        assert.throws(() => validateUrl("http://scout.hugen.tokyo/scout/hn", mockRuntime), /Only HTTPS/);
+    });
+    it("blocks private IPv4 addresses", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://127.0.0.1/admin", mockRuntime), /private.*internal/i);
+        assert.throws(() => validateUrl("https://10.0.0.1/secret", mockRuntime), /private.*internal/i);
+        assert.throws(() => validateUrl("https://192.168.1.1/api", mockRuntime), /private.*internal/i);
+        assert.throws(() => validateUrl("https://172.16.0.1/api", mockRuntime), /private.*internal/i);
+    });
+    it("blocks localhost", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://localhost/api", mockRuntime), /private.*internal/i);
+    });
+    // #1 fix: IPv6 SSRF
+    it("blocks IPv6 loopback [::1]", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[::1]/admin", mockRuntime), /private.*internal/i);
+    });
+    it("blocks IPv6 link-local [fe80::]", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[fe80::1]/api", mockRuntime), /private.*internal/i);
+    });
+    it("blocks IPv6 ULA [fc00::]", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[fc00::1]/api", mockRuntime), /private.*internal/i);
+    });
+    it("blocks IPv4-mapped IPv6 [::ffff:169.254.169.254] (cloud metadata)", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[::ffff:169.254.169.254]/metadata", mockRuntime), /private.*internal/i);
+    });
+    it("blocks IPv4-mapped IPv6 [::ffff:127.0.0.1]", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[::ffff:127.0.0.1]/admin", mockRuntime), /private.*internal/i);
+    });
+    it("blocks IPv4-mapped IPv6 [::ffff:10.0.0.1]", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.throws(() => validateUrl("https://[::ffff:10.0.0.1]/secret", mockRuntime), /private.*internal/i);
+    });
+    it("allows custom domain allowlist", () => {
+        configureSecurityPolicy(mockRuntime, { allowedDomains: ["api.example.com"] });
+        assert.doesNotThrow(() => validateUrl("https://api.example.com/data", mockRuntime));
+        assert.throws(() => validateUrl("https://scout.hugen.tokyo/scout/hn", mockRuntime), /not in allowlist/);
+    });
+    it("allows any domain when configured", () => {
+        configureSecurityPolicy(mockRuntime, { allowAnyDomain: true });
+        assert.doesNotThrow(() => validateUrl("https://any-public-api.com/endpoint", mockRuntime));
+    });
+    it("rejects invalid URLs", () => {
+        configureSecurityPolicy(mockRuntime, {});
+        assert.throws(() => validateUrl("not-a-url", mockRuntime), /Invalid URL/);
+    });
+});
+// --- Payment Policy (#2 fix) ---
+describe("createMaxPaymentPolicy", () => {
+    it("allows payments under the limit", () => {
+        const policy = createMaxPaymentPolicy(1.0); // $1.00
+        const requirements = [{ amount: "500000", scheme: "exact", network: "solana:mainnet" }]; // $0.50
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 1);
+    });
+    it("rejects payments over the limit", () => {
+        const policy = createMaxPaymentPolicy(1.0); // $1.00
+        const requirements = [{ amount: "2000000", scheme: "exact", network: "solana:mainnet" }]; // $2.00
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 0);
+    });
+    it("allows exactly the limit", () => {
+        const policy = createMaxPaymentPolicy(0.50); // $0.50
+        const requirements = [{ amount: "500000", scheme: "exact", network: "solana:mainnet" }]; // $0.50
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 1);
+    });
+    it("handles invalid amount strings", () => {
+        const policy = createMaxPaymentPolicy(1.0);
+        const requirements = [{ amount: "not-a-number", scheme: "exact" }];
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 0);
+    });
+    // H1 fix: Math.round prevents floating point truncation
+    it("allows $0.005 payment with maxPaymentUsd=0.005 (floating point safe)", () => {
+        const policy = createMaxPaymentPolicy(0.005);
+        const requirements = [{ amount: "5000", scheme: "exact", network: "solana:mainnet" }];
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 1, "Math.round should produce 5000, not 4999");
+    });
+    // R1-1 fix: Only USDC allowed
+    it("rejects non-USDC token payments", () => {
+        const policy = createMaxPaymentPolicy(1.0);
+        const requirements = [{
+                amount: "100",
+                scheme: "exact",
+                network: "solana:mainnet",
+                asset: "SoMeRaNdOmToKeNmInTaDdReSs111111111111111",
+            }];
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 0, "Non-USDC asset should be rejected");
+    });
+    it("allows USDC mainnet mint", () => {
+        const policy = createMaxPaymentPolicy(1.0);
+        const requirements = [{
+                amount: "5000",
+                scheme: "exact",
+                network: "solana:mainnet",
+                asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+            }];
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 1, "USDC mainnet mint should be allowed");
+    });
+    it("allows payment when asset is not specified (backwards compat)", () => {
+        const policy = createMaxPaymentPolicy(1.0);
+        const requirements = [{ amount: "5000", scheme: "exact", network: "solana:mainnet" }];
+        const filtered = policy(2, requirements);
+        assert.equal(filtered.length, 1, "Missing asset should be allowed (backwards compat)");
+    });
+});
+// --- Query Masking ---
+describe("maskQueryParams", () => {
+    it("masks query parameter values", () => {
+        const masked = maskQueryParams("https://scout.hugen.tokyo/scout/hn?q=secret&per_page=5");
+        assert.ok(masked.includes("q=***"));
+        assert.ok(masked.includes("per_page=***"));
+        assert.ok(!masked.includes("secret"));
+        assert.ok(!masked.includes("=5"));
+    });
+    it("preserves URL without query params", () => {
+        const masked = maskQueryParams("https://scout.hugen.tokyo/health");
+        assert.equal(masked, "https://scout.hugen.tokyo/health");
+    });
+    it("handles malformed URLs gracefully", () => {
+        const masked = maskQueryParams("not-a-url?key=val");
+        assert.ok(!masked.includes("val"));
+    });
+});

package/dist/actions/fetch-x402.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Action: Fetch an x402-protected API with automatic Solana USDC payment.
+ *
+ * When the agent needs data from a paid API (scout intelligence, DeFi data,
+ * domain analysis, etc.), this action handles the x402 payment flow:
+ * 1. Validates URL against domain allowlist and SSRF rules
+ * 2. Makes the HTTP request (with timeout, no redirects)
+ * 3. Receives 402 Payment Required
+ * 4. Signs a Solana USDC transfer (enforced by payment policy: USDC only + max limit)
+ * 5. Retries with payment proof
+ * 6. Returns the API response to the agent
+ */
+import type { Action } from "@elizaos/core";
+export declare const fetchX402Action: Action;

package/dist/actions/fetch-x402.js

@@ -0,0 +1,235 @@
+/**
+ * Action: Fetch an x402-protected API with automatic Solana USDC payment.
+ *
+ * When the agent needs data from a paid API (scout intelligence, DeFi data,
+ * domain analysis, etc.), this action handles the x402 payment flow:
+ * 1. Validates URL against domain allowlist and SSRF rules
+ * 2. Makes the HTTP request (with timeout, no redirects)
+ * 3. Receives 402 Payment Required
+ * 4. Signs a Solana USDC transfer (enforced by payment policy: USDC only + max limit)
+ * 5. Retries with payment proof
+ * 6. Returns the API response to the agent
+ */
+import { getX402Fetch } from "../state.js";
+import { validateUrl, maskQueryParams, getFetchTimeoutMs } from "../security.js";
+/** Max response body size (4 MB). */
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+/**
+ * Read response body with streaming size enforcement.
+ * Prevents OOM from servers that lie about Content-Length or omit it.
+ */
+async function readBodySafe(response, maxBytes) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        // Fallback for environments without ReadableStream
+        const text = await response.text();
+        if (text.length > maxBytes) {
+            throw new Error(`Response body exceeds ${maxBytes} bytes`);
+        }
+        return text;
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    const decoder = new TextDecoder();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalBytes += value.length;
+            if (totalBytes > maxBytes) {
+                reader.cancel();
+                throw new Error(`Response body exceeds ${maxBytes} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    // Decode all chunks
+    let text = "";
+    for (let i = 0; i < chunks.length; i++) {
+        text += decoder.decode(chunks[i], { stream: i < chunks.length - 1 });
+    }
+    text += decoder.decode();
+    return text;
+}
+export const fetchX402Action = {
+    name: "FETCH_X402_SOLANA",
+    description: "Fetch data from an x402-protected API, paying with Solana USDC. " +
+        "Use this when you need to access paid intelligence APIs like scout " +
+        "(multi-source search), DeFi security data, domain intelligence, " +
+        "weather data, email validation, or any x402-enabled service. " +
+        "Payment is automatic — the agent's Solana wallet pays USDC directly.",
+    similes: [
+        "pay for API with Solana",
+        "x402 Solana payment",
+        "fetch paid API",
+        "search with scout",
+        "get intelligence report",
+        "access paid endpoint",
+    ],
+    parameters: [
+        {
+            name: "url",
+            description: "Full URL of the x402-protected API endpoint. " +
+                "Examples: https://scout.hugen.tokyo/scout/hn?q=AI+agents, " +
+                "https://defi.hugen.tokyo/defi/token?chain=1&address=0x...",
+            required: true,
+            schema: { type: "string" },
+        },
+        {
+            name: "method",
+            description: "HTTP method. Defaults to GET.",
+            required: false,
+            schema: { type: "string", enumValues: ["GET", "POST", "PUT"] },
+        },
+        {
+            name: "body",
+            description: "JSON request body for POST/PUT requests.",
+            required: false,
+            schema: { type: "string" },
+        },
+    ],
+    validate: async (runtime) => {
+        return getX402Fetch(runtime) !== null;
+    },
+    handler: async (runtime, _message, _state, options, callback) => {
+        const x402Fetch = getX402Fetch(runtime);
+        if (!x402Fetch) {
+            if (callback) {
+                await callback({
+                    text: "Solana x402 payment is not configured. Set SOLANA_PRIVATE_KEY in agent settings.",
+                    actions: [],
+                });
+            }
+            return { success: false, error: "x402-solana not initialized" };
+        }
+        // Extract parameters from HandlerOptions.parameters
+        const params = options?.parameters ??
+            options;
+        const url = params?.url;
+        if (!url) {
+            if (callback) {
+                await callback({ text: "No URL provided for the API request.", actions: [] });
+            }
+            return { success: false, error: "Missing url parameter" };
+        }
+        // Validate URL against allowlist and SSRF rules
+        try {
+            validateUrl(url, runtime);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            if (callback) {
+                await callback({ text: `URL blocked: ${reason}`, actions: [] });
+            }
+            return { success: false, error: reason };
+        }
+        const method = (params?.method || "GET").toUpperCase();
+        const body = params?.body;
+        const safeUrl = maskQueryParams(url);
+        // Timeout via AbortController
+        const timeoutMs = getFetchTimeoutMs(runtime);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            console.error(`[x402-solana] ${method} ${safeUrl}`);
+            const init = {
+                method,
+                signal: controller.signal,
+                // R1-2 fix: Block redirects to prevent allowlist bypass via 302/307
+                redirect: "error",
+            };
+            if (body && (method === "POST" || method === "PUT")) {
+                init.body = body;
+                init.headers = { "Content-Type": "application/json" };
+            }
+            const response = await x402Fetch(url, init);
+            // R2-① fix: Streaming body reader with actual byte limit (not trusting Content-Length)
+            const text = await readBodySafe(response, MAX_RESPONSE_BYTES);
+            if (!response.ok) {
+                console.error(`[x402-solana] ${safeUrl} → ${response.status}`);
+                if (callback) {
+                    await callback({
+                        text: `API returned status ${response.status}: ${text.slice(0, 500)}`,
+                        actions: [],
+                    });
+                }
+                return { success: false, error: `HTTP ${response.status}` };
+            }
+            // Parse as JSON — keep full structure
+            let data;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                    data = parsed;
+                }
+                else {
+                    data = { result: parsed };
+                }
+            }
+            catch {
+                data = { text: text.slice(0, 4000) };
+            }
+            console.error(`[x402-solana] OK ${safeUrl} (${text.length}B)`);
+            if (callback) {
+                const summary = JSON.stringify(data, null, 2).slice(0, 2000);
+                await callback({ text: summary, actions: [] });
+            }
+            return { success: true, data: data };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const isTimeout = err instanceof DOMException && err.name === "AbortError";
+            const isRedirect = message.includes("redirect");
+            let displayMsg;
+            if (isTimeout) {
+                displayMsg = `Request timed out after ${timeoutMs}ms`;
+            }
+            else if (isRedirect) {
+                displayMsg = `Request was redirected (blocked for security): ${safeUrl}`;
+            }
+            else {
+                displayMsg = message;
+            }
+            console.error(`[x402-solana] Error on ${safeUrl}: ${displayMsg}`);
+            if (callback) {
+                await callback({ text: `Failed to fetch: ${displayMsg}`, actions: [] });
+            }
+            return { success: false, error: displayMsg };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    },
+    examples: [
+        [
+            {
+                name: "user",
+                content: { text: "Search Hacker News for AI agent news" },
+            },
+            {
+                name: "assistant",
+                content: {
+                    text: "I'll search Hacker News for AI agent news using the Scout API.",
+                    actions: ["FETCH_X402_SOLANA"],
+                },
+            },
+        ],
+        [
+            {
+                name: "user",
+                content: { text: "Get a multi-source intelligence report on MCP servers" },
+            },
+            {
+                name: "assistant",
+                content: {
+                    text: "I'll generate a multi-source intelligence report on MCP servers.",
+                    actions: ["FETCH_X402_SOLANA"],
+                },
+            },
+        ],
+    ],
+};

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Solana x402 client setup.
+ *
+ * Creates a payment-aware fetch that automatically handles 402 responses
+ * by signing Solana USDC transfers via the x402 protocol.
+ */
+/**
+ * Decode a base58-encoded Solana keypair to Uint8Array.
+ * Solana CLI keypairs are 64 bytes: [32-byte private key | 32-byte public key].
+ */
+export declare function decodeBase58(encoded: string): Uint8Array;
+/**
+ * Parse a Solana private key from multiple formats.
+ *
+ * Supports:
+ * - Hex string (64 chars = 32 bytes private key, 128 chars = 64 bytes keypair)
+ * - Base58 string: standard Solana wallet format (64-byte keypair)
+ * - JSON array: Solana CLI's ~/.config/solana/id.json format ([12, 34, ...])
+ */
+export declare function parsePrivateKey(input: string): Uint8Array;
+/**
+ * Create a payment-aware fetch function for Solana x402 payments.
+ *
+ * @param privateKeyInput - Base58-encoded Solana keypair or JSON array
+ * @param maxPaymentUsd - Maximum payment amount in USD per request
+ * @returns A fetch function that auto-handles 402 → Solana USDC payment → retry
+ */
+export declare function createSolanaX402Fetch(privateKeyInput: string, maxPaymentUsd?: number): Promise<(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>>;

package/dist/client.js

@@ -0,0 +1,120 @@
+/**
+ * Solana x402 client setup.
+ *
+ * Creates a payment-aware fetch that automatically handles 402 responses
+ * by signing Solana USDC transfers via the x402 protocol.
+ */
+import { x402Client } from "@x402/fetch";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { toClientSvmSigner } from "@x402/svm";
+import { registerExactSvmScheme } from "@x402/svm/exact/client";
+import { createKeyPairSignerFromBytes, createKeyPairSignerFromPrivateKeyBytes } from "@solana/signers";
+import { createMaxPaymentPolicy } from "./security.js";
+/** Solana mainnet CAIP-2 identifier */
+const SOLANA_MAINNET = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+/**
+ * Decode a base58-encoded Solana keypair to Uint8Array.
+ * Solana CLI keypairs are 64 bytes: [32-byte private key | 32-byte public key].
+ */
+export function decodeBase58(encoded) {
+    const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    const BASE = 58;
+    const bytes = [];
+    for (const char of encoded) {
+        const idx = ALPHABET.indexOf(char);
+        if (idx < 0)
+            throw new Error(`Invalid base58 character: ${char}`);
+        let carry = idx;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += bytes[j] * BASE;
+            bytes[j] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // Count leading '1's = leading zero bytes
+    let leadingZeros = 0;
+    for (const char of encoded) {
+        if (char !== "1")
+            break;
+        leadingZeros++;
+    }
+    // Reverse the computed bytes and prepend leading zeros
+    const reversed = bytes.reverse();
+    const result = new Uint8Array(leadingZeros + reversed.length);
+    result.set(reversed, leadingZeros);
+    return result;
+}
+/**
+ * Decode a hex string to Uint8Array.
+ */
+function decodeHex(hex) {
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Parse a Solana private key from multiple formats.
+ *
+ * Supports:
+ * - Hex string (64 chars = 32 bytes private key, 128 chars = 64 bytes keypair)
+ * - Base58 string: standard Solana wallet format (64-byte keypair)
+ * - JSON array: Solana CLI's ~/.config/solana/id.json format ([12, 34, ...])
+ */
+export function parsePrivateKey(input) {
+    const trimmed = input.trim();
+    // JSON array format: [12, 34, 56, ...]
+    if (trimmed.startsWith("[")) {
+        try {
+            const arr = JSON.parse(trimmed);
+            if (!Array.isArray(arr) || !arr.every((n) => typeof n === "number" && n >= 0 && n <= 255)) {
+                throw new Error("JSON array must contain numbers 0-255");
+            }
+            return new Uint8Array(arr);
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON array key format: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    // Hex format: 64 hex chars (32 bytes) or 128 hex chars (64 bytes)
+    const hexClean = trimmed.startsWith("0x") ? trimmed.slice(2) : trimmed;
+    if (/^[0-9a-f]+$/i.test(hexClean) && (hexClean.length === 64 || hexClean.length === 128)) {
+        return decodeHex(hexClean);
+    }
+    // Base58 format (default)
+    return decodeBase58(trimmed);
+}
+/**
+ * Create a payment-aware fetch function for Solana x402 payments.
+ *
+ * @param privateKeyInput - Base58-encoded Solana keypair or JSON array
+ * @param maxPaymentUsd - Maximum payment amount in USD per request
+ * @returns A fetch function that auto-handles 402 → Solana USDC payment → retry
+ */
+export async function createSolanaX402Fetch(privateKeyInput, maxPaymentUsd = 1.0) {
+    // 1. Parse private key (hex, base58, or JSON array)
+    const keyBytes = parsePrivateKey(privateKeyInput);
+    // 2. Create a KeyPairSigner — 32 bytes = private key only, 64 bytes = full keypair
+    const signer = keyBytes.length === 32
+        ? await createKeyPairSignerFromPrivateKeyBytes(keyBytes)
+        : await createKeyPairSignerFromBytes(keyBytes);
+    // 3. Convert to x402 SVM signer
+    const svmSigner = toClientSvmSigner(signer);
+    // 4. Create x402 client and register Solana scheme
+    //    M2 fix: Explicitly specify mainnet only to prevent devnet/testnet payments
+    const client = new x402Client();
+    registerExactSvmScheme(client, {
+        signer: svmSigner,
+        policies: [createMaxPaymentPolicy(maxPaymentUsd)],
+        networks: [SOLANA_MAINNET],
+    });
+    console.error(`[x402-solana] Wallet: ${signer.address} on ${SOLANA_MAINNET} (max $${maxPaymentUsd}/req)`);
+    // 5. Wrap fetch with payment handling
+    return wrapFetchWithPayment(fetch, client);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @hugen/plugin-x402-solana
+ *
+ * Solana USDC payments for ElizaOS agents via the x402 protocol.
+ * Enables agents to pay for any x402-protected API using Solana USDC.
+ *
+ * The first Solana x402 payment plugin for ElizaOS.
+ */
+import type { Plugin } from "@elizaos/core";
+export { getX402Fetch } from "./state.js";
+export declare const x402SolanaPlugin: Plugin;
+export default x402SolanaPlugin;

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @hugen/plugin-x402-solana
+ *
+ * Solana USDC payments for ElizaOS agents via the x402 protocol.
+ * Enables agents to pay for any x402-protected API using Solana USDC.
+ *
+ * The first Solana x402 payment plugin for ElizaOS.
+ */
+import { fetchX402Action } from "./actions/fetch-x402.js";
+import { createSolanaX402Fetch } from "./client.js";
+import { configureSecurityPolicy, getMaxPaymentUsd } from "./security.js";
+import { setX402Fetch, deleteX402Fetch } from "./state.js";
+// Re-export for external consumers
+export { getX402Fetch } from "./state.js";
+export const x402SolanaPlugin = {
+    name: "x402-solana",
+    description: "Pay for x402-protected APIs with Solana USDC. " +
+        "Automatically handles 402 Payment Required responses by signing " +
+        "Solana USDC transfers and retrying. Supports all x402-enabled APIs.",
+    init: async (pluginConfig, runtime) => {
+        // Configure security policy per-runtime
+        configureSecurityPolicy(runtime, {
+            allowedDomains: pluginConfig.allowedDomains?.split(",").map((d) => d.trim()),
+            maxPaymentUsd: pluginConfig.maxPaymentUsd
+                ? parseFloat(pluginConfig.maxPaymentUsd)
+                : undefined,
+            allowAnyDomain: pluginConfig.allowAnyDomain === "true",
+            fetchTimeoutMs: pluginConfig.fetchTimeoutMs
+                ? parseInt(pluginConfig.fetchTimeoutMs, 10)
+                : undefined,
+        });
+        const privateKey = runtime.getSetting("SOLANA_PRIVATE_KEY") ??
+            runtime.getSetting("WALLET_PRIVATE_KEY");
+        if (!privateKey) {
+            console.error("[x402-solana] No SOLANA_PRIVATE_KEY or WALLET_PRIVATE_KEY found in settings. " +
+                "Plugin will be inactive.");
+            deleteX402Fetch(runtime);
+            return;
+        }
+        try {
+            const maxUsd = getMaxPaymentUsd(runtime);
+            const x402Fetch = await createSolanaX402Fetch(String(privateKey), maxUsd);
+            setX402Fetch(runtime, x402Fetch);
+            console.error("[x402-solana] Initialized — Solana USDC payments enabled");
+        }
+        catch (err) {
+            deleteX402Fetch(runtime);
+            console.error("[x402-solana] Failed to initialize:", err);
+        }
+    },
+    actions: [fetchX402Action],
+};
+export default x402SolanaPlugin;

package/dist/security.d.ts

@@ -0,0 +1,38 @@
+/**
+ * URL validation, SSRF protection, and payment policy for x402 fetch requests.
+ *
+ * Prevents:
+ * - SSRF via private/internal IPs (IPv4 + IPv6 + IPv4-mapped IPv6)
+ * - Wallet drain via unapproved domains or excessive payments
+ * - Prompt injection attacks that trick the agent into calling malicious URLs
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import type { PaymentPolicy } from "@x402/fetch";
+/** Default fetch timeout in ms. */
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+export interface SecurityConfig {
+    allowedDomains?: string[];
+    maxPaymentUsd?: number;
+    allowAnyDomain?: boolean;
+    fetchTimeoutMs?: number;
+}
+export declare function configureSecurityPolicy(runtime: IAgentRuntime, c: SecurityConfig): void;
+/**
+ * Validate a URL before making an x402 fetch request.
+ * Throws if the URL is not allowed.
+ */
+export declare function validateUrl(url: string, runtime?: IAgentRuntime): void;
+/** Get the max payment USD threshold. */
+export declare function getMaxPaymentUsd(runtime?: IAgentRuntime): number;
+/** Get the fetch timeout in ms. */
+export declare function getFetchTimeoutMs(runtime?: IAgentRuntime): number;
+/**
+ * Create a PaymentPolicy that:
+ * 1. Only allows USDC payments (rejects other SPL tokens)
+ * 2. Rejects payments above a USD threshold
+ *
+ * USDC has 6 decimals: $1.00 = "1000000".
+ */
+export declare function createMaxPaymentPolicy(maxUsd: number): PaymentPolicy;
+/** Mask query parameter values for safe logging. */
+export declare function maskQueryParams(url: string): string;

package/dist/security.js

@@ -0,0 +1,163 @@
+/**
+ * URL validation, SSRF protection, and payment policy for x402 fetch requests.
+ *
+ * Prevents:
+ * - SSRF via private/internal IPs (IPv4 + IPv6 + IPv4-mapped IPv6)
+ * - Wallet drain via unapproved domains or excessive payments
+ * - Prompt injection attacks that trick the agent into calling malicious URLs
+ */
+/** Default allowed domains for x402 API calls. */
+const DEFAULT_ALLOWED_DOMAINS = [
+    "scout.hugen.tokyo",
+    "weather.hugen.tokyo",
+    "mailcheck.hugen.tokyo",
+    "defi.hugen.tokyo",
+    "content.hugen.tokyo",
+    "domain.hugen.tokyo",
+    "visual.hugen.tokyo",
+    "intel.hugen.tokyo",
+    "gotobi.hugen.tokyo",
+];
+/** Private/internal IP patterns (applied to bare hostname, brackets stripped). */
+const PRIVATE_IP_PATTERNS = [
+    /^127\./,
+    /^10\./,
+    /^172\.(1[6-9]|2\d|3[01])\./,
+    /^192\.168\./,
+    /^0\./,
+    /^169\.254\./,
+    /^::1$/,
+    /^fc00:/i,
+    /^fd/i,
+    /^fe80:/i,
+    /^localhost$/i,
+];
+/** Default max payment per single request in USD. */
+const DEFAULT_MAX_PAYMENT_USD = 1.0;
+/** Default fetch timeout in ms. */
+export const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+// --- Per-runtime config storage ---
+const configMap = new WeakMap();
+const EMPTY_CONFIG = {};
+export function configureSecurityPolicy(runtime, c) {
+    configMap.set(runtime, c);
+}
+function getConfig(runtime) {
+    if (runtime) {
+        return configMap.get(runtime) ?? EMPTY_CONFIG;
+    }
+    return EMPTY_CONFIG;
+}
+/**
+ * Strip IPv6 brackets from hostname for pattern matching.
+ * `new URL("https://[::1]").hostname` returns `[::1]`.
+ */
+function bareHostname(hostname) {
+    return hostname.replace(/^\[|\]$/g, "");
+}
+/**
+ * Convert IPv4-mapped IPv6 hex to IPv4 dotted format.
+ * Node.js normalizes `::ffff:127.0.0.1` to `::ffff:7f00:1`.
+ * Returns null if not an IPv4-mapped address.
+ */
+function ipv4MappedToIpv4(bare) {
+    const m = bare.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+    if (!m)
+        return null;
+    const hi = parseInt(m[1], 16);
+    const lo = parseInt(m[2], 16);
+    return `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+}
+/**
+ * Validate a URL before making an x402 fetch request.
+ * Throws if the URL is not allowed.
+ */
+export function validateUrl(url, runtime) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: ${url}`);
+    }
+    // Must be HTTPS
+    if (parsed.protocol !== "https:") {
+        throw new Error(`Only HTTPS URLs are allowed, got: ${parsed.protocol}`);
+    }
+    // Block private/internal IPs (strip brackets for IPv6)
+    const bare = bareHostname(parsed.hostname);
+    for (const pattern of PRIVATE_IP_PATTERNS) {
+        if (pattern.test(bare)) {
+            throw new Error(`Access to private/internal addresses is blocked: ${parsed.hostname}`);
+        }
+    }
+    // IPv4-mapped IPv6: Node normalizes ::ffff:127.0.0.1 → ::ffff:7f00:1 (hex)
+    // Decode back to IPv4 and re-check against IPv4 patterns
+    const mappedIpv4 = ipv4MappedToIpv4(bare);
+    if (mappedIpv4) {
+        for (const pattern of PRIVATE_IP_PATTERNS) {
+            if (pattern.test(mappedIpv4)) {
+                throw new Error(`Access to private/internal addresses is blocked: ${parsed.hostname}`);
+            }
+        }
+    }
+    // Domain allowlist check (unless allowAnyDomain is set)
+    const cfg = getConfig(runtime);
+    if (!cfg.allowAnyDomain) {
+        const allowed = cfg.allowedDomains ?? DEFAULT_ALLOWED_DOMAINS;
+        const isAllowed = allowed.some((d) => bare === d || bare.endsWith(`.${d}`));
+        if (!isAllowed) {
+            throw new Error(`Domain not in allowlist: ${parsed.hostname}. ` +
+                `Allowed: ${allowed.join(", ")}. ` +
+                `Set allowAnyDomain: true in plugin config to disable this check.`);
+        }
+    }
+}
+/** Get the max payment USD threshold. */
+export function getMaxPaymentUsd(runtime) {
+    return getConfig(runtime).maxPaymentUsd ?? DEFAULT_MAX_PAYMENT_USD;
+}
+/** Get the fetch timeout in ms. */
+export function getFetchTimeoutMs(runtime) {
+    return getConfig(runtime).fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+}
+/** USDC mint address on Solana mainnet. */
+const USDC_SOLANA_MAINNET = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+/**
+ * Create a PaymentPolicy that:
+ * 1. Only allows USDC payments (rejects other SPL tokens)
+ * 2. Rejects payments above a USD threshold
+ *
+ * USDC has 6 decimals: $1.00 = "1000000".
+ */
+export function createMaxPaymentPolicy(maxUsd) {
+    const maxBaseUnits = BigInt(Math.round(maxUsd * 1_000_000));
+    return (_version, requirements) => {
+        return requirements.filter((r) => {
+            try {
+                // R1-1 fix: Only allow USDC payments — reject other SPL tokens
+                if (r.asset && r.asset !== USDC_SOLANA_MAINNET) {
+                    return false;
+                }
+                return BigInt(r.amount) <= maxBaseUnits;
+            }
+            catch {
+                return false;
+            }
+        });
+    };
+}
+/** Mask query parameter values for safe logging. */
+export function maskQueryParams(url) {
+    try {
+        const parsed = new URL(url);
+        const masked = new URL(parsed.origin + parsed.pathname);
+        for (const [key] of parsed.searchParams) {
+            masked.searchParams.set(key, "***");
+        }
+        return masked.toString();
+    }
+    catch {
+        return url.split("?")[0] + "?***";
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared state for the x402-solana plugin.
+ *
+ * Extracted to break the circular dependency between index.ts and fetch-x402.ts.
+ * Both modules import from here instead of from each other.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+type X402Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/** Store a fetch instance for a runtime. */
+export declare function setX402Fetch(runtime: IAgentRuntime, fetch: X402Fetch): void;
+/** Remove a fetch instance for a runtime. */
+export declare function deleteX402Fetch(runtime: IAgentRuntime): void;
+/** Get the initialized x402 fetch for a runtime. Null if not configured. */
+export declare function getX402Fetch(runtime: IAgentRuntime): X402Fetch | null;
+export {};

package/dist/state.js

@@ -0,0 +1,20 @@
+/**
+ * Shared state for the x402-solana plugin.
+ *
+ * Extracted to break the circular dependency between index.ts and fetch-x402.ts.
+ * Both modules import from here instead of from each other.
+ */
+/** Per-runtime x402 fetch instances */
+const fetchMap = new WeakMap();
+/** Store a fetch instance for a runtime. */
+export function setX402Fetch(runtime, fetch) {
+    fetchMap.set(runtime, fetch);
+}
+/** Remove a fetch instance for a runtime. */
+export function deleteX402Fetch(runtime) {
+    fetchMap.delete(runtime);
+}
+/** Get the initialized x402 fetch for a runtime. Null if not configured. */
+export function getX402Fetch(runtime) {
+    return fetchMap.get(runtime) ?? null;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hugen/plugin-x402-solana",
+  "version": "0.1.0",
+  "description": "Solana USDC payments for ElizaOS agents via x402 protocol — pay for any x402-protected API with Solana",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsc && node --test dist/__tests__/*.test.js",
+    "clean": "rm -rf dist node_modules"
+  },
+  "engines": {
+    "node": ">=20.18.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@elizaos/core": "2.0.0-alpha.3",
+    "@solana/signers": "^5.5.0",
+    "@x402/core": "~2.5.0",
+    "@x402/svm": "~2.5.0",
+    "@x402/fetch": "~2.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0"
+  }
+}