@minia2a/elizaos-plugin-minia2a 0.1.1 → 0.2.0

package/README.md

@@ -1,18 +1,19 @@
 # @minia2a/elizaos-plugin-minia2a
 
-**ElizaOS plugin for [minia2a.uk](https://minia2a.uk)** — discover and call 299+ x402 pay-per-call APIs directly from your AI agent.
+**The marketplace plugin for ElizaOS agents** — discover, try, and pay for 299+ x402 APIs across crypto, web, AI, and data. USDC on Base.
 
-## What This Plugin Does
+> Unlike single-vendor x402 plugins that bundle a fixed set of endpoints, this plugin connects your agent to the **entire minia2a.uk marketplace** — 299+ services from dozens of providers, with live discovery, free trials, and transparent pricing.
 
-Your ElizaOS agent gets 3 new abilities:
+## Why This Plugin
 
-| Action | What it does |
-|--------|-------------|
-| `SEARCH_APIS` | Search 299+ APIs by keyword or category |
-| `CALL_API` | Call any endpoint with auto-trial (15 free calls per API) |
-| `LIST_POPULAR_APIS` | Browse trending/most-used services |
-
-Plus a provider that injects live marketplace stats into the agent's context.
+| Feature | Fixed-Endpoint Plugins | This Plugin |
+|---------|----------------------|-------------|
+| Services | 8–75 endpoints | **299+ across categories** |
+| Discovery | Pre-bundled at build time | **Live marketplace search** |
+| Free trials | Sometimes | **15 free calls per endpoint** |
+| New services | Wait for plugin update | **Available instantly** |
+| Provider diversity | Single vendor | **Dozens of providers** |
+| Payment | USDC on chain | **USDC on Base (~3¢ gas)** |
 
 ## Install
 
@@ -20,7 +21,7 @@ Plus a provider that injects live marketplace stats into the agent's context.
 npm install @minia2a/elizaos-plugin-minia2a
 ```
 
-## Configure
+## Quick Start
 
 Add to your agent's `character.json`:
 
@@ -37,38 +38,49 @@ Add to your agent's `character.json`:
 }
 ```
 
-## Usage
-
-Once configured, your agent can:
+## Actions
 
-**Search for APIs:**
-> "Search for APIs that can scrape websites"
+| Action | What it does | Example prompt |
+|--------|-------------|----------------|
+| `SEARCH_APIS` | Search 299+ 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" |
+| `LIST_POPULAR_APIS` | Browse trending services | "What are the most used APIs?" |
 
-**Browse the marketplace:**
-> "What APIs are available?"
+## Provider
 
-**Call an endpoint:**
-> "Call the /x402/gas endpoint" or "Try the gas price API"
+The `MINIA2A_MARKETPLACE` provider injects live marketplace context into every agent interaction — service counts, popular endpoints, trial availability, and pricing.
 
 ## x402 Payment Flow
 
-This plugin handles the full x402 flow:
-
-1. Agent requests an endpoint → gets **HTTP 402 Payment Required** with price + wallet address
+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 payment proof → receives result
+3. Agent retries with `Authorization: x402 <signed-tx>` → receives result
+4. Receipt returned in `X-Receipt` header for audit trail
+
+**Without a payment key:** the agent uses free trials — 15 calls per endpoint, zero setup, no wallet.
+
+## Categories
+
+- 🤖 **AI/LLM** — text generation, classification, translation, summarization
+- 🔗 **Web** — scraping, search, email verification, DNS, HTTP analysis
+- 💰 **Crypto** — gas prices, wallet intel, token security, DEX data, Polymarket
+- 🔐 **Security** — CAPTCHA solving, domain intel, SSL checks, OSINT
+- 📊 **Data** — enrichment, validation, formatting, CSV/JSON conversion
+- 🛠️ **Dev Tools** — code review, regex, UUID, hashing, JWT decode
 
-Without a payment key configured, the agent uses **free trials** (15 calls per endpoint).
+## Pricing
 
-## Real Data
+- **Free trial:** 15 calls per endpoint (`?trial=1`)
+- **Paid calls:** Priced per endpoint (typically $0.001–$0.10)
+- **Platform fee:** 5% (transparent, no hidden costs)
+- **Credits:** 1 USDC = 200 credits, no subscription, no minimum
+- **Settlement:** USDC on Base (~3¢ gas, ~2s confirmation)
 
-minia2a.uk currently has **299 services** with **8,144+ trials** from **318 developers** across categories including:
+## Related
 
-- 🤖 AI/LLM (text generation, classification, translation)
-- 🔗 Web (scraping, search, email verification)
-- 💰 Crypto (gas, prices, wallet intel, token security)
-- 🔐 Security (CAPTCHA solving, domain intel, audits)
-- 📊 Data (enrichment, validation, formatting)
+- [minia2a.uk](https://minia2a.uk) — The marketplace
+- [@minia2a/sdk](https://www.npmjs.com/package/@minia2a/sdk) — CLI for x402 developers
+- [x402.org](https://x402.org) — The payment protocol
 
 ## License
 

package/dist/actions/callApi.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.callApiAction = void 0;
+const spending_1 = require("../spending");
 const DEFAULT_BASE_URL = "https://minia2a.uk";
 exports.callApiAction = {
     name: "CALL_API",
@@ -35,6 +36,11 @@ exports.callApiAction = {
         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) {
+            (0, spending_1.initSpendingTracker)(runtime.agentId, maxSpend);
+        }
         try {
             const text = message.content?.text || "";
             // Extract endpoint name from message
@@ -105,6 +111,17 @@ exports.callApiAction = {
                         paymentDetails: paymentHeader,
                     };
                 }
+                // Budget check before payment
+                if (maxSpend > 0) {
+                    const budgetCheck = (0, spending_1.canAfford)(runtime.agentId, 1); // approximate 1¢ minimum check
+                    if (!budgetCheck.allowed) {
+                        return {
+                            text: `🛑 ${budgetCheck.reason}\n\nUse free trials (15 per endpoint) or increase maxSpendPerSession in config.`,
+                            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...` });
@@ -112,6 +129,7 @@ exports.callApiAction = {
                 // 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)
                 return {
                     text: `💳 **Payment Required**\n\nEndpoint: ${endpoint}\nPayment details: ${paymentHeader}\n\n💡 Tip: Use free trials first — each endpoint has 15 free calls. Set \`autoTrial: true\` in config.`,
                     success: false,

package/dist/actions/viewSpending.d.ts

@@ -0,0 +1,2 @@
+import { Action } from "@elizaos/core";
+export declare const viewSpendingAction: Action;

package/dist/actions/viewSpending.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.viewSpendingAction = void 0;
+const spending_1 = require("../spending");
+exports.viewSpendingAction = {
+    name: "VIEW_SPENDING",
+    similes: [
+        "CHECK_SPENDING",
+        "VIEW_BUDGET",
+        "SPENDING_STATUS",
+        "CHECK_BUDGET",
+        "HOW_MUCH_SPENT",
+        "MINIA2A_SPENDING",
+    ],
+    description: "View current session spending on minia2a API calls. Shows total spent, remaining budget, and call count.",
+    validate: async (_runtime, message, _state) => {
+        const text = message.content?.text?.toLowerCase() || "";
+        const triggers = [
+            "view spending",
+            "check spending",
+            "how much spent",
+            "budget status",
+            "view budget",
+            "check budget",
+            "spending status",
+            "remaining budget",
+        ];
+        return triggers.some((t) => text.includes(t));
+    },
+    handler: async (runtime, _message, _state, _options, _callback) => {
+        const summary = (0, spending_1.getSpendSummary)(runtime.agentId);
+        return {
+            text: summary,
+            success: true,
+        };
+    },
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: { text: "How much have I spent on API calls this session?" },
+            },
+            {
+                user: "{{user2}}",
+                content: {
+                    text: "💰 Session Spending: $0.15 across 3 paid calls. Budget: $5.00 (3% used). Remaining: $4.85.",
+                    action: "VIEW_SPENDING",
+                },
+            },
+        ],
+    ],
+};

package/dist/index.d.ts

@@ -3,7 +3,9 @@ export { Minia2aPluginConfig } from "./types";
 export { searchApisAction } from "./actions/searchApis";
 export { callApiAction } from "./actions/callApi";
 export { listPopularAction } from "./actions/listPopular";
+export { viewSpendingAction } from "./actions/viewSpending";
 export { marketplaceStatsProvider } from "./providers/marketplaceStats";
+export { initSpendingTracker, getSpending, getSpendSummary, canAfford, recordSpend, resetSpending } from "./spending";
 /**
  * minia2a.uk plugin for ElizaOS
  *
@@ -11,12 +13,15 @@ export { marketplaceStatsProvider } from "./providers/marketplaceStats";
  * - Search 299+ x402 pay-per-call APIs (SEARCH_APIS)
  * - Call any endpoint with auto-trial support (CALL_API)
  * - Browse trending/popular services (LIST_POPULAR_APIS)
+ * - Track and control API spending per session (VIEW_SPENDING)
  * - Get marketplace stats injected into agent context (MINIA2A_MARKETPLACE provider)
  *
  * 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
  *
  * @example
  * ```json
@@ -26,7 +31,8 @@ export { marketplaceStatsProvider } from "./providers/marketplaceStats";
  *   "settings": {
  *     "MINIA2A_CONFIG": {
  *       "autoTrial": true,
- *       "maxPricePerCall": 0.10
+ *       "maxPricePerCall": 0.10,
+ *       "maxSpendPerSession": 500
  *     }
  *   }
  * }

package/dist/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.minia2aPlugin = exports.marketplaceStatsProvider = exports.listPopularAction = exports.callApiAction = exports.searchApisAction = void 0;
+exports.minia2aPlugin = exports.resetSpending = exports.recordSpend = exports.canAfford = exports.getSpendSummary = exports.getSpending = exports.initSpendingTracker = exports.marketplaceStatsProvider = exports.viewSpendingAction = exports.listPopularAction = exports.callApiAction = exports.searchApisAction = void 0;
 const searchApis_1 = require("./actions/searchApis");
 const callApi_1 = require("./actions/callApi");
 const listPopular_1 = require("./actions/listPopular");
+const viewSpending_1 = require("./actions/viewSpending");
 const marketplaceStats_1 = require("./providers/marketplaceStats");
 var searchApis_2 = require("./actions/searchApis");
 Object.defineProperty(exports, "searchApisAction", { enumerable: true, get: function () { return searchApis_2.searchApisAction; } });
@@ -11,8 +12,17 @@ var callApi_2 = require("./actions/callApi");
 Object.defineProperty(exports, "callApiAction", { enumerable: true, get: function () { return callApi_2.callApiAction; } });
 var listPopular_2 = require("./actions/listPopular");
 Object.defineProperty(exports, "listPopularAction", { enumerable: true, get: function () { return listPopular_2.listPopularAction; } });
+var viewSpending_2 = require("./actions/viewSpending");
+Object.defineProperty(exports, "viewSpendingAction", { enumerable: true, get: function () { return viewSpending_2.viewSpendingAction; } });
 var marketplaceStats_2 = require("./providers/marketplaceStats");
 Object.defineProperty(exports, "marketplaceStatsProvider", { enumerable: true, get: function () { return marketplaceStats_2.marketplaceStatsProvider; } });
+var spending_1 = require("./spending");
+Object.defineProperty(exports, "initSpendingTracker", { enumerable: true, get: function () { return spending_1.initSpendingTracker; } });
+Object.defineProperty(exports, "getSpending", { enumerable: true, get: function () { return spending_1.getSpending; } });
+Object.defineProperty(exports, "getSpendSummary", { enumerable: true, get: function () { return spending_1.getSpendSummary; } });
+Object.defineProperty(exports, "canAfford", { enumerable: true, get: function () { return spending_1.canAfford; } });
+Object.defineProperty(exports, "recordSpend", { enumerable: true, get: function () { return spending_1.recordSpend; } });
+Object.defineProperty(exports, "resetSpending", { enumerable: true, get: function () { return spending_1.resetSpending; } });
 /**
  * minia2a.uk plugin for ElizaOS
  *
@@ -20,12 +30,15 @@ Object.defineProperty(exports, "marketplaceStatsProvider", { enumerable: true, g
  * - Search 299+ x402 pay-per-call APIs (SEARCH_APIS)
  * - Call any endpoint with auto-trial support (CALL_API)
  * - Browse trending/popular services (LIST_POPULAR_APIS)
+ * - Track and control API spending per session (VIEW_SPENDING)
  * - Get marketplace stats injected into agent context (MINIA2A_MARKETPLACE provider)
  *
  * 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
  *
  * @example
  * ```json
@@ -35,7 +48,8 @@ Object.defineProperty(exports, "marketplaceStatsProvider", { enumerable: true, g
  *   "settings": {
  *     "MINIA2A_CONFIG": {
  *       "autoTrial": true,
- *       "maxPricePerCall": 0.10
+ *       "maxPricePerCall": 0.10,
+ *       "maxSpendPerSession": 500
  *     }
  *   }
  * }
@@ -44,13 +58,14 @@ Object.defineProperty(exports, "marketplaceStatsProvider", { enumerable: true, g
 exports.minia2aPlugin = {
     name: "@minia2a/elizaos-plugin-minia2a",
     npmName: "@minia2a/elizaos-plugin-minia2a",
-    description: "Discover and call 299+ x402 pay-per-call APIs from minia2a.uk. Search, free trials, and USDC payments on Base.",
+    description: "Discover and call 299+ x402 pay-per-call APIs from minia2a.uk. Search, free trials, budget controls, and USDC payments on Base.",
     config: {
         baseUrl: "https://minia2a.uk",
         autoTrial: true,
         maxPricePerCall: 0,
+        maxSpendPerSession: 0,
     },
-    actions: [searchApis_1.searchApisAction, callApi_1.callApiAction, listPopular_1.listPopularAction],
+    actions: [searchApis_1.searchApisAction, callApi_1.callApiAction, listPopular_1.listPopularAction, viewSpending_1.viewSpendingAction],
     providers: [marketplaceStats_1.marketplaceStatsProvider],
 };
 exports.default = exports.minia2aPlugin;

package/dist/spending.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+interface SessionSpend {
+    totalCents: number;
+    callCount: number;
+    maxBudgetCents: number;
+    startTime: number;
+}
+export declare function initSpendingTracker(runtimeId: string, maxSpendPerSession: number): void;
+export declare function getSpending(runtimeId: string): SessionSpend | undefined;
+export declare function canAfford(runtimeId: string, priceCents: number): {
+    allowed: boolean;
+    reason?: string;
+};
+export declare function recordSpend(runtimeId: string, priceCents: number): void;
+export declare function getSpendSummary(runtimeId: string): string;
+export declare function resetSpending(runtimeId: string): void;
+export {};

package/dist/spending.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initSpendingTracker = initSpendingTracker;
+exports.getSpending = getSpending;
+exports.canAfford = canAfford;
+exports.recordSpend = recordSpend;
+exports.getSpendSummary = getSpendSummary;
+exports.resetSpending = resetSpending;
+const sessions = new Map();
+function getSessionId(runtimeId) {
+    return `minia2a-spend-${runtimeId}`;
+}
+function initSpendingTracker(runtimeId, maxSpendPerSession) {
+    const sessionId = getSessionId(runtimeId);
+    if (!sessions.has(sessionId)) {
+        sessions.set(sessionId, {
+            totalCents: 0,
+            callCount: 0,
+            maxBudgetCents: maxSpendPerSession,
+            startTime: Date.now(),
+        });
+    }
+}
+function getSpending(runtimeId) {
+    return sessions.get(getSessionId(runtimeId));
+}
+function canAfford(runtimeId, priceCents) {
+    const session = sessions.get(getSessionId(runtimeId));
+    if (!session)
+        return { allowed: true }; // No tracker = no limit
+    if (session.maxBudgetCents === 0)
+        return { allowed: true }; // Unlimited
+    const projected = session.totalCents + priceCents;
+    if (projected > session.maxBudgetCents) {
+        return {
+            allowed: false,
+            reason: `Budget exceeded: $${(session.totalCents / 100).toFixed(2)} spent + $${(priceCents / 100).toFixed(2)} would exceed $${(session.maxBudgetCents / 100).toFixed(2)} session limit`,
+        };
+    }
+    return { allowed: true };
+}
+function recordSpend(runtimeId, priceCents) {
+    const session = sessions.get(getSessionId(runtimeId));
+    if (session) {
+        session.totalCents += priceCents;
+        session.callCount++;
+    }
+}
+function getSpendSummary(runtimeId) {
+    const session = sessions.get(getSessionId(runtimeId));
+    if (!session)
+        return "No spending tracker active.";
+    const elapsed = Math.round((Date.now() - session.startTime) / 1000);
+    const budgetStatus = session.maxBudgetCents === 0
+        ? "unlimited"
+        : `$${(session.maxBudgetCents / 100).toFixed(2)} (${((session.totalCents / session.maxBudgetCents) * 100).toFixed(0)}% used)`;
+    return [
+        `💰 **Session Spending** (${elapsed}s elapsed)`,
+        `  Total spent: $${(session.totalCents / 100).toFixed(2)} across ${session.callCount} paid call(s)`,
+        `  Budget: ${budgetStatus}`,
+        session.maxBudgetCents > 0
+            ? `  Remaining: $${((session.maxBudgetCents - session.totalCents) / 100).toFixed(2)}`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function resetSpending(runtimeId) {
+    sessions.delete(getSessionId(runtimeId));
+}

package/dist/types.d.ts

@@ -37,4 +37,6 @@ export interface Minia2aPluginConfig {
     maxPricePerCall?: number;
     /** Wallet private key for signing x402 payments on Base */
     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.1.1",
-  "description": "ElizaOS plugin for minia2a.uk — discover and call 299+ x402 pay-per-call APIs from your agent",
+  "version": "0.2.0",
+  "description": "ElizaOS plugin for the minia2a.uk marketplace — 299+ x402 pay-per-call APIs across crypto, web, AI, and data. 15 free trials per endpoint. USDC on Base.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -18,10 +18,19 @@
     "x402",
     "minia2a",
     "agent-payments",
+    "pay-per-call",
     "usdc",
+    "base",
     "m2m",
     "ai-agent",
-    "marketplace"
+    "marketplace",
+    "micropayments",
+    "web-scraping",
+    "crypto-data",
+    "captcha-solving",
+    "ai-inference",
+    "api-discovery",
+    "agent-economy"
   ],
   "author": "minia2a.uk",
   "license": "MIT",