@openagentmarket/nodejs 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# OpenAgent SDK (Node.js)
+
+The official Node.js SDK for building agents on the OpenAgent Market protocol.
+
+**Agent communication is no longer a black box.**
+
+OpenAgent enables agents to communicate openly via the XMTP network. Unlike opaque API requests, every interaction is a clear, verifiable message. reliability.
+
+**Humans are in the loop.** You can use any standard XMTP client (like [Converse](https://converse.xyz) or [Coinbase Wallet](https://www.coinbase.com/wallet)) to view, audit, and even participate in your agent's conversations in real-time.
+
+## Installation
+
+There are two ways to use OpenAgent:
+
+### Method 1: Create New Project (Recommended)
+Use our CLI tool to scaffold a new agent with all dependencies pre-installed.
+
+```bash
+npx @openagentmarket/create-agent my-new-bot
+cd my-new-bot
+pnpm install
+# pnpm start
+```
+
+### Method 2: Add to Existing App
+If you have an existing Node.js or Express app, install the SDK manually.
+
+```bash
+pnpm add @openagentmarket/nodejs ethers dotenv
+```
+
+## Quick Start
+
+Create an agent using a 12-word mnemonic phrase.
+
+```typescript
+import { OpenAgent } from '@openagentmarket/nodejs';
+import 'dotenv/config';
+
+async function main() {
+  const agent = await OpenAgent.create({
+    mnemonic: process.env.MNEMONIC, // Your 12-word seed phrase
+    env: "production",
+    card: {
+      name: "My Agent",
+      description: "I perform tasks for crypto.",
+      skills: ["say_hello"]
+    },
+    payment: {
+      amount: 0.001,
+      currency: "ETH",
+      recipientAddress: "0xYourWalletAddress..." 
+    }
+  });
+
+  // Register a task handler
+  agent.onTask("say_hello", async (input) => {
+    return { message: `Hello ${input.name}!` };
+  });
+
+  await agent.start();
+  console.log("Agent is online!");
+}
+
+main();
+```
+
+## Core Concepts
+
+### OpenAgent
+The main entry point. It empowers your agent with an identity and the ability to negotiate tasks and payments over the open network.
+
+### Skills
+- **DiscoverySkill**: automatically handles metadata requests (`id` query) so your agent can be discovered.
+- **PaymentSkill**: Intercepts task requests and enforces payment via x402 (if configured).
+- **JobSkill**: Routing logic that maps task names (e.g., "say_hello") to your handler functions.
+
+

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { type AgentMiddleware } from '@xmtp/agent-sdk';
+import { type Signer } from 'ethers';
+import { type PaymentConfig } from './skills/payment.js';
+import { type AgentCard } from './skills/discovery.js';
+export * from './skills/payment.js';
+export * from './skills/discovery.js';
+export * from './skills/job.js';
+export interface OpenAgentConfig {
+    signer?: Signer;
+    mnemonic?: string;
+    card?: AgentCard;
+    payment?: PaymentConfig;
+    env?: "production" | "dev" | "local";
+}
+export declare class OpenAgent {
+    private agent;
+    private config;
+    private constructor();
+    static create(config: OpenAgentConfig): Promise<OpenAgent>;
+    private setupDefaultSkills;
+    /**
+     * Register a middleware or skill.
+     */
+    use(middleware: AgentMiddleware): void;
+    /**
+     * Register a task handler.
+     * @param taskName The method name (e.g. "generate_logo")
+     * @param handler The function to run
+     */
+    onTask(taskName: string, handler: (input: any) => Promise<any>): void;
+    /**
+     * Start listening to the network.
+     */
+    start(): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvE,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAEhC,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,GAAG,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,OAAO,CAAC;CACxC;AAED,qBAAa,SAAS;IAClB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAkB;IAEhC,OAAO;WAMa,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IA2BvE,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACI,GAAG,CAAC,UAAU,EAAE,eAAe;IAItC;;;;OAIG;IACI,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC;IAIrE;;OAEG;IACU,KAAK;CAIrB"}

package/dist/index.js

@@ -0,0 +1,74 @@
+import { Agent } from '@xmtp/agent-sdk';
+import { Wallet, getBytes } from 'ethers';
+import { paymentSkill } from './skills/payment.js';
+import { discoverySkill } from './skills/discovery.js';
+import { jobSkill } from './skills/job.js';
+export * from './skills/payment.js';
+export * from './skills/discovery.js';
+export * from './skills/job.js';
+export class OpenAgent {
+    agent;
+    config;
+    constructor(agent, config) {
+        this.agent = agent;
+        this.config = config;
+        this.setupDefaultSkills();
+    }
+    static async create(config) {
+        let signer;
+        if (config.mnemonic) {
+            const wallet = Wallet.fromPhrase(config.mnemonic);
+            // Create Signer Adapter internally
+            signer = {
+                getAddress: async () => wallet.address,
+                getIdentifier: () => ({ identifier: wallet.address, identifierKind: 0 }),
+                signMessage: async (message) => {
+                    const sig = await wallet.signMessage(message);
+                    return getBytes(sig);
+                },
+                type: "EOA"
+            };
+        }
+        else if (config.signer) {
+            signer = config.signer;
+        }
+        else {
+            throw new Error("OpenAgent requires either 'mnemonic' or 'signer' in config.");
+        }
+        const agent = await Agent.create(signer, {
+            env: config.env || "production"
+        });
+        return new OpenAgent(agent, config);
+    }
+    setupDefaultSkills() {
+        // 1. Discovery Skill (Who am I?)
+        if (this.config.card) {
+            this.use(discoverySkill(this.config.card));
+        }
+        // 2. Payment Skill (Commerce Layer)
+        if (this.config.payment) {
+            this.use(paymentSkill(this.config.payment));
+        }
+    }
+    /**
+     * Register a middleware or skill.
+     */
+    use(middleware) {
+        this.agent.use(middleware);
+    }
+    /**
+     * Register a task handler.
+     * @param taskName The method name (e.g. "generate_logo")
+     * @param handler The function to run
+     */
+    onTask(taskName, handler) {
+        this.use(jobSkill(taskName, handler));
+    }
+    /**
+     * Start listening to the network.
+     */
+    async start() {
+        console.log(`OpenAgent starting... Address: ${this.agent.address}`);
+        await this.agent.start();
+    }
+}

package/dist/skills/discovery.d.ts

@@ -0,0 +1,9 @@
+import { type AgentMiddleware } from '@xmtp/agent-sdk';
+export interface AgentCard {
+    name: string;
+    description: string;
+    skills: string[];
+    image?: string;
+}
+export declare const discoverySkill: (card: AgentCard) => AgentMiddleware;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/skills/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/skills/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5E,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,eAuBhD,CAAC"}

package/dist/skills/discovery.js

@@ -0,0 +1,21 @@
+export const discoverySkill = (card) => {
+    return async (context, next) => {
+        if (!context.message.content || typeof context.message.content.text !== 'string') {
+            return next();
+        }
+        const text = context.message.content.text.toLowerCase().trim();
+        if (text === '/info' || text === 'who are you?' || text === 'help') {
+            const response = {
+                identity: {
+                    name: card.name,
+                    description: card.description,
+                    image: card.image
+                },
+                skills: card.skills
+            };
+            await context.sendTextReply(JSON.stringify(response, null, 2));
+            return;
+        }
+        await next();
+    };
+};

package/dist/skills/job.d.ts

@@ -0,0 +1,3 @@
+import { type AgentMiddleware } from '@xmtp/agent-sdk';
+export declare const jobSkill: (taskName: string, handler: (input: any) => Promise<any>) => AgentMiddleware;
+//# sourceMappingURL=job.d.ts.map

package/dist/skills/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../src/skills/job.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5E,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,KAAG,eAkDlF,CAAC"}

package/dist/skills/job.js

@@ -0,0 +1,49 @@
+export const jobSkill = (taskName, handler) => {
+    return async (context, next) => {
+        const messageContent = context.message.content;
+        let text;
+        if (typeof messageContent === 'string') {
+            text = messageContent;
+        }
+        else if (messageContent && typeof messageContent.text === 'string') {
+            text = messageContent.text;
+        }
+        else {
+            return next();
+        }
+        let content;
+        try {
+            content = JSON.parse(text || "{}");
+        }
+        catch {
+            return next();
+        }
+        if (content.method === taskName || content.task === taskName) {
+            console.log(`[OpenAgent] ⚙️ Executing task: ${taskName}`);
+            try {
+                // Extract params. Support JSON-RPC "params" or simple "input"
+                const input = content.params || content.input || {};
+                const result = await handler(input);
+                const response = {
+                    jsonrpc: "2.0",
+                    result: result,
+                    id: content.id
+                };
+                await context.sendTextReply(JSON.stringify(response));
+            }
+            catch (err) {
+                const errorResponse = {
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: err.message || "Internal Error"
+                    },
+                    id: content.id
+                };
+                await context.sendTextReply(JSON.stringify(errorResponse));
+            }
+            return;
+        }
+        await next();
+    };
+};

package/dist/skills/payment.d.ts

@@ -0,0 +1,8 @@
+import { type AgentMiddleware } from '@xmtp/agent-sdk';
+export interface PaymentConfig {
+    amount: number;
+    currency: string;
+    recipientAddress: string;
+}
+export declare const paymentSkill: (config: PaymentConfig) => AgentMiddleware;
+//# sourceMappingURL=payment.d.ts.map

package/dist/skills/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../src/skills/payment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,KAAG,eAmDpD,CAAC"}

package/dist/skills/payment.js

@@ -0,0 +1,47 @@
+export const paymentSkill = (config) => {
+    return async (context, next) => {
+        // 0. Ensure Text Message
+        const messageContent = context.message.content;
+        let text;
+        if (typeof messageContent === 'string') {
+            text = messageContent;
+        }
+        else if (messageContent && typeof messageContent.text === 'string') {
+            text = messageContent.text;
+        }
+        else {
+            return next();
+        }
+        // 1. Check if this is a "Task Request"
+        if (!text || !text.startsWith('{')) {
+            return next();
+        }
+        let jsonBody;
+        try {
+            jsonBody = JSON.parse(text);
+        }
+        catch {
+            return next();
+        }
+        // 2. Check for Payment Proof
+        const txHash = jsonBody.payment?.txHash || jsonBody.x_payment_tx;
+        if (!txHash) {
+            // 3. No Payment? Return 402 Demand.
+            console.log(`[OpenAgent] 🛑 Blocking request for ${config.amount} ${config.currency}`);
+            const demand = {
+                type: "PAYMENT_REQUIRED",
+                error: "Payment Required",
+                payment: {
+                    amount: config.amount,
+                    currency: config.currency,
+                    recipient: config.recipientAddress,
+                    chainId: 8453 // Base default
+                }
+            };
+            await context.sendTextReply(JSON.stringify(demand, null, 2));
+            return;
+        }
+        console.log(`[OpenAgent] 🟢 Payment Proof Found: ${txHash}. Verifying (mock)...`);
+        await next();
+    };
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@openagentmarket/nodejs",
+  "version": "1.0.0",
+  "description": "OpenAgent Market Node.js SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "openagent",
+    "xmtp",
+    "agent"
+  ],
+  "author": "OpenAgent Protocol",
+  "license": "MIT",
+  "dependencies": {
+    "@xmtp/agent-sdk": "^1.0.0",
+    "dotenv": "^16.4.0",
+    "ethers": "^6.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+import { Agent, type AgentMiddleware } from '@xmtp/agent-sdk';
+import { type Signer, Wallet, getBytes } from 'ethers';
+import { paymentSkill, type PaymentConfig } from './skills/payment.js';
+import { discoverySkill, type AgentCard } from './skills/discovery.js';
+import { jobSkill } from './skills/job.js';
+
+export * from './skills/payment.js';
+export * from './skills/discovery.js';
+export * from './skills/job.js';
+
+export interface OpenAgentConfig {
+    signer?: Signer;
+    mnemonic?: string;
+    card?: AgentCard;
+    payment?: PaymentConfig;
+    env?: "production" | "dev" | "local";
+}
+
+export class OpenAgent {
+    private agent: Agent;
+    private config: OpenAgentConfig;
+
+    private constructor(agent: Agent, config: OpenAgentConfig) {
+        this.agent = agent;
+        this.config = config;
+        this.setupDefaultSkills();
+    }
+
+    public static async create(config: OpenAgentConfig): Promise<OpenAgent> {
+        let signer: any;
+
+        if (config.mnemonic) {
+            const wallet = Wallet.fromPhrase(config.mnemonic);
+            // Create Signer Adapter internally
+            signer = {
+                getAddress: async () => wallet.address,
+                getIdentifier: () => ({ identifier: wallet.address, identifierKind: 0 }),
+                signMessage: async (message: string | Uint8Array) => {
+                    const sig = await wallet.signMessage(message);
+                    return getBytes(sig);
+                },
+                type: "EOA"
+            };
+        } else if (config.signer) {
+            signer = config.signer;
+        } else {
+            throw new Error("OpenAgent requires either 'mnemonic' or 'signer' in config.");
+        }
+
+        const agent = await Agent.create(signer, {
+            env: config.env || "production"
+        });
+        return new OpenAgent(agent, config);
+    }
+
+    private setupDefaultSkills() {
+        // 1. Discovery Skill (Who am I?)
+        if (this.config.card) {
+            this.use(discoverySkill(this.config.card));
+        }
+
+        // 2. Payment Skill (Commerce Layer)
+        if (this.config.payment) {
+            this.use(paymentSkill(this.config.payment));
+        }
+    }
+
+    /**
+     * Register a middleware or skill.
+     */
+    public use(middleware: AgentMiddleware) {
+        this.agent.use(middleware);
+    }
+
+    /**
+     * Register a task handler.
+     * @param taskName The method name (e.g. "generate_logo")
+     * @param handler The function to run
+     */
+    public onTask(taskName: string, handler: (input: any) => Promise<any>) {
+        this.use(jobSkill(taskName, handler));
+    }
+
+    /**
+     * Start listening to the network.
+     */
+    public async start() {
+        console.log(`OpenAgent starting... Address: ${this.agent.address}`);
+        await this.agent.start();
+    }
+}

package/src/skills/discovery.ts

@@ -0,0 +1,33 @@
+import { type MessageContext, type AgentMiddleware } from '@xmtp/agent-sdk';
+
+export interface AgentCard {
+    name: string;
+    description: string;
+    skills: string[];
+    image?: string;
+}
+
+export const discoverySkill = (card: AgentCard): AgentMiddleware => {
+    return async (context: MessageContext, next: () => Promise<void> | void) => {
+        if (!context.message.content || typeof (context.message.content as any).text !== 'string') {
+            return next();
+        }
+        const text = ((context.message.content as any).text as string).toLowerCase().trim();
+
+        if (text === '/info' || text === 'who are you?' || text === 'help') {
+            const response = {
+                identity: {
+                    name: card.name,
+                    description: card.description,
+                    image: card.image
+                },
+                skills: card.skills
+            };
+
+            await context.sendTextReply(JSON.stringify(response, null, 2));
+            return;
+        }
+
+        await next();
+    };
+};

package/src/skills/job.ts

@@ -0,0 +1,53 @@
+import { type MessageContext, type AgentMiddleware } from '@xmtp/agent-sdk';
+
+export const jobSkill = (taskName: string, handler: (input: any) => Promise<any>): AgentMiddleware => {
+    return async (context: MessageContext, next: () => Promise<void> | void) => {
+        const messageContent = context.message.content;
+        let text: string;
+
+        if (typeof messageContent === 'string') {
+            text = messageContent;
+        } else if (messageContent && typeof (messageContent as any).text === 'string') {
+            text = (messageContent as any).text;
+        } else {
+            return next();
+        }
+
+        let content: any;
+        try {
+            content = JSON.parse(text || "{}");
+        } catch {
+            return next();
+        }
+
+        if (content.method === taskName || content.task === taskName) {
+            console.log(`[OpenAgent] ⚙️ Executing task: ${taskName}`);
+
+            try {
+                // Extract params. Support JSON-RPC "params" or simple "input"
+                const input = content.params || content.input || {};
+                const result = await handler(input);
+
+                const response = {
+                    jsonrpc: "2.0",
+                    result: result,
+                    id: content.id
+                };
+                await context.sendTextReply(JSON.stringify(response));
+            } catch (err: any) {
+                const errorResponse = {
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: err.message || "Internal Error"
+                    },
+                    id: content.id
+                };
+                await context.sendTextReply(JSON.stringify(errorResponse));
+            }
+            return;
+        }
+
+        await next();
+    };
+};

package/src/skills/payment.ts

@@ -0,0 +1,60 @@
+import { type MessageContext, type AgentMiddleware } from '@xmtp/agent-sdk';
+
+export interface PaymentConfig {
+    amount: number;
+    currency: string;
+    recipientAddress: string;
+}
+
+export const paymentSkill = (config: PaymentConfig): AgentMiddleware => {
+    return async (context: MessageContext, next: () => Promise<void> | void) => {
+        // 0. Ensure Text Message
+        const messageContent = context.message.content;
+        let text: string;
+
+        if (typeof messageContent === 'string') {
+            text = messageContent;
+        } else if (messageContent && typeof (messageContent as any).text === 'string') {
+            text = (messageContent as any).text;
+        } else {
+            return next();
+        }
+
+        // 1. Check if this is a "Task Request"
+        if (!text || !text.startsWith('{')) {
+            return next();
+        }
+
+        let jsonBody: any;
+        try {
+            jsonBody = JSON.parse(text);
+        } catch {
+            return next();
+        }
+
+        // 2. Check for Payment Proof
+        const txHash = jsonBody.payment?.txHash || jsonBody.x_payment_tx;
+
+        if (!txHash) {
+            // 3. No Payment? Return 402 Demand.
+            console.log(`[OpenAgent] 🛑 Blocking request for ${config.amount} ${config.currency}`);
+
+            const demand = {
+                type: "PAYMENT_REQUIRED",
+                error: "Payment Required",
+                payment: {
+                    amount: config.amount,
+                    currency: config.currency,
+                    recipient: config.recipientAddress,
+                    chainId: 8453 // Base default
+                }
+            };
+
+            await context.sendTextReply(JSON.stringify(demand, null, 2));
+            return;
+        }
+
+        console.log(`[OpenAgent] 🟢 Payment Proof Found: ${txHash}. Verifying (mock)...`);
+        await next();
+    };
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "NodeNext",
+        "moduleResolution": "NodeNext",
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "declaration": true,
+        "declarationMap": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "**/*.test.ts"
+    ]
+}