@openclawcash/mcp-server 0.1.2 → 0.1.4

package/README.md

@@ -58,6 +58,8 @@ Set one of these environment variables:
 - `OPENCLAWCASH_AGENT_KEY`
 - `AGENTWALLETAPI_KEY`
 
+All MCP tools require an OpenClawCash agent key because they call the authenticated agent API, including read tools such as `swap_quote` and `supported_tokens_list`.
+
 Optional base URL override:
 
 - `OPENCLAWCASH_BASE_URL`
@@ -217,8 +219,10 @@ The MCP server itself does not hold approval memory. The MCP client or agent run
 
 ## Notes
 
-- `swap_quote` is read-only.
+- `swap_quote` is read-only, but still requires an agent key.
+- `supported_tokens_list` is read-only, but still requires an agent key.
 - `transfer_send`, `swap_execute`, `approve_token`, `wallet_create`, and `wallet_import` are write tools.
+- For `wallet_get`, `transactions_list`, `supported_tokens_list`, and `swap_quote`, pass at most one wallet selector when using `walletId`, `walletLabel`, or `walletAddress`.
 - The server uses stdio transport and is intended for MCP-compatible desktop or agent clients.
 
 ## Standalone Packaging Notes

package/openclawcash-mcp.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { z } from "zod";
 
 const SERVER_NAME = "openclawcash";
-const SERVER_VERSION = "0.1.1";
+const SERVER_VERSION = "0.1.6";
 const PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_BASE_URL = "https://openclawcash.com";
 
@@ -130,13 +130,16 @@ const transferArgsSchema = walletSelectorBaseSchema
     message: "Provide exactly one of amount or value.",
   });
 
-const swapQuoteArgsSchema = z.object({
-  network: z.string().min(1),
-  tokenIn: z.string().min(1),
-  tokenOut: z.string().min(1),
-  amountIn: z.string().min(1),
-  chain: z.enum(["evm", "solana"]).optional(),
-});
+const swapQuoteArgsSchema = walletSelectorBaseSchema
+  .extend({
+    network: z.string().min(1),
+    tokenIn: z.string().min(1),
+    tokenOut: z.string().min(1),
+    amountIn: z.string().min(1),
+  })
+  .refine((data) => [data.walletId, data.walletLabel, data.walletAddress].filter((value) => value !== undefined).length <= 1, {
+    message: selectorDescription(),
+  });
 
 const swapExecuteArgsSchema = z
   .object({
@@ -165,14 +168,17 @@ const approveArgsSchema = z
     message: "Provide exactly one of walletId or walletAddress.",
   });
 
-const supportedTokensArgsSchema = z.object({
-  network: z.string().min(1).optional(),
-  chain: z.enum(["evm", "solana"]).optional(),
-});
+const supportedTokensArgsSchema = walletSelectorBaseSchema
+  .extend({
+    network: z.string().min(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletLabel, data.walletAddress].filter((value) => value !== undefined).length <= 1, {
+    message: selectorDescription(),
+  });
 
 const createWalletArgsSchema = z.object({
   label: z.string().min(1),
-  network: z.enum(["sepolia", "mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"]).optional(),
+  network: z.enum(["sepolia", "mainnet", "polygon-mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"]).optional(),
   exportPassphrase: z.string().trim().min(12),
   exportPassphraseStorageType: z.enum(["env", "secret_manager", "vault", "other"]),
   exportPassphraseStorageRef: z.string().trim().min(3),
@@ -181,10 +187,154 @@ const createWalletArgsSchema = z.object({
 
 const importWalletArgsSchema = z.object({
   label: z.string().min(1),
-  network: z.enum(["mainnet", "solana-mainnet"]),
+  network: z.enum(["mainnet", "polygon-mainnet", "solana-mainnet"]),
   privateKey: z.string().min(1),
 });
 
+const userTagSetArgsSchema = z.object({
+  userTag: z
+    .string()
+    .trim()
+    .toLowerCase()
+    .min(3)
+    .max(64)
+    .regex(/^[a-z0-9][a-z0-9._-]{2,63}$/),
+});
+
+const polymarketLimitArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    tokenId: z.string().min(1),
+    side: z.enum(["BUY", "SELL"]),
+    price: z.number().positive(),
+    size: z.number().positive(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const polymarketMarketArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    tokenId: z.string().min(1),
+    side: z.enum(["BUY", "SELL"]),
+    amount: z.number().positive(),
+    orderType: z.enum(["FAK", "FOK", "GTC"]).optional(),
+    worstPrice: z.number().min(0).max(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const polymarketReadArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    status: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(200).optional(),
+    cursor: z.string().min(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const polymarketCancelArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    orderId: z.string().min(1),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const checkoutEscrowIdArgsSchema = z.object({
+  id: z.string().min(1),
+});
+
+const checkoutPayreqIdArgsSchema = z.object({
+  id: z.string().min(1),
+});
+
+const checkoutWalletSelectorArgsSchema = z
+  .object({
+    id: z.string().min(1),
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const checkoutCreatePayreqArgsSchema = z
+  .object({
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    amount: z.string().min(1),
+    expiresInSeconds: z.number().int().positive().optional(),
+    autoReleaseSeconds: z.number().int().positive().optional(),
+    disputeWindowSeconds: z.number().int().positive().optional(),
+    metadata: z.record(z.unknown()).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const checkoutFundingConfirmArgsSchema = z.object({
+  id: z.string().min(1),
+  txHash: z.string().min(1),
+  minConfirmations: z.number().int().positive().optional(),
+});
+
+const checkoutAcceptArgsSchema = z.object({
+  id: z.string().min(1),
+});
+
+const checkoutProofArgsSchema = z.object({
+  id: z.string().min(1),
+  proofHash: z.string().trim().min(1).max(128),
+  proofUrl: z.string().url().optional(),
+});
+
+const checkoutDisputeArgsSchema = z.object({
+  id: z.string().min(1),
+  reasonCode: z.string().trim().min(3).max(64),
+  details: z.record(z.unknown()).optional(),
+});
+
+const checkoutSwapAndPayArgsSchema = z
+  .object({
+    id: z.string().min(1),
+    walletId: z.union([z.number().int().positive(), z.string().min(1)]).optional(),
+    walletAddress: z.string().min(1).optional(),
+    confirm: z.boolean().optional(),
+    slippage: z.number().positive().max(5).optional(),
+  })
+  .refine((data) => [data.walletId, data.walletAddress].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of walletId or walletAddress.",
+  });
+
+const checkoutWebhookCreateArgsSchema = z.object({
+  url: z.string().url(),
+  eventTypes: z.array(z.string().min(1)).optional(),
+  enabled: z.boolean().optional(),
+});
+
+const checkoutWebhookUpdateArgsSchema = z.object({
+  id: z.union([z.number().int().positive(), z.string().min(1)]),
+  url: z.string().url().optional(),
+  eventTypes: z.array(z.string().min(1)).optional(),
+  enabled: z.boolean().optional(),
+}).refine((data) => data.url !== undefined || data.eventTypes !== undefined || data.enabled !== undefined, {
+  message: "Provide at least one of url, eventTypes, or enabled.",
+});
+
+const checkoutWebhookDeleteArgsSchema = z.object({
+  id: z.union([z.number().int().positive(), z.string().min(1)]),
+});
+
 function queryString(params) {
   const search = new URLSearchParams();
   for (const [key, value] of Object.entries(params)) {
@@ -226,6 +376,9 @@ async function callAgentApi({ method, pathName, query, body, requireAuth = true
   if (requireAuth) {
     headers["X-Agent-Key"] = requireAgentKey();
   }
+  if (["POST", "PATCH", "DELETE"].includes(String(method || "").toUpperCase())) {
+    headers["Idempotency-Key"] = `mcp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  }
 
   const url = `${getBaseUrl()}${pathName}${queryString(query || {})}`;
   const response = await fetch(url, {
@@ -354,6 +507,9 @@ const tools = [
       properties: {
         network: { type: "string", description: "Example: mainnet, sepolia, solana-mainnet." },
         chain: { type: "string", enum: ["evm", "solana"] },
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }], description: "Optional wallet selector for history-linked activity." },
+        walletLabel: { type: "string", description: "Optional wallet selector for history-linked activity." },
+        walletAddress: { type: "string", description: "Optional wallet selector for history-linked activity." },
       },
       additionalProperties: false,
     },
@@ -363,7 +519,6 @@ const tools = [
         method: "GET",
         pathName: "/api/agent/supported-tokens",
         query: args,
-        requireAuth: false,
       }),
   },
   {
@@ -400,6 +555,9 @@ const tools = [
       type: "object",
       properties: {
         network: { type: "string" },
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }], description: "Optional wallet selector for history-linked activity." },
+        walletLabel: { type: "string", description: "Optional wallet selector for history-linked activity." },
+        walletAddress: { type: "string", description: "Optional wallet selector for history-linked activity." },
         tokenIn: { type: "string" },
         tokenOut: { type: "string" },
         amountIn: { type: "string" },
@@ -416,7 +574,6 @@ const tools = [
         pathName: "/api/agent/quote",
         query: { network },
         body,
-        requireAuth: false,
       });
     },
   },
@@ -478,7 +635,7 @@ const tools = [
         label: { type: "string" },
         network: {
           type: "string",
-          enum: ["sepolia", "mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"],
+          enum: ["sepolia", "mainnet", "polygon-mainnet", "solana-devnet", "solana-testnet", "solana-mainnet"],
         },
         exportPassphrase: { type: "string", minLength: 12 },
         exportPassphraseStorageType: { type: "string", enum: ["env", "secret_manager", "vault", "other"] },
@@ -514,12 +671,12 @@ const tools = [
   },
   {
     name: "wallet_import",
-    description: withWriteSafety("Import a mainnet or Solana mainnet wallet under the configured agent key."),
+    description: withWriteSafety("Import a mainnet, polygon-mainnet, or Solana mainnet wallet under the configured agent key."),
     inputSchema: {
       type: "object",
       properties: {
         label: { type: "string" },
-        network: { type: "string", enum: ["mainnet", "solana-mainnet"] },
+        network: { type: "string", enum: ["mainnet", "polygon-mainnet", "solana-mainnet"] },
         privateKey: { type: "string" },
       },
       required: ["label", "network", "privateKey"],
@@ -533,6 +690,524 @@ const tools = [
         body: args,
       }),
   },
+  {
+    name: "user_tag_get",
+    description: "Read global checkout user tag for the API key owner.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    parse: (args) => z.object({}).parse(args ?? {}),
+    execute: async () =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/user-tag",
+      }),
+  },
+  {
+    name: "user_tag_set",
+    description: withWriteSafety("Set global checkout user tag once (immutable after set)."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        userTag: { type: "string" },
+      },
+      required: ["userTag"],
+      additionalProperties: false,
+    },
+    parse: (args) => userTagSetArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "PUT",
+        pathName: "/api/agent/user-tag",
+        body: args,
+      }),
+  },
+  {
+    name: "checkout_payreq_create",
+    description: withWriteSafety("Create a checkout pay request and escrow."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        amount: { type: "string" },
+        expiresInSeconds: { type: "integer" },
+        autoReleaseSeconds: { type: "integer" },
+        disputeWindowSeconds: { type: "integer" },
+        metadata: { type: "object", additionalProperties: true },
+      },
+      required: ["amount"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutCreatePayreqArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/checkout/payreq",
+        body: args,
+      }),
+  },
+  {
+    name: "checkout_payreq_get",
+    description: "Get checkout pay request details by id.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutPayreqIdArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: `/api/agent/checkout/payreq/${encodeURIComponent(args.id)}`,
+      }),
+  },
+  {
+    name: "checkout_escrow_get",
+    description: "Get checkout escrow details by escrow id.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutEscrowIdArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(args.id)}`,
+      }),
+  },
+  {
+    name: "checkout_funding_confirm",
+    description: withWriteSafety("Confirm checkout escrow funding transaction."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        txHash: { type: "string" },
+        minConfirmations: { type: "integer" },
+      },
+      required: ["id", "txHash"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutFundingConfirmArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/funding-confirm`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_accept",
+    description: withWriteSafety("Accept escrow as buyer."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutAcceptArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/accept`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_proof_submit",
+    description: withWriteSafety("Submit checkout proof."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        proofHash: { type: "string" },
+        proofUrl: { type: "string" },
+      },
+      required: ["id", "proofHash"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutProofArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/proof`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_dispute_open",
+    description: withWriteSafety("Open checkout dispute."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        reasonCode: { type: "string" },
+        details: { type: "object", additionalProperties: true },
+      },
+      required: ["id", "reasonCode"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutDisputeArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/dispute`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_quick_pay",
+    description: withWriteSafety("Directly fund checkout escrow from buyer wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutWalletSelectorArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/quick-pay`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_swap_and_pay",
+    description: withWriteSafety("Swap source asset and fund checkout escrow."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        confirm: { type: "boolean" },
+        slippage: { type: "number" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutSwapAndPayArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/swap-and-pay`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_release",
+    description: withWriteSafety("Release checkout escrow to seller."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        force: { type: "boolean" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutEscrowIdArgsSchema.extend({ force: z.boolean().optional() }).parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/release`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_refund",
+    description: withWriteSafety("Refund checkout escrow to buyer."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        force: { type: "boolean" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutEscrowIdArgsSchema.extend({ force: z.boolean().optional() }).parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/refund`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_cancel",
+    description: withWriteSafety("Cancel checkout escrow."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutEscrowIdArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: `/api/agent/checkout/escrows/${encodeURIComponent(args.id)}/cancel`,
+        body: {},
+      }),
+  },
+  {
+    name: "checkout_webhooks_list",
+    description: "List checkout webhook subscriptions.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    parse: (args) => z.object({}).parse(args ?? {}),
+    execute: async () =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/checkout/webhooks",
+      }),
+  },
+  {
+    name: "checkout_webhook_create",
+    description: withWriteSafety("Create checkout webhook subscription."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: { type: "string" },
+        eventTypes: { type: "array", items: { type: "string" } },
+        enabled: { type: "boolean" },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutWebhookCreateArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/checkout/webhooks",
+        body: args,
+      }),
+  },
+  {
+    name: "checkout_webhook_update",
+    description: withWriteSafety("Update checkout webhook subscription."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        url: { type: "string" },
+        eventTypes: { type: "array", items: { type: "string" } },
+        enabled: { type: "boolean" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutWebhookUpdateArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, ...body } = args;
+      return callAgentApi({
+        method: "PATCH",
+        pathName: `/api/agent/checkout/webhooks/${encodeURIComponent(String(id))}`,
+        body,
+      });
+    },
+  },
+  {
+    name: "checkout_webhook_delete",
+    description: withWriteSafety("Delete checkout webhook subscription."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { oneOf: [{ type: "integer" }, { type: "string" }] },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutWebhookDeleteArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "DELETE",
+        pathName: `/api/agent/checkout/webhooks/${encodeURIComponent(String(args.id))}`,
+      }),
+  },
+  {
+    name: "polymarket_order_limit",
+    description: withWriteSafety("Place a Polymarket limit order from a configured polygon-mainnet wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        tokenId: { type: "string" },
+        side: { type: "string", enum: ["BUY", "SELL"] },
+        price: { type: "number" },
+        size: { type: "number" },
+      },
+      required: ["tokenId", "side", "price", "size"],
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketLimitArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/venues/polymarket/orders/limit",
+        body: args,
+      }),
+  },
+  {
+    name: "polymarket_order_market",
+    description: withWriteSafety("Place a Polymarket market order from a configured polygon-mainnet wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        tokenId: { type: "string" },
+        side: { type: "string", enum: ["BUY", "SELL"] },
+        amount: { type: "number" },
+        orderType: { type: "string", enum: ["FAK", "FOK", "GTC"] },
+        worstPrice: { type: "number" },
+      },
+      required: ["tokenId", "side", "amount"],
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketMarketArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/venues/polymarket/orders/market",
+        body: args,
+      }),
+  },
+  {
+    name: "polymarket_account",
+    description: "Read Polymarket account summary for a configured polygon-mainnet wallet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketReadArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/venues/polymarket/account",
+        query: args,
+      }),
+  },
+  {
+    name: "polymarket_orders",
+    description: "List Polymarket open orders for a configured polygon-mainnet wallet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        status: { type: "string" },
+        limit: { type: "integer" },
+        cursor: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketReadArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/venues/polymarket/orders",
+        query: args,
+      }),
+  },
+  {
+    name: "polymarket_cancel_order",
+    description: withWriteSafety("Cancel a Polymarket order for a configured polygon-mainnet wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        orderId: { type: "string" },
+      },
+      required: ["orderId"],
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketCancelArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/venues/polymarket/orders/cancel",
+        body: args,
+      }),
+  },
+  {
+    name: "polymarket_activity",
+    description: "List Polymarket trade activity for a configured polygon-mainnet wallet.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        limit: { type: "integer" },
+        cursor: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketReadArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/venues/polymarket/activity",
+        query: args,
+      }),
+  },
+  {
+    name: "polymarket_positions",
+    description: "List Polymarket open positions (open-market filtered) for a configured polygon-mainnet wallet, including position PnL fields.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        limit: { type: "integer" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketReadArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/venues/polymarket/positions",
+        query: args,
+      }),
+  },
 ];
 
 const resources = [
@@ -561,6 +1236,7 @@ const resources = [
       "3. Use `wallet_get` or `balances_get` before write actions.",
       "4. For writes, establish approval mode once per session.",
       "5. Use `swap_quote` before `swap_execute`.",
+      "6. For Polymarket: ask your human to complete setup in dashboard (/venues/polymarket), then place/cancel orders and inspect account/activity/positions via polymarket tools.",
     ].join("\n"),
   },
 ];
@@ -666,7 +1342,7 @@ async function runSelfTest() {
       capabilities: {},
       clientInfo: {
         name: "openclawcash-self-test",
-        version: "0.1.1",
+        version: SERVER_VERSION,
       },
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclawcash/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "OpenClawCash MCP server for managed agent wallets, balances, transfers, swaps, and approvals.",
   "type": "module",
   "license": "Proprietary",