{"_id":"@agent-wallet/mastra-plugin","_rev":"2-9dee4ffa56982499d79f6e32e9ea8519","name":"@agent-wallet/mastra-plugin","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agent-wallet/mastra-plugin","version":"1.0.0","keywords":["mastra","ai-agent","wallet","x402","usdc","payments","web3","non-custodial","base","cctp","spend-limits","agentwallet"],"author":{"name":"AI Agent Economy","email":"max@ai-agent-economy.com"},"license":"MIT","_id":"@agent-wallet/mastra-plugin@1.0.0","maintainers":[{"name":"up2itnow5280","email":"up2itnow@msn.com"}],"homepage":"https://ai-agent-economy.com","bugs":{"url":"https://github.com/up2itnow/mastra-plugin/issues"},"dist":{"shasum":"11f32325ad2b63118c393b16d4fcddb62888beeb","tarball":"https://registry.npmjs.org/@agent-wallet/mastra-plugin/-/mastra-plugin-1.0.0.tgz","fileCount":14,"integrity":"sha512-woQVnjuSPub1A2vqa32RCtW9Iiq9gWeFeZvBmuUXwVmNi9fLfvpogigEiO5jDKcJjCoTv2Pvah0g8oGAqjESwQ==","signatures":[{"sig":"MEYCIQDY288HLsF/pFR6WTou7mgNFJQPQC1v4mVfCtzUOljViQIhAMakSCoNOadvC8tv7irKZQ8GdI8jzSE5dBlro59tlYA9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1425877},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm run test"},"_npmUser":{"name":"up2itnow5280","email":"up2itnow@msn.com"},"repository":{"url":"git+https://github.com/up2itnow/mastra-plugin.git","type":"git"},"_npmVersion":"11.8.0","description":"Non-custodial wallet + x402 payments for Mastra agents","directories":{},"_nodeVersion":"25.6.0","_hasShrinkwrap":false,"devDependencies":{"zod":"^3.24.1","tsup":"^8.3.5","viem":"^2.21.54","vitest":"^3.0.5","typescript":"^5.7.3","@types/node":"^22.0.0","@mastra/core":"^0.10.5","agentwallet-sdk":"^2.4.1"},"peerDependencies":{"zod":">=3.0.0","@mastra/core":">=0.10.0","agentwallet-sdk":">=2.4.0"},"peerDependenciesMeta":{"agentwallet-sdk":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/mastra-plugin_1.0.0_1771825504689_0.36158712658592496","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package has moved to 'agentwallet-mastra-plugin'. Install: npm i agentwallet-mastra-plugin"}},"time":{"created":"2026-02-23T05:45:04.604Z","modified":"2026-03-22T21:22:25.128Z","1.0.0":"2026-02-23T05:45:04.825Z"},"bugs":{"url":"https://github.com/up2itnow/mastra-plugin/issues"},"author":{"name":"AI Agent Economy","email":"max@ai-agent-economy.com"},"license":"MIT","homepage":"https://ai-agent-economy.com","keywords":["mastra","ai-agent","wallet","x402","usdc","payments","web3","non-custodial","base","cctp","spend-limits","agentwallet"],"repository":{"url":"git+https://github.com/up2itnow/mastra-plugin.git","type":"git"},"description":"Non-custodial wallet + x402 payments for Mastra agents","maintainers":[{"name":"up2itnow5280","email":"up2itnow@msn.com"}],"readme":"# agentwallet-mastra-plugin\n\nNon-custodial wallet + x402 payments + spend limits for [Mastra](https://mastra.ai) AI agents. Add complete on-chain payment capability to any Mastra agent in one line.\n\n```typescript\ntools: createAgentWalletTools({ privateKey: process.env.AGENT_PRIVATE_KEY })\n```\n\n[![npm version](https://badge.fury.io/js/%40agentwallet%2Fmastra-plugin.svg)](https://www.npmjs.com/package/agentwallet-mastra-plugin)\n[![Tests](https://img.shields.io/badge/tests-71%20passing-brightgreen)](https://github.com/up2itnow/mastra-plugin)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## What This Does\n\nMastra gives you a powerful agent framework. What it doesn't give you is the ability for agents to pay for things. This plugin closes that gap.\n\nYour agents get:\n- A **non-custodial wallet** on Base (they control their own keys)\n- **USDC + ETH balance** checking\n- **USDC payments** to any address\n- **x402 payments** — automatic handling of HTTP 402 payment flows for paid APIs and data services\n- **Cross-chain bridging** via Circle CCTP V2 (Base → Ethereum/Optimism/Arbitrum)\n- **Spend limits** — per-transaction and daily caps you configure as the developer\n- **Transaction history** — direct on-chain queries, no indexer required\n\n## Install\n\n```bash\nnpm install agentwallet-mastra-plugin agentwallet-sdk\n```\n\nBoth packages are required. `agentwallet-sdk` is a peer dependency containing the on-chain logic.\n\n## Quick Start\n\n```typescript\nimport { createAgentWalletTools } from 'agentwallet-mastra-plugin';\nimport { Agent } from '@mastra/core';\nimport { openai } from '@ai-sdk/openai';\n\nconst agent = new Agent({\n  name: 'PayingAgent',\n  instructions: 'You can make payments using your wallet.',\n  model: openai('gpt-4o'),\n  tools: createAgentWalletTools({\n    privateKey: process.env.AGENT_PRIVATE_KEY!,\n  }),\n});\n\nconst result = await agent.generate('What is my wallet address?');\n```\n\n## Configuration\n\n```typescript\nimport { createAgentWalletTools } from 'agentwallet-mastra-plugin';\n\nconst tools = createAgentWalletTools({\n  // Required: the agent's private key\n  // Store this in a secrets manager, not in code\n  privateKey: process.env.AGENT_PRIVATE_KEY!,\n\n  // Optional: custom RPC endpoint (defaults to Base Mainnet public RPC)\n  rpcUrl: process.env.BASE_RPC_URL,\n\n  // Optional: enforce spending guardrails\n  spendLimits: {\n    perTxLimitUsdc: 10,   // max $10 per transaction\n    dailyLimitUsdc: 100,  // max $100 per day (rolling 24h window)\n  },\n\n  // Optional: use testnet during development\n  network: 'mainnet', // or 'testnet' (Base Sepolia)\n});\n```\n\n## The 10 Tools\n\nEach tool is registered with Mastra using `createTool` with strict Zod schemas. The agent sees them as normal tools and can call them naturally in conversation.\n\n---\n\n### `getWalletAddress`\n\nReturns the agent's wallet address on Base. Use this to display the wallet or receive payments.\n\n**Input:** _(none)_\n\n**Output:**\n```typescript\n{\n  success: true,\n  address: \"0xf39F...\",\n  network: \"Base (chainId: 8453)\"\n}\n```\n\n---\n\n### `getWalletBalance`\n\nReturns USDC and ETH balances. Check this before attempting payments.\n\n**Input:** _(none)_\n\n**Output:**\n```typescript\n{\n  success: true,\n  address: \"0xf39F...\",\n  usdcBalance: \"42.5\",     // human-readable\n  ethBalance: \"0.01\",      // human-readable\n  usdcRaw: \"42500000\",     // base units (6 decimals)\n  ethRaw: \"10000000000000000\"\n}\n```\n\n---\n\n### `createWallet`\n\nGenerates a new non-custodial wallet. Returns the public address and a masked key hint.\n\n**Input:**\n```typescript\n{ label?: string }  // optional name for your records\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  address: \"0xABCD...\",\n  privateKeyHint: \"0xac0974...2ff80 (store the full key securely)\",\n  warning: \"IMPORTANT: Store the private key in a secure secrets manager immediately.\",\n  label: \"my-agent-wallet\"\n}\n```\n\n> ⚠️ The private key appears **once** in the hint. Store it immediately in AWS Secrets Manager, HashiCorp Vault, or equivalent. This plugin never logs or transmits private keys.\n\n---\n\n### `sendPayment`\n\nSend USDC to any address on Base. Enforces spend limits before submitting.\n\n**Input:**\n```typescript\n{\n  to: string;          // \"0x...\" recipient address\n  amountUsdc: number;  // e.g. 5.00 for $5.00\n  memo?: string;       // optional off-chain note\n}\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  txHash: \"0xabc...\",\n  amountUsdc: 5,\n  to: \"0x70997...\",\n  explorerUrl: \"https://basescan.org/tx/0xabc...\"\n}\n```\n\n**Error cases:** `SPEND_LIMIT_EXCEEDED`, `INSUFFICIENT_BALANCE`, `NETWORK_ERROR`\n\n---\n\n### `x402Pay`\n\nMake an HTTP request to a URL that requires x402 payment. Handles the entire payment flow automatically: detects the 402 response, pays in USDC on Base, then retries the original request.\n\n**Input:**\n```typescript\n{\n  url: string;              // URL to fetch\n  method?: string;          // GET, POST, PUT, DELETE, PATCH (default: GET)\n  body?: string;            // JSON body for POST/PUT\n  maxPaymentUsdc?: number;  // max willing to pay (default: 1 USDC)\n}\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  statusCode: 200,\n  responseBody: \"...\",\n  paymentMade: true\n}\n```\n\n**Use cases:** Paid data feeds, premium AI APIs, TaskBridge task payments.\n\n---\n\n### `bridgePayment`\n\nBridge USDC from Base to another chain using Circle CCTP V2. Non-custodial — all signing happens locally.\n\n**Input:**\n```typescript\n{\n  amountUsdc: number;              // amount to bridge\n  destinationChain: string;        // \"ethereum\" | \"optimism\" | \"arbitrum\"\n  destinationAddress?: string;     // recipient (defaults to agent's own address)\n  fastFinality?: boolean;          // true = ~12s, false = ~15min (default: true)\n}\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  burnTxHash: \"0xburn...\",\n  mintTxHash: \"0xmint...\",\n  amountUsdc: 50,\n  destinationChain: \"optimism\",\n  status: \"completed\"\n}\n```\n\n---\n\n### `getPortfolio`\n\nFull financial snapshot: balances, network, block height, and timestamp.\n\n**Input:** _(none)_\n\n**Output:**\n```typescript\n{\n  success: true,\n  address: \"0xf39F...\",\n  usdcBalance: \"100\",\n  ethBalance: \"0.05\",\n  blockNumber: \"23456789\",\n  timestamp: \"2026-02-22T10:00:00.000Z\"\n}\n```\n\n---\n\n### `getTransactionHistory`\n\nRecent USDC transfer history, queried directly from Base event logs. No indexer required.\n\n**Input:**\n```typescript\n{\n  limit?: number;          // max results (1-100, default: 20)\n  lookbackBlocks?: number; // blocks to search (default: 10000 ≈ ~6h on Base)\n}\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  transactions: [\n    {\n      blockNumber: \"23456000\",\n      txHash: \"0xabc...\",\n      direction: \"outgoing\",\n      amountUsdc: \"5\",\n      counterparty: \"0x70997...\"\n    }\n  ],\n  totalFound: 12,\n  blocksSearched: 10000\n}\n```\n\n---\n\n### `getSpendLimits`\n\nInspect the current spend limit configuration. Agents can use this to understand what they're authorized to spend before planning a series of payments.\n\n**Input:** _(none)_\n\n**Output:**\n```typescript\n{\n  success: true,\n  limitsConfigured: true,\n  perTxLimitUsdc: 10,\n  dailyLimitUsdc: 100,\n  spentTodayUsdc: 15.5,\n  remainingDailyUsdc: 84.5,\n  windowResetInMs: 43200000\n}\n```\n\n---\n\n### `checkSpendAllowance`\n\nPre-flight check: verify a specific amount is within limits before attempting a payment. Doesn't execute anything.\n\n**Input:**\n```typescript\n{ amountUsdc: number }\n```\n\n**Output:**\n```typescript\n{\n  success: true,\n  allowed: false,\n  amountUsdc: 15,\n  blockedBy: \"per-transaction limit (10 USDC)\",\n  perTxCheck: { limit: 10, withinLimit: false },\n  dailyCheck: { limit: 100, spentToday: 15.5, wouldSpend: 30.5, withinLimit: true }\n}\n```\n\n---\n\n## Why Non-Custodial\n\n**Custodial wallets** (like hosted API services) hold your agent's private key. This means:\n- If the service is compromised, your funds are at risk\n- The service can censor or freeze transactions\n- You have a third-party dependency in your payments stack\n- Privacy: the service knows every transaction your agent makes\n\n**Non-custodial wallets** keep the private key in your environment:\n- Only your agent can sign transactions\n- No counterparty risk\n- No third-party censorship\n- Works offline/airgapped (except for RPC calls)\n\nThis plugin is built on `agentwallet-sdk`, which handles on-chain operations using [viem](https://viem.sh). Your private key never leaves the process that runs your agent.\n\n## Security\n\n### Private Key Handling\n\n- The private key is passed in at plugin initialization and stored in memory only\n- It is **never** logged, never serialized, never included in tool outputs\n- `createWallet` shows a masked key hint — not the full key\n- Use environment variables (or a secrets manager) to inject the key at runtime\n\n```bash\n# Never hardcode keys. Always use environment variables:\nAGENT_PRIVATE_KEY=0x... node my-agent.js\n```\n\n### Spend Limits\n\nSpend limits are enforced synchronously before any transaction reaches the blockchain. They're intentionally simple and conservative:\n\n```typescript\nspendLimits: {\n  perTxLimitUsdc: 5,    // Each payment: max $5\n  dailyLimitUsdc: 50,   // Per day: max $50\n}\n```\n\nLimits reset on a rolling 24-hour window. The `checkSpendAllowance` tool lets agents verify limits before attempting payments.\n\n### What This Plugin Does NOT Do\n\n- Does not store or escrow any funds\n- Does not have a backend service or central server\n- Does not track or report transactions to any third party\n- Does not require any API key other than your RPC URL\n\n## Resources\n\n- **[agentwallet-sdk](https://www.npmjs.com/package/agentwallet-sdk)** — The underlying SDK for on-chain operations\n- **[AI Agent Economy](https://ai-agent-economy.com)** — Platform, docs, and community\n- **[TaskBridge](https://ai-agent-economy.com/taskbridge)** — Agent-native job marketplace with built-in x402 payments\n- **[Base Network](https://base.org)** — The L2 this plugin runs on (fast, cheap, EVM-compatible)\n- **[Circle CCTP V2](https://www.circle.com/en/cross-chain-transfer-protocol)** — The bridge protocol used by `bridgePayment`\n\n## Requirements\n\n- Node.js >= 18\n- `@mastra/core` >= 0.10.0\n- `agentwallet-sdk` >= 2.4.0\n- `zod` >= 3.0.0\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\nBuilt by [AI Agent Economy](https://ai-agent-economy.com). Making autonomous payments safe, sovereign, and simple.\n","readmeFilename":"README.md"}