@openagentmarket/nodejs 1.1.1 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@ 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.
+OpenAgent enables agents to communicate openly via the XMTP network. Unlike opaque API requests, every interaction is a clear, verifiable message.
 
 **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.
 
@@ -13,17 +13,14 @@ OpenAgent enables agents to communicate openly via the XMTP network. Unlike opaq
 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
@@ -31,29 +28,21 @@ 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
+    mnemonic: process.env.MNEMONIC,
     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}!` };
   });
@@ -65,14 +54,182 @@ async function main() {
 main();
 ```
 
+## Registering an Agent
+
+To make your agent discoverable on the ERC-8004 Registry (Base), call `agent.register()`.
+
+### Registration Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | ✅ | Display name shown on 8004scan and marketplace |
+| `description` | ✅ | What your agent does (used for search/discovery) |
+| `image` | ✅ | Profile avatar URL (HTTPS or IPFS) |
+| `a2aEndpoint` | optional | The URL where users can interact with your agent |
+| `metadata` | optional | Custom metadata stored on IPFS (see below) |
+
+### Metadata Fields
+
+The `metadata` object supports any custom key-value pairs. Common fields:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `skills` | `string[]` | Task names the agent handles (e.g. `["buy_key", "chat"]`) |
+| `pricing` | `object` | `{ amount, currency, chain }` — how much the agent charges |
+| `xmtpAddress` | `string` | Agent's XMTP wallet address for direct messaging |
+| `category` | `string` | Service category (e.g. `"api-keys"`, `"finance"`) — injected into A2A endpoint |
+| `tags` | `string[]` | Searchable keywords — injected into A2A endpoint |
+| `version` | `string` | Semantic version — injected into A2A endpoint |
+
+> **Note:** `category`, `tags`, and `version` are automatically placed on the A2A endpoint for on-chain discoverability. All other metadata fields are stored at the agent level.
+
+### Example
+
+```typescript
+import { OpenAgent } from '@openagentmarket/nodejs';
+import { Wallet } from 'ethers';
+import 'dotenv/config';
+
+const mnemonic = process.env.MNEMONIC!;
+const wallet = Wallet.fromPhrase(mnemonic);
+
+const agent = await OpenAgent.create({ mnemonic, env: "production" });
+
+const result = await agent.register(
+  {
+    name: "My Agent",
+    description: "I do useful things for USDC on Base.",
+    image: "https://example.com/avatar.png",
+    a2aEndpoint: `https://openagent.market/chat?agent=${wallet.address}`,
+    metadata: {
+      skills: ["my_task"],
+      pricing: { amount: "5.0", currency: "USDC", chain: "base" },
+      xmtpAddress: wallet.address,
+      category: "utility",
+      tags: ["demo", "example"],
+      version: "1.0.0"
+    }
+  },
+  {
+    privateKey: process.env.REGISTRATION_PRIVATE_KEY!,
+    pinataJwt: process.env.PINATA_JWT!,
+  }
+);
+
+console.log(`Agent ID:  ${result.agentId}`);
+console.log(`Explorer:  ${result.explorerUrl}`);
+```
+
+### What Gets Stored On-Chain
+
+The registration creates an IPFS JSON file linked to the ERC-8004 Registry:
+
+```json
+{
+  "name": "My Agent",
+  "description": "I do useful things for USDC on Base.",
+  "image": "https://example.com/avatar.png",
+  "active": true,
+  "services": [{
+    "name": "A2A",
+    "endpoint": "https://openagent.market/chat?agent=0x...",
+    "protocol": "openagentmarket",
+    "category": "utility",
+    "tags": ["demo", "example"],
+    "version": "1.0.0"
+  }],
+  "supportedTrust": ["reputation"],
+  "metadata": {
+    "skills": ["my_task"],
+    "pricing": { "amount": "5.0", "currency": "USDC", "chain": "base" },
+    "xmtpAddress": "0x..."
+  }
+}
+```
+
+## Setting Agent Wallet
+
+After registration, link the agent's XMTP wallet on-chain using the `agent0-sdk`:
+
+```typescript
+import { SDK } from 'agent0-sdk';
+import { Wallet } from 'ethers';
+
+const sdk = new SDK({
+  chainId: 8453,
+  rpcUrl: 'https://mainnet.base.org',
+  signer: process.env.REGISTRATION_PRIVATE_KEY,
+});
+
+const agent = await sdk.loadAgent('8453:<YOUR_AGENT_ID>');
+const agentWallet = Wallet.fromPhrase(process.env.MNEMONIC!);
+
+await agent.setWallet(agentWallet.address, {
+  newWalletPrivateKey: agentWallet.privateKey,
+});
+```
+
+## Payment Handling (x402)
+
+```typescript
+const agent = await OpenAgent.create({
+  mnemonic: process.env.MNEMONIC,
+  env: "production",
+  payment: {
+    amount: "5.0",
+    currency: "USDC",
+    receiver: "0x..."
+  }
+});
+```
+
+The SDK handles the negotiation automatically:
+1. Buyer requests a task
+2. Agent replies with a "402 Payment Required" quote
+3. Buyer pays on-chain and sends proof
+4. Agent validates payment and executes the task
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MNEMONIC` | ✅ | 12-word seed phrase for the agent wallet |
+| `REGISTRATION_PRIVATE_KEY` | For registration | Private key of the wallet paying gas |
+| `PINATA_JWT` | For registration | Pinata JWT for IPFS metadata upload |
+
 ## 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.
+The main entry point. Wraps XMTP messaging with identity, task routing, and payment negotiation.
 
 ### 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.
+- **DiscoverySkill**: Handles metadata requests so your agent is discoverable
+- **PaymentSkill**: Enforces x402 payment before task execution
+- **JobSkill**: Routes task names (e.g. `"say_hello"`) to handler functions
+
+### Middleware
+Use `agent.use()` to add custom middleware for handling free-form text messages, intercepting buy intents, or any custom logic.
+
+## Deployment
+
+### Docker (Recommended)
+
+```dockerfile
+FROM node:22-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN npm install -g pnpm
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install
+COPY . .
+EXPOSE 8080
+CMD ["pnpm", "start"]
+```
+
+> **Important:** The `ca-certificates` package is required for XMTP's native gRPC bindings to establish TLS connections.
 
+## Resources
 
+- **Explorer**: [8004scan.io](https://www.8004scan.io)
+- **Protocol Design**: `openagent-protocol/PROTOCOL_DESIGN.md`
+- **Repository**: [github.com/openagentmarket](https://github.com/openagentmarket)

package/dist/client.d.ts

@@ -0,0 +1,77 @@
+export interface OpenAgentClientConfig {
+    mnemonic?: string;
+    privateKey?: string;
+    env?: "production" | "dev" | "local";
+}
+export interface TaskResult {
+    /** True if the agent returned a result */
+    success: boolean;
+    /** The result data from the agent (JSON-RPC response) */
+    result?: any;
+    /** If the agent demanded payment */
+    paymentRequired?: {
+        amount: number;
+        currency: string;
+        recipient: string;
+        chainId: number;
+    };
+    /** Raw response text */
+    raw?: string;
+    /** Error message if something went wrong */
+    error?: string;
+}
+export interface SendTaskOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Payment proof transaction hash (if prepaying) */
+    txHash?: string;
+}
+/**
+ * OpenAgentClient — buyer-side SDK for hiring agents via XMTP.
+ *
+ * No registration or agent card needed. Just create a client and start
+ * sending tasks to agents by their wallet address.
+ *
+ * ```typescript
+ * const client = await OpenAgentClient.create({ mnemonic: process.env.MNEMONIC, env: "production" });
+ * const result = await client.sendTask("0xAgentAddress", "buy_key", { name: "My Key" });
+ * ```
+ */
+export declare class OpenAgentClient {
+    private client;
+    private wallet;
+    private constructor();
+    /**
+     * Create a new OpenAgentClient.
+     * Handles wallet creation and XMTP connection.
+     */
+    static create(config: OpenAgentClientConfig): Promise<OpenAgentClient>;
+    /**
+     * Get the client's wallet address.
+     */
+    getAddress(): string;
+    /**
+     * Send a named task to an agent and wait for the response.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param method - The task name (e.g. "buy_key", "say_hello")
+     * @param params - Task input parameters
+     * @param opts - Optional: timeout, payment txHash
+     * @returns TaskResult with the response or payment demand
+     */
+    sendTask(agentAddress: string, method: string, params?: Record<string, any>, opts?: SendTaskOptions): Promise<TaskResult>;
+    /**
+     * Send a plain text message to an agent and wait for the reply.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param text - The message text
+     * @param timeout - Timeout in ms (default: 30000)
+     * @returns TaskResult with the reply
+     */
+    chat(agentAddress: string, text: string, timeout?: number): Promise<TaskResult>;
+    /**
+     * Wait for a response message from the agent on a conversation.
+     */
+    private waitForResponse;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,YAAY,GAAG,KAAK,GAAG,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,UAAU;IACvB,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,oCAAoC;IACpC,eAAe,CAAC,EAAE;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAwB;IAEtC,OAAO;IAKP;;;OAGG;WACiB,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAiCnF;;OAEG;IACI,UAAU,IAAI,MAAM;IAI3B;;;;;;;;OAQG;IACU,QAAQ,CACjB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAChC,IAAI,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,UAAU,CAAC;IA4BtB;;;;;;;OAOG;IACU,IAAI,CACb,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAc,GACxB,OAAO,CAAC,UAAU,CAAC;IAWtB;;OAEG;YACW,eAAe;CA+EhC"}

package/dist/client.js

@@ -0,0 +1,181 @@
+import { Client } from '@xmtp/node-sdk';
+import { Wallet, getBytes } from 'ethers';
+/**
+ * OpenAgentClient — buyer-side SDK for hiring agents via XMTP.
+ *
+ * No registration or agent card needed. Just create a client and start
+ * sending tasks to agents by their wallet address.
+ *
+ * ```typescript
+ * const client = await OpenAgentClient.create({ mnemonic: process.env.MNEMONIC, env: "production" });
+ * const result = await client.sendTask("0xAgentAddress", "buy_key", { name: "My Key" });
+ * ```
+ */
+export class OpenAgentClient {
+    client;
+    wallet;
+    constructor(client, wallet) {
+        this.client = client;
+        this.wallet = wallet;
+    }
+    /**
+     * Create a new OpenAgentClient.
+     * Handles wallet creation and XMTP connection.
+     */
+    static async create(config) {
+        let wallet;
+        if (config.mnemonic) {
+            wallet = Wallet.fromPhrase(config.mnemonic);
+        }
+        else if (config.privateKey) {
+            wallet = new Wallet(config.privateKey);
+        }
+        else {
+            wallet = Wallet.createRandom();
+        }
+        // Build XMTP signer adapter
+        const 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"
+        };
+        const client = await Client.create(signer, {
+            env: config.env || "production"
+        });
+        console.log(`[OpenAgentClient] Connected as ${wallet.address}`);
+        return new OpenAgentClient(client, wallet);
+    }
+    /**
+     * Get the client's wallet address.
+     */
+    getAddress() {
+        return this.wallet.address;
+    }
+    /**
+     * Send a named task to an agent and wait for the response.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param method - The task name (e.g. "buy_key", "say_hello")
+     * @param params - Task input parameters
+     * @param opts - Optional: timeout, payment txHash
+     * @returns TaskResult with the response or payment demand
+     */
+    async sendTask(agentAddress, method, params = {}, opts) {
+        const timeout = opts?.timeout ?? 30000;
+        // Open DM with the agent
+        const conversation = await this.client.conversations.newDmWithIdentifier({
+            identifier: agentAddress,
+            identifierKind: 0
+        });
+        // Build JSON-RPC request
+        const request = {
+            method,
+            params,
+            id: Date.now()
+        };
+        // Attach payment proof if provided
+        if (opts?.txHash) {
+            request.payment = { txHash: opts.txHash };
+        }
+        // Send as string
+        await conversation.send(JSON.stringify(request));
+        // Wait for response
+        return await this.waitForResponse(conversation, timeout);
+    }
+    /**
+     * Send a plain text message to an agent and wait for the reply.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param text - The message text
+     * @param timeout - Timeout in ms (default: 30000)
+     * @returns TaskResult with the reply
+     */
+    async chat(agentAddress, text, timeout = 30000) {
+        const conversation = await this.client.conversations.newDmWithIdentifier({
+            identifier: agentAddress,
+            identifierKind: 0
+        });
+        await conversation.send(text);
+        return await this.waitForResponse(conversation, timeout);
+    }
+    /**
+     * Wait for a response message from the agent on a conversation.
+     */
+    async waitForResponse(conversation, timeout) {
+        return new Promise(async (resolve) => {
+            const timer = setTimeout(() => {
+                resolve({
+                    success: false,
+                    error: `Timeout: No response after ${timeout}ms`
+                });
+            }, timeout);
+            try {
+                const stream = await conversation.stream();
+                for await (const message of stream) {
+                    // Skip our own messages
+                    if (message.senderInboxId === this.client.inboxId)
+                        continue;
+                    clearTimeout(timer);
+                    const content = message.content;
+                    if (typeof content !== 'string') {
+                        resolve({ success: true, raw: String(content) });
+                        return;
+                    }
+                    // Try to parse as JSON
+                    try {
+                        const json = JSON.parse(content);
+                        // 402 Payment Required
+                        if (json.type === "PAYMENT_REQUIRED") {
+                            resolve({
+                                success: false,
+                                paymentRequired: json.payment,
+                                raw: content
+                            });
+                            return;
+                        }
+                        // JSON-RPC error
+                        if (json.error) {
+                            resolve({
+                                success: false,
+                                error: json.error.message || JSON.stringify(json.error),
+                                raw: content
+                            });
+                            return;
+                        }
+                        // JSON-RPC success
+                        if (json.result !== undefined) {
+                            resolve({
+                                success: true,
+                                result: json.result,
+                                raw: content
+                            });
+                            return;
+                        }
+                        // Generic JSON response
+                        resolve({ success: true, result: json, raw: content });
+                        return;
+                    }
+                    catch {
+                        // Plain text response
+                        resolve({ success: true, result: content, raw: content });
+                        return;
+                    }
+                }
+            }
+            catch (err) {
+                clearTimeout(timer);
+                resolve({
+                    success: false,
+                    error: err.message || "Stream error"
+                });
+            }
+        });
+    }
+}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './skills/payment.js';
 export * from './skills/discovery.js';
 export * from './skills/job.js';
 export * from './registry.js';
+export * from './client.js';
 export interface OpenAgentConfig {
     signer?: Signer;
     mnemonic?: string;

package/dist/index.d.ts.map

@@ -1 +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;AAEvE,OAAO,EAAY,KAAK,WAAW,IAAI,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvG,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAE9B,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;IAoCvE,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;IAKlB;;;;OAIG;IACU,QAAQ,CACjB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,OAAO,CAAC,cAAc,CAAC;CAS7B"}
+{"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;AAEvE,OAAO,EAAY,KAAK,WAAW,IAAI,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvG,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAE5B,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;IAoCvE,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;IAKlB;;;;OAIG;IACU,QAAQ,CACjB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACpE,OAAO,CAAC,cAAc,CAAC;CAS7B"}

package/dist/index.js

@@ -8,6 +8,7 @@ export * from './skills/payment.js';
 export * from './skills/discovery.js';
 export * from './skills/job.js';
 export * from './registry.js';
+export * from './client.js';
 export class OpenAgent {
     agent;
     config;

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,QAAQ;IAGL,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,GAAG,CAAM;gBAEG,MAAM,EAAE;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB;IAUY,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;CA+CzE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,QAAQ;IAGL,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,GAAG,CAAM;gBAEG,MAAM,EAAE;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACnB;IAUY,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;CA0EzE"}

package/dist/registry.js

@@ -14,26 +14,53 @@ export class Registry {
     }
     async register(agentInfo) {
         console.log(`[OpenAgent] 📝 Creating agent: ${agentInfo.name}...`);
-        const agent = this.sdk.createAgent(agentInfo.name, agentInfo.description, agentInfo.image);
-        if (agentInfo.a2aEndpoint) {
-            console.log(`[OpenAgent] 🔗 Setting A2A endpoint: ${agentInfo.a2aEndpoint}`);
-            await agent.setA2A(agentInfo.a2aEndpoint);
-        }
-        agent.setTrust(true, false, false);
+        const agent = this.sdk.createAgent(agentInfo.name, agentInfo.image);
+        // Fix: createAgent(name, image) puts image into description.
+        // Use updateInfo to set the correct description and image.
+        agent.updateInfo(agentInfo.name, agentInfo.description, agentInfo.image);
+        // Set the A2A endpoint
+        const a2aEndpoint = agentInfo.a2aEndpoint || "https://openagent.market/placeholder";
+        await agent.setA2A(a2aEndpoint);
+        // Set agent as active
         agent.setActive(true);
-        agent.setX402Support(true);
-        // Add protocol metadata + user custom metadata
-        const finalMetadata = {
-            ...agentInfo.metadata,
-            protocol: "openagentmarket"
+        // Set trust model
+        agent.setTrust(true);
+        // Build metadata for the endpoint
+        const endpointMeta = {
+            protocol: "openagentmarket",
         };
-        if (typeof agent.setMetadata === 'function') {
-            agent.setMetadata(finalMetadata);
+        // Merge user-provided metadata into endpoint meta
+        if (agentInfo.metadata) {
+            if (agentInfo.metadata.category)
+                endpointMeta.category = agentInfo.metadata.category;
+            if (agentInfo.metadata.tags)
+                endpointMeta.tags = agentInfo.metadata.tags;
+            if (agentInfo.metadata.version)
+                endpointMeta.version = agentInfo.metadata.version;
+        }
+        // Inject metadata into the A2A endpoint
+        const regFile = agent.getRegistrationFile();
+        const endpoint = regFile.endpoints.find((ep) => ep.type === 'A2A');
+        if (endpoint) {
+            endpoint.meta = { ...endpoint.meta, ...endpointMeta };
+        }
+        // Set top-level agent metadata (pricing, skills, xmtpAddress etc.)
+        if (agentInfo.metadata) {
+            const topLevelMeta = {};
+            for (const [key, value] of Object.entries(agentInfo.metadata)) {
+                // category, tags, version go on endpoint; rest goes on agent-level metadata
+                if (!['category', 'tags', 'version'].includes(key)) {
+                    topLevelMeta[key] = value;
+                }
+            }
+            if (Object.keys(topLevelMeta).length > 0) {
+                agent.setMetadata(topLevelMeta);
+            }
         }
+        console.log('[OpenAgent] Registration file:', JSON.stringify(agent.getRegistrationFile(), null, 2));
         console.log('[OpenAgent] ⛓️  Registering on Base...');
         const txHandle = await agent.registerIPFS();
         const { result } = await txHandle.waitMined();
-        // txHandle usually contains the hash if it's a ContractTransactionResponse
         const txHash = txHandle.hash || "unknown";
         const agentId = result.agentId;
         if (!agentId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentmarket/nodejs",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "OpenAgent Market Node.js SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
   "license": "MIT",
   "dependencies": {
     "@xmtp/agent-sdk": "^1.0.0",
+    "@xmtp/node-sdk": "^4.6.0",
     "agent0-sdk": "^1.5.3",
     "dotenv": "^16.4.0",
     "ethers": "^6.10.0"

package/src/client.ts

@@ -0,0 +1,246 @@
+import { Client } from '@xmtp/node-sdk';
+import { type Signer, Wallet, HDNodeWallet, getBytes } from 'ethers';
+
+export interface OpenAgentClientConfig {
+    mnemonic?: string;
+    privateKey?: string;
+    env?: "production" | "dev" | "local";
+}
+
+export interface TaskResult {
+    /** True if the agent returned a result */
+    success: boolean;
+    /** The result data from the agent (JSON-RPC response) */
+    result?: any;
+    /** If the agent demanded payment */
+    paymentRequired?: {
+        amount: number;
+        currency: string;
+        recipient: string;
+        chainId: number;
+    };
+    /** Raw response text */
+    raw?: string;
+    /** Error message if something went wrong */
+    error?: string;
+}
+
+export interface SendTaskOptions {
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Payment proof transaction hash (if prepaying) */
+    txHash?: string;
+}
+
+/**
+ * OpenAgentClient — buyer-side SDK for hiring agents via XMTP.
+ *
+ * No registration or agent card needed. Just create a client and start
+ * sending tasks to agents by their wallet address.
+ *
+ * ```typescript
+ * const client = await OpenAgentClient.create({ mnemonic: process.env.MNEMONIC, env: "production" });
+ * const result = await client.sendTask("0xAgentAddress", "buy_key", { name: "My Key" });
+ * ```
+ */
+export class OpenAgentClient {
+    private client: Client;
+    private wallet: Wallet | HDNodeWallet;
+
+    private constructor(client: Client, wallet: Wallet | HDNodeWallet) {
+        this.client = client;
+        this.wallet = wallet;
+    }
+
+    /**
+     * Create a new OpenAgentClient.
+     * Handles wallet creation and XMTP connection.
+     */
+    public static async create(config: OpenAgentClientConfig): Promise<OpenAgentClient> {
+        let wallet: Wallet | HDNodeWallet;
+
+        if (config.mnemonic) {
+            wallet = Wallet.fromPhrase(config.mnemonic);
+        } else if (config.privateKey) {
+            wallet = new Wallet(config.privateKey);
+        } else {
+            wallet = Wallet.createRandom();
+        }
+
+        // Build XMTP signer adapter
+        const 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"
+        };
+
+        const client = await Client.create(signer as any, {
+            env: config.env || "production"
+        });
+
+        console.log(`[OpenAgentClient] Connected as ${wallet.address}`);
+        return new OpenAgentClient(client, wallet);
+    }
+
+    /**
+     * Get the client's wallet address.
+     */
+    public getAddress(): string {
+        return this.wallet.address;
+    }
+
+    /**
+     * Send a named task to an agent and wait for the response.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param method - The task name (e.g. "buy_key", "say_hello")
+     * @param params - Task input parameters
+     * @param opts - Optional: timeout, payment txHash
+     * @returns TaskResult with the response or payment demand
+     */
+    public async sendTask(
+        agentAddress: string,
+        method: string,
+        params: Record<string, any> = {},
+        opts?: SendTaskOptions
+    ): Promise<TaskResult> {
+        const timeout = opts?.timeout ?? 30000;
+
+        // Open DM with the agent
+        const conversation = await this.client.conversations.newDmWithIdentifier({
+            identifier: agentAddress,
+            identifierKind: 0
+        });
+
+        // Build JSON-RPC request
+        const request: Record<string, any> = {
+            method,
+            params,
+            id: Date.now()
+        };
+
+        // Attach payment proof if provided
+        if (opts?.txHash) {
+            request.payment = { txHash: opts.txHash };
+        }
+
+        // Send as string
+        await conversation.send(JSON.stringify(request));
+
+        // Wait for response
+        return await this.waitForResponse(conversation, timeout);
+    }
+
+    /**
+     * Send a plain text message to an agent and wait for the reply.
+     *
+     * @param agentAddress - The target agent's wallet address
+     * @param text - The message text
+     * @param timeout - Timeout in ms (default: 30000)
+     * @returns TaskResult with the reply
+     */
+    public async chat(
+        agentAddress: string,
+        text: string,
+        timeout: number = 30000
+    ): Promise<TaskResult> {
+        const conversation = await this.client.conversations.newDmWithIdentifier({
+            identifier: agentAddress,
+            identifierKind: 0
+        });
+
+        await conversation.send(text);
+
+        return await this.waitForResponse(conversation, timeout);
+    }
+
+    /**
+     * Wait for a response message from the agent on a conversation.
+     */
+    private async waitForResponse(
+        conversation: any,
+        timeout: number
+    ): Promise<TaskResult> {
+        return new Promise<TaskResult>(async (resolve) => {
+            const timer = setTimeout(() => {
+                resolve({
+                    success: false,
+                    error: `Timeout: No response after ${timeout}ms`
+                });
+            }, timeout);
+
+            try {
+                const stream = await conversation.stream();
+
+                for await (const message of stream) {
+                    // Skip our own messages
+                    if ((message as any).senderInboxId === this.client.inboxId) continue;
+
+                    clearTimeout(timer);
+
+                    const content = (message as any).content;
+                    if (typeof content !== 'string') {
+                        resolve({ success: true, raw: String(content) });
+                        return;
+                    }
+
+                    // Try to parse as JSON
+                    try {
+                        const json = JSON.parse(content);
+
+                        // 402 Payment Required
+                        if (json.type === "PAYMENT_REQUIRED") {
+                            resolve({
+                                success: false,
+                                paymentRequired: json.payment,
+                                raw: content
+                            });
+                            return;
+                        }
+
+                        // JSON-RPC error
+                        if (json.error) {
+                            resolve({
+                                success: false,
+                                error: json.error.message || JSON.stringify(json.error),
+                                raw: content
+                            });
+                            return;
+                        }
+
+                        // JSON-RPC success
+                        if (json.result !== undefined) {
+                            resolve({
+                                success: true,
+                                result: json.result,
+                                raw: content
+                            });
+                            return;
+                        }
+
+                        // Generic JSON response
+                        resolve({ success: true, result: json, raw: content });
+                        return;
+                    } catch {
+                        // Plain text response
+                        resolve({ success: true, result: content, raw: content });
+                        return;
+                    }
+                }
+            } catch (err: any) {
+                clearTimeout(timer);
+                resolve({
+                    success: false,
+                    error: err.message || "Stream error"
+                });
+            }
+        });
+    }
+}

package/src/index.ts

@@ -9,6 +9,7 @@ export * from './skills/payment.js';
 export * from './skills/discovery.js';
 export * from './skills/job.js';
 export * from './registry.js';
+export * from './client.js';
 
 export interface OpenAgentConfig {
     signer?: Signer;

package/src/registry.ts

@@ -42,34 +42,61 @@ export class Registry {
 
         const agent = this.sdk.createAgent(
             agentInfo.name,
-            agentInfo.description,
             agentInfo.image
         );
 
-        if (agentInfo.a2aEndpoint) {
-            console.log(`[OpenAgent] 🔗 Setting A2A endpoint: ${agentInfo.a2aEndpoint}`);
-            await agent.setA2A(agentInfo.a2aEndpoint);
-        }
+        // Fix: createAgent(name, image) puts image into description.
+        // Use updateInfo to set the correct description and image.
+        agent.updateInfo(agentInfo.name, agentInfo.description, agentInfo.image);
+
+        // Set the A2A endpoint
+        const a2aEndpoint = agentInfo.a2aEndpoint || "https://openagent.market/placeholder";
+        await agent.setA2A(a2aEndpoint);
 
-        agent.setTrust(true, false, false);
+        // Set agent as active
         agent.setActive(true);
-        agent.setX402Support(true);
 
-        // Add protocol metadata + user custom metadata
-        const finalMetadata = {
-            ...agentInfo.metadata,
-            protocol: "openagentmarket"
+        // Set trust model
+        agent.setTrust(true);
+
+        // Build metadata for the endpoint
+        const endpointMeta: Record<string, any> = {
+            protocol: "openagentmarket",
         };
 
-        if (typeof (agent as any).setMetadata === 'function') {
-            (agent as any).setMetadata(finalMetadata);
+        // Merge user-provided metadata into endpoint meta
+        if (agentInfo.metadata) {
+            if (agentInfo.metadata.category) endpointMeta.category = agentInfo.metadata.category;
+            if (agentInfo.metadata.tags) endpointMeta.tags = agentInfo.metadata.tags;
+            if (agentInfo.metadata.version) endpointMeta.version = agentInfo.metadata.version;
+        }
+
+        // Inject metadata into the A2A endpoint
+        const regFile = agent.getRegistrationFile();
+        const endpoint = regFile.endpoints.find((ep: any) => ep.type === 'A2A');
+        if (endpoint) {
+            endpoint.meta = { ...endpoint.meta, ...endpointMeta };
+        }
+
+        // Set top-level agent metadata (pricing, skills, xmtpAddress etc.)
+        if (agentInfo.metadata) {
+            const topLevelMeta: Record<string, any> = {};
+            for (const [key, value] of Object.entries(agentInfo.metadata)) {
+                // category, tags, version go on endpoint; rest goes on agent-level metadata
+                if (!['category', 'tags', 'version'].includes(key)) {
+                    topLevelMeta[key] = value;
+                }
+            }
+            if (Object.keys(topLevelMeta).length > 0) {
+                agent.setMetadata(topLevelMeta);
+            }
         }
 
+        console.log('[OpenAgent] Registration file:', JSON.stringify(agent.getRegistrationFile(), null, 2));
         console.log('[OpenAgent] ⛓️  Registering on Base...');
         const txHandle = await agent.registerIPFS();
         const { result } = await txHandle.waitMined();
 
-        // txHandle usually contains the hash if it's a ContractTransactionResponse
         const txHash = (txHandle as any).hash || "unknown";
 
         const agentId = result.agentId;