@spraay/langchain-agent-wallet 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# 💧 @spraay/langchain-agent-wallet
+
+LangChain tools for Spraay Agent Wallet — provision smart wallets, manage session keys, and predict addresses on Base via x402 USDC micropayments.
+
+## Install
+
+```bash
+npm install @spraay/langchain-agent-wallet @langchain/core
+```
+
+## Quick Start
+
+```typescript
+import { ChatOpenAI } from "@langchain/openai";
+import { createToolCallingAgent, AgentExecutor } from "langchain/agents";
+import { ChatPromptTemplate } from "@langchain/core/prompts";
+import { createSpraayWalletTools } from "@spraay/langchain-agent-wallet";
+
+const tools = createSpraayWalletTools({
+  privateKey: process.env.EVM_PRIVATE_KEY!,
+  // gatewayUrl: "https://gateway.spraay.app" // default
+});
+
+const llm = new ChatOpenAI({ model: "gpt-4o" });
+
+const prompt = ChatPromptTemplate.fromMessages([
+  ["system", "You are a Web3 agent that can manage smart wallets on Base."],
+  ["human", "{input}"],
+  ["placeholder", "{agent_scratchpad}"],
+]);
+
+const agent = createToolCallingAgent({ llm, tools, prompt });
+const executor = new AgentExecutor({ agent, tools });
+
+const result = await executor.invoke({
+  input: "Deploy a new agent wallet for 0x1234...abcd",
+});
+```
+
+## Tools
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `spraay_provision_wallet` | Deploy a new smart wallet on Base | $0.05 |
+| `spraay_add_session_key` | Grant scoped permissions to an address | $0.02 |
+| `spraay_get_wallet_info` | Query wallet details and balance | $0.005 |
+| `spraay_revoke_session_key` | Remove a session key | $0.02 |
+| `spraay_predict_address` | Pre-compute CREATE2 wallet address | $0.001 |
+
+## Individual Tool Usage
+
+```typescript
+import { SpraayProvisionWalletTool } from "@spraay/langchain-agent-wallet";
+
+const provisionTool = new SpraayProvisionWalletTool({
+  privateKey: process.env.EVM_PRIVATE_KEY!,
+});
+
+// Use with any LangChain agent or chain
+```
+
+## Environment
+
+```env
+EVM_PRIVATE_KEY=0x...          # Required — signs x402 payments
+SPRAAY_GATEWAY_URL=https://... # Optional — override default gateway
+```
+
+## Links
+
+- [Spraay Docs](https://docs.spraay.app)
+- [x402 Protocol](https://x402.org)
+- [LangChain.js](https://js.langchain.com)
+
+## License
+
+MIT — [@plagtech](https://github.com/plagtech)

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+interface SpraayToolConfig {
+    privateKey: string;
+    gatewayUrl?: string;
+}
+declare class SpraayProvisionWalletTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        ownerAddress: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        ownerAddress: string;
+        label?: string | undefined;
+    }, {
+        ownerAddress: string;
+        label?: string | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayAddSessionKeyTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+        sessionKeyAddress: z.ZodString;
+        permissions: z.ZodArray<z.ZodString, "many">;
+        expiresIn: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+        permissions: string[];
+        expiresIn?: number | undefined;
+    }, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+        permissions: string[];
+        expiresIn?: number | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayGetWalletInfoTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+    }, {
+        walletAddress: string;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayRevokeSessionKeyTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+        sessionKeyAddress: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+    }, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayPredictAddressTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        ownerAddress: z.ZodString;
+        salt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        ownerAddress: string;
+        salt?: string | undefined;
+    }, {
+        ownerAddress: string;
+        salt?: string | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+/**
+ * Create all 5 Spraay Agent Wallet tools for LangChain.
+ *
+ * @example
+ * ```ts
+ * import { createSpraayWalletTools } from "@spraay/langchain-agent-wallet";
+ *
+ * const tools = createSpraayWalletTools({
+ *   privateKey: process.env.EVM_PRIVATE_KEY!,
+ * });
+ *
+ * const agent = createToolCallingAgent({ llm, tools, prompt });
+ * ```
+ */
+declare function createSpraayWalletTools(config: SpraayToolConfig): StructuredTool[];
+
+export { SpraayAddSessionKeyTool, SpraayGetWalletInfoTool, SpraayPredictAddressTool, SpraayProvisionWalletTool, SpraayRevokeSessionKeyTool, createSpraayWalletTools };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+import { StructuredTool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+interface SpraayToolConfig {
+    privateKey: string;
+    gatewayUrl?: string;
+}
+declare class SpraayProvisionWalletTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        ownerAddress: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        ownerAddress: string;
+        label?: string | undefined;
+    }, {
+        ownerAddress: string;
+        label?: string | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayAddSessionKeyTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+        sessionKeyAddress: z.ZodString;
+        permissions: z.ZodArray<z.ZodString, "many">;
+        expiresIn: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+        permissions: string[];
+        expiresIn?: number | undefined;
+    }, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+        permissions: string[];
+        expiresIn?: number | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayGetWalletInfoTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+    }, {
+        walletAddress: string;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayRevokeSessionKeyTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        walletAddress: z.ZodString;
+        sessionKeyAddress: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+    }, {
+        walletAddress: string;
+        sessionKeyAddress: string;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+declare class SpraayPredictAddressTool extends StructuredTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        ownerAddress: z.ZodString;
+        salt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        ownerAddress: string;
+        salt?: string | undefined;
+    }, {
+        ownerAddress: string;
+        salt?: string | undefined;
+    }>;
+    private config;
+    constructor(config: SpraayToolConfig);
+    _call(input: z.infer<typeof this.schema>): Promise<string>;
+}
+/**
+ * Create all 5 Spraay Agent Wallet tools for LangChain.
+ *
+ * @example
+ * ```ts
+ * import { createSpraayWalletTools } from "@spraay/langchain-agent-wallet";
+ *
+ * const tools = createSpraayWalletTools({
+ *   privateKey: process.env.EVM_PRIVATE_KEY!,
+ * });
+ *
+ * const agent = createToolCallingAgent({ llm, tools, prompt });
+ * ```
+ */
+declare function createSpraayWalletTools(config: SpraayToolConfig): StructuredTool[];
+
+export { SpraayAddSessionKeyTool, SpraayGetWalletInfoTool, SpraayPredictAddressTool, SpraayProvisionWalletTool, SpraayRevokeSessionKeyTool, createSpraayWalletTools };

package/dist/index.js

@@ -0,0 +1,226 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SpraayAddSessionKeyTool: () => SpraayAddSessionKeyTool,
+  SpraayGetWalletInfoTool: () => SpraayGetWalletInfoTool,
+  SpraayPredictAddressTool: () => SpraayPredictAddressTool,
+  SpraayProvisionWalletTool: () => SpraayProvisionWalletTool,
+  SpraayRevokeSessionKeyTool: () => SpraayRevokeSessionKeyTool,
+  createSpraayWalletTools: () => createSpraayWalletTools
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tools.ts
+var import_tools = require("@langchain/core/tools");
+var import_zod = require("zod");
+var import_ethers = require("ethers");
+var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var SPRAAY_PAYMENT_ADDRESS = "0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8";
+async function makePaymentHeader(wallet, amountUsd) {
+  const payload = {
+    amount: amountUsd.toString(),
+    token: USDC_BASE,
+    recipient: SPRAAY_PAYMENT_ADDRESS,
+    chain: "base",
+    timestamp: Date.now()
+  };
+  const signature = await wallet.signMessage(JSON.stringify(payload));
+  const header = Buffer.from(
+    JSON.stringify({ ...payload, signature })
+  ).toString("base64");
+  return { "X-PAYMENT": header, "Content-Type": "application/json" };
+}
+async function gatewayRequest(wallet, baseUrl, method, path, costUsd, body) {
+  const headers = await makePaymentHeader(wallet, costUsd);
+  const url = `${baseUrl}${path}`;
+  const options = { method, headers };
+  if (body && method === "POST") {
+    options.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, options);
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error || `HTTP ${res.status}`);
+  }
+  return JSON.stringify(data, null, 2);
+}
+function createWallet(config) {
+  const key = config.privateKey.startsWith("0x") ? config.privateKey : `0x${config.privateKey}`;
+  return {
+    wallet: new import_ethers.ethers.Wallet(key),
+    baseUrl: config.gatewayUrl || "https://gateway.spraay.app"
+  };
+}
+var SpraayProvisionWalletTool = class extends import_tools.StructuredTool {
+  name = "spraay_provision_wallet";
+  description = `\u{1F4A7} Provision (deploy) a new Spraay smart wallet on Base for an AI agent.
+Use this when the user wants to create/deploy a new agent wallet.
+Costs $0.05 USDC per call via x402 micropayment on Base.
+Factory: 0xFBD832Db6D9a05A0434cd497707a1bDC43389CfD
+Returns the new wallet address and deployment transaction hash.`;
+  schema = import_zod.z.object({
+    ownerAddress: import_zod.z.string().describe("The EVM address (0x...) that will own the new wallet"),
+    label: import_zod.z.string().optional().describe("Optional human-readable label for the wallet")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/provision",
+      0.05,
+      { ownerAddress: input.ownerAddress, label: input.label }
+    );
+  }
+};
+var SpraayAddSessionKeyTool = class extends import_tools.StructuredTool {
+  name = "spraay_add_session_key";
+  description = `\u{1F4A7} Add a session key to an existing Spraay agent wallet.
+Grants scoped permissions (transfer, swap, approve, etc.) to another address.
+Use when the user wants to delegate limited wallet access.
+Costs $0.02 USDC per call via x402 on Base.`;
+  schema = import_zod.z.object({
+    walletAddress: import_zod.z.string().describe("The agent wallet address to add the session key to"),
+    sessionKeyAddress: import_zod.z.string().describe("The address to grant session key access"),
+    permissions: import_zod.z.array(import_zod.z.string()).describe('Array of permissions, e.g. ["transfer", "swap"]'),
+    expiresIn: import_zod.z.number().optional().describe("Optional expiry in seconds")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/session-key",
+      0.02,
+      input
+    );
+  }
+};
+var SpraayGetWalletInfoTool = class extends import_tools.StructuredTool {
+  name = "spraay_get_wallet_info";
+  description = `\u{1F4A7} Get information about a Spraay agent wallet.
+Returns the owner, active session keys with permissions, USDC balance, and label.
+Use when the user asks about wallet status, balance, or active keys.
+Costs $0.005 USDC per call via x402 on Base.`;
+  schema = import_zod.z.object({
+    walletAddress: import_zod.z.string().describe("The agent wallet address to query")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/info?walletAddress=${input.walletAddress}`,
+      5e-3
+    );
+  }
+};
+var SpraayRevokeSessionKeyTool = class extends import_tools.StructuredTool {
+  name = "spraay_revoke_session_key";
+  description = `\u{1F4A7} Revoke a session key from a Spraay agent wallet.
+Removes all permissions from the specified session key address.
+Use when the user wants to remove access or disable a key.
+Costs $0.02 USDC per call via x402 on Base.`;
+  schema = import_zod.z.object({
+    walletAddress: import_zod.z.string().describe("The agent wallet that has the session key"),
+    sessionKeyAddress: import_zod.z.string().describe("The session key address to revoke")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/revoke-key",
+      0.02,
+      input
+    );
+  }
+};
+var SpraayPredictAddressTool = class extends import_tools.StructuredTool {
+  name = "spraay_predict_address";
+  description = `\u{1F4A7} Predict the counterfactual address of a Spraay agent wallet before deploying it.
+Uses CREATE2 deterministic addressing \u2014 the wallet can be deployed later.
+Use when the user wants to know what address their wallet will have.
+Costs $0.001 USDC per call via x402 on Base.`;
+  schema = import_zod.z.object({
+    ownerAddress: import_zod.z.string().describe("The EVM address that would own the wallet"),
+    salt: import_zod.z.string().optional().describe("Optional salt for CREATE2 derivation")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    const qs = `ownerAddress=${input.ownerAddress}${input.salt ? `&salt=${input.salt}` : ""}`;
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/predict?${qs}`,
+      1e-3
+    );
+  }
+};
+function createSpraayWalletTools(config) {
+  return [
+    new SpraayProvisionWalletTool(config),
+    new SpraayAddSessionKeyTool(config),
+    new SpraayGetWalletInfoTool(config),
+    new SpraayRevokeSessionKeyTool(config),
+    new SpraayPredictAddressTool(config)
+  ];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SpraayAddSessionKeyTool,
+  SpraayGetWalletInfoTool,
+  SpraayPredictAddressTool,
+  SpraayProvisionWalletTool,
+  SpraayRevokeSessionKeyTool,
+  createSpraayWalletTools
+});

package/dist/index.mjs

@@ -0,0 +1,194 @@
+// src/tools.ts
+import { StructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+import { ethers } from "ethers";
+var USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var SPRAAY_PAYMENT_ADDRESS = "0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8";
+async function makePaymentHeader(wallet, amountUsd) {
+  const payload = {
+    amount: amountUsd.toString(),
+    token: USDC_BASE,
+    recipient: SPRAAY_PAYMENT_ADDRESS,
+    chain: "base",
+    timestamp: Date.now()
+  };
+  const signature = await wallet.signMessage(JSON.stringify(payload));
+  const header = Buffer.from(
+    JSON.stringify({ ...payload, signature })
+  ).toString("base64");
+  return { "X-PAYMENT": header, "Content-Type": "application/json" };
+}
+async function gatewayRequest(wallet, baseUrl, method, path, costUsd, body) {
+  const headers = await makePaymentHeader(wallet, costUsd);
+  const url = `${baseUrl}${path}`;
+  const options = { method, headers };
+  if (body && method === "POST") {
+    options.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, options);
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error || `HTTP ${res.status}`);
+  }
+  return JSON.stringify(data, null, 2);
+}
+function createWallet(config) {
+  const key = config.privateKey.startsWith("0x") ? config.privateKey : `0x${config.privateKey}`;
+  return {
+    wallet: new ethers.Wallet(key),
+    baseUrl: config.gatewayUrl || "https://gateway.spraay.app"
+  };
+}
+var SpraayProvisionWalletTool = class extends StructuredTool {
+  name = "spraay_provision_wallet";
+  description = `\u{1F4A7} Provision (deploy) a new Spraay smart wallet on Base for an AI agent.
+Use this when the user wants to create/deploy a new agent wallet.
+Costs $0.05 USDC per call via x402 micropayment on Base.
+Factory: 0xFBD832Db6D9a05A0434cd497707a1bDC43389CfD
+Returns the new wallet address and deployment transaction hash.`;
+  schema = z.object({
+    ownerAddress: z.string().describe("The EVM address (0x...) that will own the new wallet"),
+    label: z.string().optional().describe("Optional human-readable label for the wallet")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/provision",
+      0.05,
+      { ownerAddress: input.ownerAddress, label: input.label }
+    );
+  }
+};
+var SpraayAddSessionKeyTool = class extends StructuredTool {
+  name = "spraay_add_session_key";
+  description = `\u{1F4A7} Add a session key to an existing Spraay agent wallet.
+Grants scoped permissions (transfer, swap, approve, etc.) to another address.
+Use when the user wants to delegate limited wallet access.
+Costs $0.02 USDC per call via x402 on Base.`;
+  schema = z.object({
+    walletAddress: z.string().describe("The agent wallet address to add the session key to"),
+    sessionKeyAddress: z.string().describe("The address to grant session key access"),
+    permissions: z.array(z.string()).describe('Array of permissions, e.g. ["transfer", "swap"]'),
+    expiresIn: z.number().optional().describe("Optional expiry in seconds")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/session-key",
+      0.02,
+      input
+    );
+  }
+};
+var SpraayGetWalletInfoTool = class extends StructuredTool {
+  name = "spraay_get_wallet_info";
+  description = `\u{1F4A7} Get information about a Spraay agent wallet.
+Returns the owner, active session keys with permissions, USDC balance, and label.
+Use when the user asks about wallet status, balance, or active keys.
+Costs $0.005 USDC per call via x402 on Base.`;
+  schema = z.object({
+    walletAddress: z.string().describe("The agent wallet address to query")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/info?walletAddress=${input.walletAddress}`,
+      5e-3
+    );
+  }
+};
+var SpraayRevokeSessionKeyTool = class extends StructuredTool {
+  name = "spraay_revoke_session_key";
+  description = `\u{1F4A7} Revoke a session key from a Spraay agent wallet.
+Removes all permissions from the specified session key address.
+Use when the user wants to remove access or disable a key.
+Costs $0.02 USDC per call via x402 on Base.`;
+  schema = z.object({
+    walletAddress: z.string().describe("The agent wallet that has the session key"),
+    sessionKeyAddress: z.string().describe("The session key address to revoke")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/revoke-key",
+      0.02,
+      input
+    );
+  }
+};
+var SpraayPredictAddressTool = class extends StructuredTool {
+  name = "spraay_predict_address";
+  description = `\u{1F4A7} Predict the counterfactual address of a Spraay agent wallet before deploying it.
+Uses CREATE2 deterministic addressing \u2014 the wallet can be deployed later.
+Use when the user wants to know what address their wallet will have.
+Costs $0.001 USDC per call via x402 on Base.`;
+  schema = z.object({
+    ownerAddress: z.string().describe("The EVM address that would own the wallet"),
+    salt: z.string().optional().describe("Optional salt for CREATE2 derivation")
+  });
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  async _call(input) {
+    const { wallet, baseUrl } = createWallet(this.config);
+    const qs = `ownerAddress=${input.ownerAddress}${input.salt ? `&salt=${input.salt}` : ""}`;
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/predict?${qs}`,
+      1e-3
+    );
+  }
+};
+function createSpraayWalletTools(config) {
+  return [
+    new SpraayProvisionWalletTool(config),
+    new SpraayAddSessionKeyTool(config),
+    new SpraayGetWalletInfoTool(config),
+    new SpraayRevokeSessionKeyTool(config),
+    new SpraayPredictAddressTool(config)
+  ];
+}
+export {
+  SpraayAddSessionKeyTool,
+  SpraayGetWalletInfoTool,
+  SpraayPredictAddressTool,
+  SpraayProvisionWalletTool,
+  SpraayRevokeSessionKeyTool,
+  createSpraayWalletTools
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@spraay/langchain-agent-wallet",
+  "version": "1.0.0",
+  "description": "💧 LangChain tools for Spraay Agent Wallet — provision smart wallets, manage session keys on Base via x402",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "langchain",
+    "spraay",
+    "agent-wallet",
+    "x402",
+    "base",
+    "smart-wallet",
+    "usdc",
+    "ai-tools"
+  ],
+  "author": "plagtech",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plagtech/langchain-spraay-wallet"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.2.0"
+  },
+  "dependencies": {
+    "spraay-agent-wallet": "^1.0.0",
+    "ethers": "^6.13.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@langchain/core": "^0.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export {
+  SpraayProvisionWalletTool,
+  SpraayAddSessionKeyTool,
+  SpraayGetWalletInfoTool,
+  SpraayRevokeSessionKeyTool,
+  SpraayPredictAddressTool,
+  createSpraayWalletTools,
+} from "./tools";

package/src/tools.ts

@@ -0,0 +1,292 @@
+import { StructuredTool } from "@langchain/core/tools";
+import { z } from "zod";
+import { ethers } from "ethers";
+
+// ── Shared Config ─────────────────────────────────────────────────
+
+const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const SPRAAY_PAYMENT_ADDRESS = "0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8";
+
+interface SpraayToolConfig {
+  privateKey: string;
+  gatewayUrl?: string;
+}
+
+async function makePaymentHeader(
+  wallet: ethers.Wallet,
+  amountUsd: number
+): Promise<Record<string, string>> {
+  const payload = {
+    amount: amountUsd.toString(),
+    token: USDC_BASE,
+    recipient: SPRAAY_PAYMENT_ADDRESS,
+    chain: "base",
+    timestamp: Date.now(),
+  };
+  const signature = await wallet.signMessage(JSON.stringify(payload));
+  const header = Buffer.from(
+    JSON.stringify({ ...payload, signature })
+  ).toString("base64");
+  return { "X-PAYMENT": header, "Content-Type": "application/json" };
+}
+
+async function gatewayRequest(
+  wallet: ethers.Wallet,
+  baseUrl: string,
+  method: "GET" | "POST",
+  path: string,
+  costUsd: number,
+  body?: Record<string, unknown>
+): Promise<string> {
+  const headers = await makePaymentHeader(wallet, costUsd);
+  const url = `${baseUrl}${path}`;
+  const options: RequestInit = { method, headers };
+  if (body && method === "POST") {
+    options.body = JSON.stringify(body);
+  }
+  const res = await fetch(url, options);
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error || `HTTP ${res.status}`);
+  }
+  return JSON.stringify(data, null, 2);
+}
+
+function createWallet(config: SpraayToolConfig): {
+  wallet: ethers.Wallet;
+  baseUrl: string;
+} {
+  const key = config.privateKey.startsWith("0x")
+    ? config.privateKey
+    : `0x${config.privateKey}`;
+  return {
+    wallet: new ethers.Wallet(key),
+    baseUrl: config.gatewayUrl || "https://gateway.spraay.app",
+  };
+}
+
+// ── Tool 1: Provision Agent Wallet ────────────────────────────────
+
+export class SpraayProvisionWalletTool extends StructuredTool {
+  name = "spraay_provision_wallet";
+  description = `💧 Provision (deploy) a new Spraay smart wallet on Base for an AI agent.
+Use this when the user wants to create/deploy a new agent wallet.
+Costs $0.05 USDC per call via x402 micropayment on Base.
+Factory: 0xFBD832Db6D9a05A0434cd497707a1bDC43389CfD
+Returns the new wallet address and deployment transaction hash.`;
+
+  schema = z.object({
+    ownerAddress: z
+      .string()
+      .describe("The EVM address (0x...) that will own the new wallet"),
+    label: z
+      .string()
+      .optional()
+      .describe("Optional human-readable label for the wallet"),
+  });
+
+  private config: SpraayToolConfig;
+
+  constructor(config: SpraayToolConfig) {
+    super();
+    this.config = config;
+  }
+
+  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/provision",
+      0.05,
+      { ownerAddress: input.ownerAddress, label: input.label }
+    );
+  }
+}
+
+// ── Tool 2: Add Session Key ───────────────────────────────────────
+
+export class SpraayAddSessionKeyTool extends StructuredTool {
+  name = "spraay_add_session_key";
+  description = `💧 Add a session key to an existing Spraay agent wallet.
+Grants scoped permissions (transfer, swap, approve, etc.) to another address.
+Use when the user wants to delegate limited wallet access.
+Costs $0.02 USDC per call via x402 on Base.`;
+
+  schema = z.object({
+    walletAddress: z
+      .string()
+      .describe("The agent wallet address to add the session key to"),
+    sessionKeyAddress: z
+      .string()
+      .describe("The address to grant session key access"),
+    permissions: z
+      .array(z.string())
+      .describe('Array of permissions, e.g. ["transfer", "swap"]'),
+    expiresIn: z
+      .number()
+      .optional()
+      .describe("Optional expiry in seconds"),
+  });
+
+  private config: SpraayToolConfig;
+
+  constructor(config: SpraayToolConfig) {
+    super();
+    this.config = config;
+  }
+
+  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/session-key",
+      0.02,
+      input
+    );
+  }
+}
+
+// ── Tool 3: Get Wallet Info ───────────────────────────────────────
+
+export class SpraayGetWalletInfoTool extends StructuredTool {
+  name = "spraay_get_wallet_info";
+  description = `💧 Get information about a Spraay agent wallet.
+Returns the owner, active session keys with permissions, USDC balance, and label.
+Use when the user asks about wallet status, balance, or active keys.
+Costs $0.005 USDC per call via x402 on Base.`;
+
+  schema = z.object({
+    walletAddress: z
+      .string()
+      .describe("The agent wallet address to query"),
+  });
+
+  private config: SpraayToolConfig;
+
+  constructor(config: SpraayToolConfig) {
+    super();
+    this.config = config;
+  }
+
+  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/info?walletAddress=${input.walletAddress}`,
+      0.005
+    );
+  }
+}
+
+// ── Tool 4: Revoke Session Key ────────────────────────────────────
+
+export class SpraayRevokeSessionKeyTool extends StructuredTool {
+  name = "spraay_revoke_session_key";
+  description = `💧 Revoke a session key from a Spraay agent wallet.
+Removes all permissions from the specified session key address.
+Use when the user wants to remove access or disable a key.
+Costs $0.02 USDC per call via x402 on Base.`;
+
+  schema = z.object({
+    walletAddress: z
+      .string()
+      .describe("The agent wallet that has the session key"),
+    sessionKeyAddress: z
+      .string()
+      .describe("The session key address to revoke"),
+  });
+
+  private config: SpraayToolConfig;
+
+  constructor(config: SpraayToolConfig) {
+    super();
+    this.config = config;
+  }
+
+  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+    const { wallet, baseUrl } = createWallet(this.config);
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "POST",
+      "/api/v1/agent-wallet/revoke-key",
+      0.02,
+      input
+    );
+  }
+}
+
+// ── Tool 5: Predict Wallet Address ────────────────────────────────
+
+export class SpraayPredictAddressTool extends StructuredTool {
+  name = "spraay_predict_address";
+  description = `💧 Predict the counterfactual address of a Spraay agent wallet before deploying it.
+Uses CREATE2 deterministic addressing — the wallet can be deployed later.
+Use when the user wants to know what address their wallet will have.
+Costs $0.001 USDC per call via x402 on Base.`;
+
+  schema = z.object({
+    ownerAddress: z
+      .string()
+      .describe("The EVM address that would own the wallet"),
+    salt: z
+      .string()
+      .optional()
+      .describe("Optional salt for CREATE2 derivation"),
+  });
+
+  private config: SpraayToolConfig;
+
+  constructor(config: SpraayToolConfig) {
+    super();
+    this.config = config;
+  }
+
+  async _call(input: z.infer<typeof this.schema>): Promise<string> {
+    const { wallet, baseUrl } = createWallet(this.config);
+    const qs = `ownerAddress=${input.ownerAddress}${
+      input.salt ? `&salt=${input.salt}` : ""
+    }`;
+    return gatewayRequest(
+      wallet,
+      baseUrl,
+      "GET",
+      `/api/v1/agent-wallet/predict?${qs}`,
+      0.001
+    );
+  }
+}
+
+// ── Convenience: Create All Tools ─────────────────────────────────
+
+/**
+ * Create all 5 Spraay Agent Wallet tools for LangChain.
+ *
+ * @example
+ * ```ts
+ * import { createSpraayWalletTools } from "@spraay/langchain-agent-wallet";
+ *
+ * const tools = createSpraayWalletTools({
+ *   privateKey: process.env.EVM_PRIVATE_KEY!,
+ * });
+ *
+ * const agent = createToolCallingAgent({ llm, tools, prompt });
+ * ```
+ */
+export function createSpraayWalletTools(
+  config: SpraayToolConfig
+): StructuredTool[] {
+  return [
+    new SpraayProvisionWalletTool(config),
+    new SpraayAddSessionKeyTool(config),
+    new SpraayGetWalletInfoTool(config),
+    new SpraayRevokeSessionKeyTool(config),
+    new SpraayPredictAddressTool(config),
+  ];
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}