{"_id":"@agent-economy-wallet/core","_rev":"2-db170ad880ce956f920708d009611d15","name":"@agent-economy-wallet/core","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@agent-economy-wallet/core","version":"1.0.0","_id":"@agent-economy-wallet/core@1.0.0","maintainers":[{"name":"xavierscript","email":"david111francisco@gmail.com"}],"dist":{"shasum":"1e07d92881e6fb6fd1563f5654e3002df96935f1","tarball":"https://registry.npmjs.org/@agent-economy-wallet/core/-/core-1.0.0.tgz","fileCount":149,"integrity":"sha512-yoqWRQA02vT7HQcMIP1JelotEbvYbyMBdyYUreUcDUilZq/ihdT9lSWFcwSciqBhdV2vPQsrBtRJ6uac5FuhHg==","signatures":[{"sig":"MEQCICJqlOQe7BkRt29Z/ZezkJRWi5ubNnzhPINXXPEBagE/AiAVTkDFH6wCIWDagnFsASFbmz+CrpqCy7OOaEREX7eH4A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":595876},"main":"./dist/index.js","type":"module","_from":"file:agent-economy-wallet-core-1.0.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rimraf dist"},"_npmUser":{"name":"xavierscript","email":"david111francisco@gmail.com"},"_resolved":"C:\\Users\\HP\\AppData\\Local\\Temp\\0a8a43b4aa18d1d140c5569cb91c2160\\agent-economy-wallet-core-1.0.0.tgz","_integrity":"sha512-yoqWRQA02vT7HQcMIP1JelotEbvYbyMBdyYUreUcDUilZq/ihdT9lSWFcwSciqBhdV2vPQsrBtRJ6uac5FuhHg==","_npmVersion":"11.0.0","description":"Solana wallet SDK for autonomous AI agents — keypair generation, encrypted storage, transaction signing, policy enforcement","directories":{},"_nodeVersion":"24.11.0","dependencies":{"bs58":"^6.0.0","uuid":"^9.0.0","dotenv":"^16.4.5","tweetnacl":"^1.0.3","@solana/web3.js":"^1.95.0","@solana/spl-token":"^0.4.6","@modelcontextprotocol/sdk":"^1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"rimraf":"^5.0.0","vitest":"^1.6.0","typescript":"^5.4.0","@types/uuid":"^9.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_1.0.0_1774959243201_0.3000563150925004","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@agent-economy-wallet/core","version":"1.0.1","description":"Solana wallet SDK for autonomous AI agents — keypair generation, encrypted storage, transaction signing, policy enforcement","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","@solana/spl-token":"^0.4.6","@solana/web3.js":"^1.95.0","bs58":"^6.0.0","dotenv":"^16.4.5","tweetnacl":"^1.0.3","uuid":"^9.0.0"},"devDependencies":{"@types/uuid":"^9.0.0","rimraf":"^5.0.0","typescript":"^5.4.0","vitest":"^1.6.0"},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","clean":"rimraf dist"},"_id":"@agent-economy-wallet/core@1.0.1","_integrity":"sha512-WXQl6CedKaShhUm9xJCsIU6GQwYqbcnkyekefhhkob5yv7+GymEVIw5K0vJeXq2fX7L/SEIxlaEbYDan1HWmMA==","_resolved":"C:\\Users\\HP\\AppData\\Local\\Temp\\db30c17ef1051cb915cf00f955d6273a\\agent-economy-wallet-core-1.0.1.tgz","_from":"file:agent-economy-wallet-core-1.0.1.tgz","_nodeVersion":"24.11.0","_npmVersion":"11.0.0","dist":{"integrity":"sha512-WXQl6CedKaShhUm9xJCsIU6GQwYqbcnkyekefhhkob5yv7+GymEVIw5K0vJeXq2fX7L/SEIxlaEbYDan1HWmMA==","shasum":"dc1216e5ed3d029ea6e4f3dfd3579ef35cc09c9a","tarball":"https://registry.npmjs.org/@agent-economy-wallet/core/-/core-1.0.1.tgz","fileCount":150,"unpackedSize":603357,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDfA47vfmy/ctzjIwrZ9gPdZ71nwI4iN7qoWcWirjJ+dAIhAL9y3jkeZ6s4beLSNtwRD32zREoPj25Rcw6jsRfHyqzy"}]},"_npmUser":{"name":"xavierscript","email":"david111francisco@gmail.com"},"directories":{},"maintainers":[{"name":"xavierscript","email":"david111francisco@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_1.0.1_1774961315518_0.4858119940297201"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T12:14:03.124Z","modified":"2026-03-31T12:48:35.766Z","1.0.0":"2026-03-31T12:14:03.353Z","1.0.1":"2026-03-31T12:48:35.659Z"},"description":"Solana wallet SDK for autonomous AI agents — keypair generation, encrypted storage, transaction signing, policy enforcement","maintainers":[{"name":"xavierscript","email":"david111francisco@gmail.com"}],"readme":"# @agent-economy-wallet/core\n\nThe cryptographic and on-chain protocol foundation for the [Agent Economy Wallet](https://github.com/xavierScript/agent-economy-wallet). Every other package in the ecosystem depends on this one.\n\n> **If you just want to integrate the agent marketplace into your app, install [`agent-economy-wallet`](https://www.npmjs.com/package/agent-economy-wallet) instead — it re-exports everything from this package plus higher-level helpers.**\n\n## Installation\n\n```bash\npnpm add @agent-economy-wallet/core\n```\n\n```bash\nnpm install @agent-economy-wallet/core\n```\n\n> **Node.js ≥ 18 required.**\n\n---\n\n## What's Inside\n\n| Module | Export | Description |\n|--------|--------|-------------|\n| **Core** | `createCoreServices()` | Factory — wires all services from environment |\n| **Core** | `WalletService` | Wallet CRUD, signing, balance queries |\n| **Core** | `KeyManager` | AES-256-GCM + PBKDF2 encrypted keystore |\n| **Core** | `PolicyEngine` | Immutable spending guardrails for all transfers |\n| **Core** | `AuditLogger` | Tamper-evident logging for every action |\n| **Core** | `SolanaConnection` | Managed Solana RPC connection wrapper |\n| **Protocol** | `TransactionBuilder` | Assemble and sign Solana transactions |\n| **Protocol** | `SplTokenService` | Mint, transfer, and query SPL tokens |\n| **Protocol** | `X402Client` | Buyer-side autonomous x402 payment client |\n| **Protocol** | `X402ServerService` | Merchant-side x402 transaction verification |\n| **Protocol** | `withX402Paywall` | Low-level Express middleware for x402 gating |\n| **Registry** | `discoverRegistry` | Scan Solana on-chain for registered merchants |\n| **Registry** | `buildRegistrationTx` | Build SPL Memo registration transaction |\n| **Relay** | `KoraService` | Gasless transaction relay via Kora paymaster |\n| **Relay** | `MasterFunder` | Auto-fund new agent wallets from a master key |\n| **Utility** | `WELL_KNOWN_TOKENS` | Symbol → mint address map (USDC, WSOL, etc.) |\n| **Utility** | `getDefaultConfig` | Read and validate env vars into `AgentWalletConfig` |\n\n---\n\n## Environment Variables\n\n```env\n# Required\nWALLET_PASSPHRASE=your-strong-passphrase-here\nSOLANA_RPC_URL=https://api.devnet.solana.com\nSOLANA_CLUSTER=devnet\nOWNER_ADDRESS=YourBase58PublicKeyHere\n\n# Optional — auto-fund new wallets\nMASTER_WALLET_SECRET_KEY=your-base58-master-key   # or use MASTER_WALLET_KEY_LABEL\nMASTER_WALLET_KEY_LABEL=master-funder              # preferred (uses AES-encrypted keystore)\nAGENT_SEED_SOL=0.01\n\n# Optional — gasless transactions\nKORA_RPC_URL=http://localhost:8080\n```\n\n---\n\n## Usage\n\n### createCoreServices()\n\nBootstrap every service from your environment in one line. Shared by the CLI, MCP server, and SDK:\n\n```typescript\nimport { createCoreServices } from \"@agent-economy-wallet/core\";\n\nconst services = createCoreServices();\n// services.walletService\n// services.keyManager\n// services.policyEngine\n// services.auditLogger\n// services.connection\n// services.txBuilder\n// services.splTokenService\n// services.x402Server\n// services.masterFunder  (null if not configured)\n// services.koraService   (null if not configured)\n```\n\n### WalletService — Create a Wallet\n\n```typescript\nimport { createCoreServices, type Policy } from \"@agent-economy-wallet/core\";\n\nconst { walletService } = createCoreServices();\n\n// Signature: createWallet(label?, policy?, metadata?, autoFund?)\nconst wallet = await walletService.createWallet(\n  \"my-agent\",    // label\n  undefined,     // policy (see below)\n  {},            // metadata\n  true,          // autoFund from master wallet\n);\n\n/*\n  Returns WalletInfo:\n  {\n    id: string;\n    label: string;\n    publicKey: string;\n    balanceSol: number;\n    balanceLamports: number;\n    createdAt: string;\n    metadata: Record<string, unknown>;\n  }\n*/\n```\n\n### PolicyEngine — Enforcing Spending Limits\n\nPolicies are attached at wallet creation (or later) and enforced on every `signAndSendTransaction` call:\n\n```typescript\nimport { createCoreServices, type Policy } from \"@agent-economy-wallet/core\";\n\nconst { walletService, policyEngine } = createCoreServices();\n\nconst policy: Policy = {\n  maxSolPerTx: 0.05,         // SOL cap per single transaction\n  dailySolLimit: 0.5,         // rolling 24-hour SOL cap\n  maxTxPerHour: 20,           // rate limit\n  allowedPrograms: [          // on-chain program whitelist\n    \"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA\", // SPL Token\n  ],\n};\n\nconst wallet = await walletService.createWallet(\"safe-agent\", policy);\n\n// Or attach/update a policy after creation\npolicyEngine.attachPolicy(wallet.id, policy);\n```\n\n### Signing a Transaction\n\n```typescript\nconst { walletService, txBuilder } = createCoreServices();\nconst wallet = await walletService.createWallet(\"signer\");\n\n// Build a SOL transfer transaction\nconst tx = await txBuilder.buildSolTransfer(\n  wallet.publicKey,\n  \"RecipientBase58Address\",\n  0.01 * 1e9  // lamports\n);\n\n// Signature: signAndSendTransaction(walletId, tx, context?, additionalSigners?)\nconst result = await walletService.signAndSendTransaction(\n  wallet.id,\n  tx,\n  { action: \"sol:transfer\", details: { to: \"RecipientBase58Address\" } }\n);\n\n/*\n  Returns TransactionResult:\n  {\n    signature: string;      // base58 tx signature\n    gasless: boolean;       // true if Kora relay was used\n    network: string;        // \"devnet\" | \"mainnet-beta\"\n    explorerUrl: string;    // https://explorer.solana.com/tx/...\n  }\n*/\n```\n\n### Registry — Discover and Register Merchants\n\n```typescript\nimport {\n  discoverRegistry,\n  buildRegistrationTx,\n  createCoreServices,\n} from \"@agent-economy-wallet/core\";\n\nconst { walletService, connection } = createCoreServices();\nconst conn = connection.getConnection();\n\n// Discover all merchants registered on-chain\n// discoverRegistry(connection, limit?)\nconst merchants = await discoverRegistry(conn, 100);\n// Each: { publicKey, manifestUrl, registeredAt, signature }\n\n// Register your own merchant\n// buildRegistrationTx(connection, publicKey, manifestUrl)\nconst { walletId, transaction } = await buildRegistrationTx(\n  conn,\n  wallet.publicKey,\n  \"https://my-agent.com/.well-known/agent.json\"\n);\nconst result = await walletService.signAndSendTransaction(walletId, transaction);\nconsole.log(result.explorerUrl);\n```\n\n### x402 — Gating an Express Endpoint (Merchant)\n\n```typescript\nimport express from \"express\";\nimport {\n  createCoreServices,\n  withX402Paywall,\n  WELL_KNOWN_TOKENS,\n} from \"@agent-economy-wallet/core\";\n\nconst app = express();\nconst services = createCoreServices();\n\n// withX402Paywall(services, amountInBaseUnits, mintAddress)\n// 100_000 = 0.1 USDC (6 decimals)\napp.get(\n  \"/api/data\",\n  withX402Paywall(services, 100_000, WELL_KNOWN_TOKENS.USDC),\n  (req, res) => res.json({ result: \"Paid access only\" })\n);\n\napp.listen(3000);\n```\n\n---\n\n## Security Architecture\n\n- **Keys never leave the encrypted keystore.** AI agents only ever see public key references. `unlockWallet()` loads the decrypted keypair into memory for a single signing operation and does not store it.\n- **PBKDF2 key derivation** with 210,000 SHA-512 iterations from `WALLET_PASSPHRASE`.\n- **`closeWallet()` is human-only.** It requires `{ humanInitiated: true }` — a literal type that cannot be satisfied by any MCP tool schema, making it a compile-time barrier against agent-initiated key deletion.\n- **`AuditLogger`** persists every action (success or failure) out of process, so audit trails survive even if the agent crashes.\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md"}