@openclawcash/mcp-server 0.1.3 → 0.1.5

package/README.md

@@ -16,6 +16,7 @@ Canonical docs page: `https://openclawcash.com/mcp`
 - `transfer_send`
 - `swap_quote`
 - `swap_execute`
+- `checkout_fund` (quick-pay first, swap fallback)
 - `approve_token`
 - `wallet_create`
 - `wallet_import`
@@ -222,6 +223,10 @@ The MCP server itself does not hold approval memory. The MCP client or agent run
 - `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.
+- `transfer_send` is for normal wallet transfers. For checkout escrow funding, use checkout tools:
+  - `checkout_quick_pay` for direct settlement funding
+  - `checkout_swap_and_pay` for asset mismatch funding
+  - `checkout_funding_confirm` to confirm external/manual funding transactions
 - 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.
 

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.3";
+const SERVER_VERSION = "0.1.9";
 const PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_BASE_URL = "https://openclawcash.com";
 
@@ -178,7 +178,7 @@ const supportedTokensArgsSchema = walletSelectorBaseSchema
 
 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),
@@ -187,10 +187,185 @@ 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 polymarketUnlinkArgsSchema = z
+  .object({
+    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 polymarketMarketResolveArgsSchema = z
+  .object({
+    marketUrl: z.string().url().optional(),
+    slug: z.string().min(1).optional(),
+    outcome: z.string().min(1),
+  })
+  .refine((data) => [data.marketUrl, data.slug].filter((v) => v !== undefined).length === 1, {
+    message: "Provide exactly one of marketUrl or slug.",
+  });
+
+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 checkoutFundArgsSchema = 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(),
+    slippage: z.number().positive().max(5).optional(),
+    allowSwapFallback: z.boolean().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)) {
@@ -232,6 +407,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, {
@@ -376,7 +554,9 @@ const tools = [
   },
   {
     name: "transfer_send",
-    description: withWriteSafety("Send a native asset or token transfer from a managed wallet."),
+    description: withWriteSafety(
+      "Send a native asset or token transfer from a managed wallet. Do not use for checkout escrow funding; use checkout_quick_pay or checkout_swap_and_pay.",
+    ),
     inputSchema: {
       type: "object",
       properties: {
@@ -394,12 +574,37 @@ const tools = [
       additionalProperties: false,
     },
     parse: (args) => transferArgsSchema.parse(args ?? {}),
-    execute: async (args) =>
-      callAgentApi({
-        method: "POST",
-        pathName: "/api/agent/transfer",
-        body: args,
-      }),
+    execute: async (args) => {
+      try {
+        return await callAgentApi({
+          method: "POST",
+          pathName: "/api/agent/transfer",
+          body: args,
+        });
+      } catch (error) {
+        const payload = error?.payload;
+        const code = typeof payload?.code === "string" ? payload.code : "";
+        if (code === "unsupported_funding_asset" || code === "unsupported_funding_network") {
+          const enriched = new Error(
+            [
+              "Checkout escrow funding is restricted to checkout funding endpoints.",
+              "Use `checkout_quick_pay` (direct settlement) or `checkout_swap_and_pay` (asset mismatch), then `checkout_funding_confirm` if needed.",
+            ].join(" "),
+          );
+          enriched.status = error?.status;
+          enriched.payload = {
+            ...(payload && typeof payload === "object" ? payload : {}),
+            mcpHints: {
+              quickPayTool: "checkout_quick_pay",
+              swapAndPayTool: "checkout_swap_and_pay",
+              fundingConfirmTool: "checkout_funding_confirm",
+            },
+          };
+          throw enriched;
+        }
+        throw error;
+      }
+    },
   },
   {
     name: "swap_quote",
@@ -488,7 +693,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"] },
@@ -524,12 +729,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"],
@@ -543,6 +748,636 @@ 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_fund",
+    description: withWriteSafety(
+      "Default escrow funding flow: try direct quick-pay first, then automatically fallback to swap-and-pay when required.",
+    ),
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+        slippage: { type: "number" },
+        allowSwapFallback: { type: "boolean", description: "Defaults to true." },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    parse: (args) => checkoutFundArgsSchema.parse(args ?? {}),
+    execute: async (args) => {
+      const { id, walletId, walletAddress, slippage, allowSwapFallback = true } = args;
+      const selector = {
+        ...(walletId !== undefined ? { walletId } : {}),
+        ...(walletAddress !== undefined ? { walletAddress } : {}),
+      };
+
+      try {
+        const quickPay = await callAgentApi({
+          method: "POST",
+          pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/quick-pay`,
+          body: selector,
+        });
+        return {
+          strategy: "quick-pay",
+          fallbackUsed: false,
+          quickPay,
+        };
+      } catch (error) {
+        const code = typeof error?.payload?.code === "string" ? error.payload.code : "";
+        if (code !== "quick_pay_requires_swap" || !allowSwapFallback) {
+          throw error;
+        }
+
+        const quotePreview = await callAgentApi({
+          method: "POST",
+          pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/swap-and-pay`,
+          body: {
+            ...selector,
+            ...(slippage !== undefined ? { slippage } : {}),
+            confirm: false,
+          },
+        });
+
+        const swapAndPay = await callAgentApi({
+          method: "POST",
+          pathName: `/api/agent/checkout/escrows/${encodeURIComponent(id)}/swap-and-pay`,
+          body: {
+            ...selector,
+            ...(slippage !== undefined ? { slippage } : {}),
+            confirm: true,
+          },
+        });
+
+        return {
+          strategy: "swap-and-pay",
+          fallbackUsed: true,
+          fallbackReason: code,
+          quote: quotePreview?.quote || null,
+          swapAndPay,
+        };
+      }
+    },
+  },
+  {
+    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_market_resolve",
+    description: "Resolve a Polymarket market URL/slug and human-readable outcome label to the exact CLOB tokenId required by order tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        marketUrl: { type: "string", description: "Polymarket market or event URL." },
+        slug: { type: "string", description: "Polymarket market slug (alternative to marketUrl)." },
+        outcome: { type: "string", description: "Outcome label, e.g. Yes, No, Trump, Harris." },
+      },
+      required: ["outcome"],
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketMarketResolveArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "GET",
+        pathName: "/api/agent/venues/polymarket/market/resolve",
+        query: args,
+      }),
+  },
+  {
+    name: "polymarket_order_limit",
+    description: withWriteSafety("Place a Polymarket limit order from a configured polygon-mainnet wallet. Use this for explicit target-price orders; for close-position intent, prefer market SELL unless a limit price is explicitly requested."),
+    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. For close-position intent on open markets, default to side=SELL (SELL amount is shares); use limit SELL only for explicit target-price requests."),
+    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_clear_integration",
+    description: withWriteSafety("Clear Polymarket integration for a configured polygon-mainnet wallet."),
+    inputSchema: {
+      type: "object",
+      properties: {
+        walletId: { oneOf: [{ type: "integer" }, { type: "string" }] },
+        walletAddress: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    parse: (args) => polymarketUnlinkArgsSchema.parse(args ?? {}),
+    execute: async (args) =>
+      callAgentApi({
+        method: "POST",
+        pathName: "/api/agent/venues/polymarket/unlink",
+        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 = [
@@ -570,7 +1405,9 @@ const resources = [
       "2. Use `wallets_list` first to discover managed wallets.",
       "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`.",
+      "5. For checkout escrow funding, use `checkout_fund` (quick-pay first, swap fallback when needed).",
+      "6. Use `swap_quote` before `swap_execute` for non-checkout swaps.",
+      "7. 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"),
   },
 ];

package/package.json

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