@minia2a/elizaos-plugin-minia2a 0.2.3 → 0.2.4

package/README.md

@@ -1,8 +1,10 @@
 # @minia2a/elizaos-plugin-minia2a
 
-**The marketplace plugin for ElizaOS agents** — discover, try, and pay for 1,680+ x402 APIs across crypto, web, AI, and data. USDC on Base.
+**The marketplace plugin for ElizaOS agents** — discover and call 1,680+ x402 APIs across crypto, web, AI, and data, with live pricing surfaced on every HTTP 402. USDC on Base.
 
-> Unlike single-vendor x402 plugins that bundle a fixed set of endpoints, this plugin connects your agent to the **entire minia2a.uk marketplace** — 1,680+ services from dozens of providers, with live discovery, free trials, and transparent pricing.
+> Unlike single-vendor x402 plugins that bundle a fixed set of endpoints, this plugin connects your agent to the **entire minia2a.uk marketplace** — 1,680+ services from dozens of providers, with live discovery and transparent pricing.
+
+> **Scope of this version:** it does not sign trials and does not settle payments. `CALL_API` returns the endpoint's response, or on 402 reports the price plus the exact signed-trial recipe for your agent to follow. Neither the trial message nor a USDC payment is signed for you.
 
 ## Why This Plugin
 
@@ -10,10 +12,10 @@
 |---------|----------------------|-------------|
 | Services | 8–75 endpoints | **1,680+ across categories** |
 | Discovery | Pre-bundled at build time | **Live marketplace search** |
-| Free trials | Sometimes | **5 free trial calls per wallet** |
+| Free trials | Sometimes | **5 free trial calls per signed wallet** (platform-side; sign the message yourself) |
 | New services | Wait for plugin update | **Available instantly** |
 | Provider diversity | Single vendor | **Dozens of providers** |
-| Payment | USDC on chain | **USDC on Base (~3¢ gas)** |
+| Payment | USDC on chain | **x402 / USDC on Base** (not settled by this version) |
 
 ## Install
 
@@ -30,9 +32,8 @@ Add to your agent's `character.json`:
   "plugins": ["@minia2a/elizaos-plugin-minia2a"],
   "settings": {
     "MINIA2A_CONFIG": {
-      "autoTrial": true,
-      "maxPricePerCall": 0.10,
-      "baseUrl": "https://minia2a.uk"
+      "baseUrl": "https://minia2a.uk",
+      "maxSpendPerSession": 500
     }
   }
 }
@@ -43,21 +44,41 @@ Add to your agent's `character.json`:
 | Action | What it does | Example prompt |
 |--------|-------------|----------------|
 | `SEARCH_APIS` | Search 1,680+ APIs by keyword or category | "Find APIs that can scrape websites" |
-| `CALL_API` | Call any endpoint with auto-trial | "Get the current gas price on Base" |
+| `CALL_API` | Call any endpoint; on 402 return its price + the signed-trial recipe | "Get the current gas price on Base" |
 | `LIST_POPULAR_APIS` | Browse trending services | "What are the most used APIs?" |
 
 ## Provider
 
 The `MINIA2A_MARKETPLACE` provider injects live marketplace context into every agent interaction — service counts, popular endpoints, trial availability, and pricing.
 
-## x402 Payment Flow
+## What happens on HTTP 402
+
+1. Agent calls an endpoint → the gateway answers `402 Payment Required`.
+2. The challenge is in the **`payment-required` response header** (base64 JSON with an
+   `accepts[]` array). `CALL_API` decodes it and reports the price, e.g. `0.5 USDC on eip155:8453`.
+3. The agent then either **pays via x402 itself** (`PAYMENT-SIGNATURE` V2 / `X-PAYMENT` V1)
+   or **draws a free trial** with a signed wallet — see below.
+4. A successful call carries a receipt in the **`x-minia2a-receipt`** header, which `CALL_API`
+   surfaces in its reply.
+
+This plugin performs steps 1–2 and 4. It does **not** perform step 3: no trial signature and no
+payment is produced for you. `paymentPrivateKey` is accepted by the config but has no signer
+behind it, so setting it changes nothing.
+
+### Free trials (5 per signed wallet, no registration)
 
-1. Agent requests endpoint → gets `HTTP 402 Payment Required` with price + wallet
-2. Agent auto-signs USDC on Base (if `paymentPrivateKey` configured)
-3. Agent retries with `Authorization: x402 <signed-tx>` → receives result
-4. Receipt returned in `X-Receipt` header for audit trail
+Trials are wallet-based, not a URL parameter. A bare `?trial=1` draws nothing — the gateway
+documents that explicitly in its [AGENTS.md](https://minia2a.uk/AGENTS.md). To draw one:
+
+```
+message = "minia2a trial:" + wallet + ":" + serviceId + ":" + unixSeconds    # EIP-191
+GET /x402/<svc>?wallet=<wallet>
+  X-Wallet-Signature: <signature>
+  X-Trial-Timestamp: <unixSeconds>
+# → 200 + x-trial-remaining: 4, x-trial-max: 5
+```
 
-**Without a payment key:** the agent uses free trials — 5 free trial calls per wallet.
+`serviceId` is the catalog `id` (e.g. `x402-gas`), **not** the URL path segment (`gas`).
 
 ## Categories
 
@@ -70,10 +91,10 @@ The `MINIA2A_MARKETPLACE` provider injects live marketplace context into every a
 
 ## Pricing
 
-- **Free trial:** 5 free trial calls per wallet (`?trial=1`)
-- **Paid calls:** Priced per endpoint (typically $0.001–$0.10)
+- **Free trial:** 5 calls per signed wallet, one allowance across the whole catalog — see above
+- **Paid calls:** Priced per endpoint (typically $0.001–$0.10), charged in USDC per call
 - **Platform fee:** 5% (transparent, no hidden costs)
-- **Credits:** 1 USDC = 200 credits, no subscription, no minimum
+- **No credits, no subscription, no minimum** — the platform's unit is USDC (microUSDC balances)
 - **Settlement:** USDC on Base (~3¢ gas, ~2s confirmation)
 
 ## Related

package/dist/actions/callApi.js

@@ -3,6 +3,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.callApiAction = void 0;
 const spending_1 = require("../spending");
 const DEFAULT_BASE_URL = "https://minia2a.uk";
+/**
+ * A 402 from the gateway carries the canonical challenge in the
+ * `payment-required` response header: base64(JSON) with an `accepts[]` array.
+ * `WWW-Authenticate` / `X-Payment-Required` are legacy shapes this gateway does
+ * not send; reading only those (as an earlier version did) left the price blank.
+ */
+function readChallenge(res) {
+    const raw = res.headers.get("payment-required") || res.headers.get("PAYMENT-REQUIRED");
+    if (!raw)
+        return { nextSteps: [] };
+    try {
+        const json = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+        const accept = Array.isArray(json.accepts) ? json.accepts[0] : undefined;
+        const amount = accept?.amount;
+        const usd = amount != null ? Number(amount) / 1e6 : NaN;
+        return {
+            price: Number.isFinite(usd) ? `${usd} USDC on ${accept?.network || "?"}` : undefined,
+            error: typeof json.message === "string" ? json.message : undefined,
+            nextSteps: Array.isArray(json.nextSteps)
+                ? json.nextSteps.filter((s) => typeof s === "string")
+                : [],
+        };
+    }
+    catch {
+        return { nextSteps: [] };
+    }
+}
+const TRIAL_HOW_TO = "\n\n**Free trials are wallet-based.** Sign `minia2a trial:<wallet>:<service-id>:<unixSeconds>`" +
+    " (EIP-191), then send `?wallet=` together with the `X-Wallet-Signature` and `X-Trial-Timestamp`" +
+    " headers to draw 5 free calls — no registration. This plugin does not sign that message for you." +
+    " A bare `?trial=1` draws nothing; the gateway says so in its own AGENTS.md.";
 exports.callApiAction = {
     name: "CALL_API",
     similes: [
@@ -15,7 +46,7 @@ exports.callApiAction = {
         "X402_CALL",
         "MINIA2A_CALL",
     ],
-    description: "Call an x402 API endpoint on minia2a.uk. Uses free trials automatically (5 per wallet). For paid calls, handles the HTTP 402 → pay USDC → retry flow.",
+    description: "Call an x402 API endpoint on minia2a.uk and return its response. On HTTP 402 it reports the price and the exact signed-trial recipe. It does not sign trials and does not settle payments.",
     validate: async (_runtime, message, _state) => {
         const text = message.content?.text?.toLowerCase() || "";
         const triggers = [
@@ -35,7 +66,6 @@ exports.callApiAction = {
     handler: async (runtime, message, _state, _options, callback) => {
         const config = runtime.getSetting("MINIA2A_CONFIG") || {};
         const baseUrl = config.baseUrl || DEFAULT_BASE_URL;
-        const autoTrial = config.autoTrial !== false; // default true
         const maxSpend = config.maxSpendPerSession || 0;
         // Initialize session spending tracker if budget is configured
         if (maxSpend > 0) {
@@ -77,19 +107,16 @@ exports.callApiAction = {
                     }
                 }
             }
-            // Step 1: Send initial request (with trial header if auto-trial)
+            // Step 1: Send the request.
+            // There is no request header that grants a trial. Older versions set
+            // `x402-trial: true`, which the gateway ignores — it returned a 402
+            // byte-identical to the unheadered baseline, under a "with free trial"
+            // message. Trials are drawn by a signed wallet (see TRIAL_HOW_TO).
             const headers = {
                 "Content-Type": "application/json",
             };
-            if (autoTrial) {
-                headers["x402-trial"] = "true";
-            }
             if (callback) {
-                callback({
-                    text: autoTrial
-                        ? `🆓 Calling ${endpoint} with free trial...`
-                        : `📡 Calling ${endpoint}...`,
-                });
+                callback({ text: `📡 Calling ${endpoint}...` });
             }
             let res = await fetch(`${baseUrl}${endpoint}`, {
                 method: body && Object.keys(body).length > 0 ? "POST" : "GET",
@@ -100,15 +127,19 @@ exports.callApiAction = {
             });
             // Step 2: Handle HTTP 402 Payment Required
             if (res.status === 402) {
-                const paymentHeader = res.headers.get("WWW-Authenticate") ||
-                    res.headers.get("X-Payment-Required") ||
-                    "";
+                const challenge = readChallenge(res);
+                const head = `💳 **Payment Required**\n\nEndpoint: ${endpoint}` +
+                    (challenge.price ? `\nPrice: ${challenge.price}` : "") +
+                    (challenge.error ? `\nGateway: ${challenge.error}` : "") +
+                    (challenge.nextSteps.length
+                        ? `\n\nGateway next steps:\n${challenge.nextSteps.map((s) => `- ${s}`).join("\n")}`
+                        : "");
                 if (!config.paymentPrivateKey) {
                     return {
-                        text: `💳 **Payment Required**\n\nEndpoint: ${endpoint}\nPrice: ${paymentHeader}\n\nThis endpoint requires payment. Configure your wallet private key in MINIA2A_CONFIG.paymentPrivateKey to auto-pay, or use free trials (5 calls per wallet).`,
+                        text: head + TRIAL_HOW_TO,
                         success: false,
                         paymentRequired: true,
-                        paymentDetails: paymentHeader,
+                        paymentDetails: challenge.price,
                     };
                 }
                 // Budget check before payment
@@ -116,25 +147,24 @@ exports.callApiAction = {
                     const budgetCheck = (0, spending_1.canAfford)(runtime.agentId, 1); // approximate 1¢ minimum check
                     if (!budgetCheck.allowed) {
                         return {
-                            text: `🛑 ${budgetCheck.reason}\n\nUse free trials (5 per wallet) or increase maxSpendPerSession in config.`,
+                            text: `🛑 ${budgetCheck.reason}\n\nUse a signed wallet trial (see below) or increase maxSpendPerSession in config.` + TRIAL_HOW_TO,
                             success: false,
                             budgetExceeded: true,
                         };
                     }
                 }
-                // If we have a payment key, handle the payment flow
-                if (callback) {
-                    callback({ text: `💳 Payment required — auto-signing USDC on Base...` });
-                }
-                // Extract payment address and amount from 402 headers
-                // The actual USDC signing would use ethers.js or viem
-                // For now, return payment instructions
-                // TODO: Implement full x402 payment flow (sign USDC tx → retry with X-PAYMENT header)
+                // `paymentPrivateKey` is accepted by this plugin but had no payment
+                // signer behind it: an earlier version printed "auto-signing USDC on
+                // Base..." and then returned instructions without signing anything.
+                // Report that plainly instead of implying a settlement.
                 return {
-                    text: `💳 **Payment Required**\n\nEndpoint: ${endpoint}\nPayment details: ${paymentHeader}\n\n💡 Tip: Use free trials first — each wallet has 5 free trial calls. Set \`autoTrial: true\` in config.`,
+                    text: head +
+                        "\n\n**No payment was made.** `paymentPrivateKey` is configured, but this version has no" +
+                        " x402 signer wired to it — nothing was signed and no USDC was sent." +
+                        TRIAL_HOW_TO,
                     success: false,
                     paymentRequired: true,
-                    paymentDetails: paymentHeader,
+                    paymentDetails: challenge.price,
                 };
             }
             // Step 3: Handle response
@@ -151,10 +181,13 @@ exports.callApiAction = {
                     ? data
                     : JSON.stringify(data, null, 2)
                 : "OK (no response body)";
+            // The gateway names this `x-minia2a-receipt` (not `X-Receipt`).
+            const receipt = res.headers.get("x-minia2a-receipt");
             return {
-                text: `✅ **${endpoint}** response:\n\n\`\`\`json\n${resultText.slice(0, 2000)}\n\`\`\`${resultText.length > 2000 ? "\n\n...(truncated)" : ""}`,
+                text: `✅ **${endpoint}** response:\n\n\`\`\`json\n${resultText.slice(0, 2000)}\n\`\`\`${resultText.length > 2000 ? "\n\n...(truncated)" : ""}${receipt ? `\n\nReceipt: \`${receipt}\`` : ""}`,
                 success: true,
                 data,
+                receipt: receipt || undefined,
             };
         }
         catch (error) {
@@ -186,7 +219,7 @@ exports.callApiAction = {
             {
                 user: "{{user2}}",
                 content: {
-                    text: "🆓 Called /x402/gas with free trial. Gas: 12 Gwei on Base.",
+                    text: "💳 /x402/gas returned HTTP 402 — 0.5 USDC on eip155:8453. To draw a free trial, sign \"minia2a trial:<wallet>:x402-gas:<unixSeconds>\" and send it with ?wallet= and the X-Wallet-Signature / X-Trial-Timestamp headers.",
                     action: "CALL_API",
                 },
             },

package/dist/index.d.ts

@@ -11,17 +11,19 @@ export { initSpendingTracker, getSpending, getSpendSummary, canAfford, recordSpe
  *
  * Gives your ElizaOS agent the ability to:
  * - Search 1,680+ x402 pay-per-call APIs (SEARCH_APIS)
- * - Call any endpoint with auto-trial support (CALL_API)
+ * - Call any endpoint and, on 402, get its price + the signed-trial recipe (CALL_API)
  * - Browse trending/popular services (LIST_POPULAR_APIS)
- * - Track and control API spending per session (VIEW_SPENDING)
+ * - Track API spending per session (VIEW_SPENDING)
  * - Get marketplace stats injected into agent context (MINIA2A_MARKETPLACE provider)
  *
+ * What this version does NOT do: it does not sign trials and does not settle
+ * payments. A 402 is reported to you, never paid.
+ *
  * Configuration via character.json settings.MINIA2A_CONFIG:
  * - baseUrl: minia2a marketplace URL (default: https://minia2a.uk)
- * - autoTrial: use free trials automatically (default: true)
- * - maxPricePerCall: max USD per paid call (default: 0, trials only)
  * - maxSpendPerSession: total USD cents budget cap per session (0 = unlimited)
- * - paymentPrivateKey: wallet key for x402 USDC payments on Base
+ * - autoTrial, maxPricePerCall, paymentPrivateKey: accepted but not used —
+ *   there is no signed-trial path and no x402 signer behind them.
  *
  * @example
  * ```json

package/dist/index.js

@@ -28,17 +28,19 @@ Object.defineProperty(exports, "resetSpending", { enumerable: true, get: functio
  *
  * Gives your ElizaOS agent the ability to:
  * - Search 1,680+ x402 pay-per-call APIs (SEARCH_APIS)
- * - Call any endpoint with auto-trial support (CALL_API)
+ * - Call any endpoint and, on 402, get its price + the signed-trial recipe (CALL_API)
  * - Browse trending/popular services (LIST_POPULAR_APIS)
- * - Track and control API spending per session (VIEW_SPENDING)
+ * - Track API spending per session (VIEW_SPENDING)
  * - Get marketplace stats injected into agent context (MINIA2A_MARKETPLACE provider)
  *
+ * What this version does NOT do: it does not sign trials and does not settle
+ * payments. A 402 is reported to you, never paid.
+ *
  * Configuration via character.json settings.MINIA2A_CONFIG:
  * - baseUrl: minia2a marketplace URL (default: https://minia2a.uk)
- * - autoTrial: use free trials automatically (default: true)
- * - maxPricePerCall: max USD per paid call (default: 0, trials only)
  * - maxSpendPerSession: total USD cents budget cap per session (0 = unlimited)
- * - paymentPrivateKey: wallet key for x402 USDC payments on Base
+ * - autoTrial, maxPricePerCall, paymentPrivateKey: accepted but not used —
+ *   there is no signed-trial path and no x402 signer behind them.
  *
  * @example
  * ```json
@@ -58,7 +60,7 @@ Object.defineProperty(exports, "resetSpending", { enumerable: true, get: functio
 exports.minia2aPlugin = {
     name: "@minia2a/elizaos-plugin-minia2a",
     npmName: "@minia2a/elizaos-plugin-minia2a",
-    description: "Discover and call 1,680+ x402 pay-per-call APIs from minia2a.uk. Search, free trials, budget controls, and USDC payments on Base.",
+    description: "Discover and call 1,680+ x402 pay-per-call APIs from minia2a.uk. Live marketplace search, spending tracking, and the signed-trial recipe on HTTP 402. This version does not sign trials and does not settle payments.",
     config: {
         baseUrl: "https://minia2a.uk",
         autoTrial: true,

package/dist/spending.d.ts

@@ -2,8 +2,11 @@
  * Session-level spending tracker for budget controls.
  *
  * Tracks cumulative spend within a single agent session.
- * When maxSpendPerSession is configured, paid calls are blocked
- * once the budget is exhausted. Free trials are always allowed.
+ * When maxSpendPerSession is configured, CALL_API reports the budget as
+ * exhausted once it is spent, instead of returning the 402 challenge.
+ *
+ * Note: this version never settles a payment, so `totalCents` stays at 0 and
+ * the cap cannot bind in practice. It is wired, not meaningful yet.
  */
 interface SessionSpend {
     totalCents: number;

package/dist/spending.js

@@ -3,8 +3,11 @@
  * Session-level spending tracker for budget controls.
  *
  * Tracks cumulative spend within a single agent session.
- * When maxSpendPerSession is configured, paid calls are blocked
- * once the budget is exhausted. Free trials are always allowed.
+ * When maxSpendPerSession is configured, CALL_API reports the budget as
+ * exhausted once it is spent, instead of returning the 402 challenge.
+ *
+ * Note: this version never settles a payment, so `totalCents` stays at 0 and
+ * the cap cannot bind in practice. It is wired, not meaningful yet.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initSpendingTracker = initSpendingTracker;

package/dist/types.d.ts

@@ -31,11 +31,21 @@ export interface Minia2aApiResponse {
 export interface Minia2aPluginConfig {
     /** Base URL of the minia2a marketplace (default: https://minia2a.uk) */
     baseUrl?: string;
-    /** Whether to auto-use free trials when available */
+    /**
+     * Reserved. Accepted and ignored: this version has no signed-trial path, so
+     * there is no auto-trial to toggle. It previously set an `x402-trial` request
+     * header the gateway ignores.
+     */
     autoTrial?: boolean;
-    /** Maximum price in USD the agent is authorized to pay per call (0 = trials only) */
+    /**
+     * Accepted and NOT enforced. This version never settles a payment, so there
+     * is nothing to cap; the value is not read anywhere.
+     */
     maxPricePerCall?: number;
-    /** Wallet private key for signing x402 payments on Base */
+    /**
+     * Accepted and NOT used. No x402 signer is wired to it — nothing is signed
+     * and no USDC is sent, whether or not this is set.
+     */
     paymentPrivateKey?: string;
     /** Maximum total spend in USD cents allowed per agent session (0 = unlimited) */
     maxSpendPerSession?: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@minia2a/elizaos-plugin-minia2a",
-  "version": "0.2.3",
-  "description": "ElizaOS plugin for the minia2a.uk marketplace — 1,680+ x402 pay-per-call APIs across crypto, web, AI, and data. 5 free trial calls per wallet. USDC on Base.",
+  "version": "0.2.4",
+  "description": "ElizaOS plugin for the minia2a.uk marketplace \u2014 1,680+ x402 pay-per-call APIs across crypto, web, AI, and data. 5 free trial calls per wallet. USDC on Base.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [