@openclawcash/mcp-server 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # OpenClawCash MCP Server
 
-This folder contains the public OpenClawCash stdio MCP server package that exposes OpenClawCash agent wallet operations as MCP tools.
+This folder contains the public OpenClawCash stdio MCP server package, which exposes OpenClawCash agent operations as MCP tools.
 
 It is a thin adapter over the existing OpenClawCash agent API at `https://openclawcash.com/api/agent/*`.
 
@@ -8,17 +8,60 @@ Canonical docs page: `https://openclawcash.com/mcp`
 
 ## What It Exposes
 
+Wallet and profile tools:
+
 - `wallets_list`
 - `wallet_get`
 - `transactions_list`
 - `balances_get`
 - `supported_tokens_list`
+- `user_tag_get`
+- `user_tag_set`
+- `wallet_create`
+- `wallet_import`
+
+Trading and transfer tools:
+
 - `transfer_send`
 - `swap_quote`
 - `swap_execute`
 - `approve_token`
-- `wallet_create`
-- `wallet_import`
+
+Get Paid checkout tools:
+
+- `checkout_payreq_create`
+- `checkout_payreq_get`
+- `checkout_escrow_get`
+- `checkout_funding_confirm`
+- `checkout_accept`
+- `checkout_proof_submit`
+- `checkout_dispute_open`
+- `checkout_quick_pay`
+- `checkout_swap_and_pay`
+- `checkout_fund` (quick-pay first, swap fallback)
+- `checkout_release`
+- `checkout_refund`
+- `checkout_cancel`
+- `checkout_webhooks_list`
+- `checkout_webhook_create`
+- `checkout_webhook_update`
+- `checkout_webhook_delete`
+
+Polymarket tools:
+
+- `polymarket_market_resolve`
+- `polymarket_order_limit`
+- `polymarket_order_market`
+- `polymarket_account`
+- `polymarket_orders`
+- `polymarket_cancel_order`
+- `polymarket_clear_integration`
+- `polymarket_activity`
+- `polymarket_positions`
+
+Utility tool:
+
+- `openclawcash-self-test`
 
 It also exposes two lightweight MCP resources:
 
@@ -222,6 +265,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.6";
+const SERVER_VERSION = "0.1.9";
 const PROTOCOL_VERSION = "2024-11-05";
 const DEFAULT_BASE_URL = "https://openclawcash.com";
 
@@ -250,6 +250,25 @@ const polymarketCancelArgsSchema = z
     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),
 });
@@ -316,6 +335,18 @@ const checkoutSwapAndPayArgsSchema = z
     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(),
@@ -523,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: {
@@ -541,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",
@@ -919,6 +977,78 @@ const tools = [
       });
     },
   },
+  {
+    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."),
@@ -1056,9 +1186,30 @@ const tools = [
         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."),
+    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: {
@@ -1082,7 +1233,7 @@ const tools = [
   },
   {
     name: "polymarket_order_market",
-    description: withWriteSafety("Place a Polymarket market order from a configured polygon-mainnet wallet."),
+    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: {
@@ -1167,6 +1318,25 @@ const tools = [
         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.",
@@ -1235,8 +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`.",
-      "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.",
+      "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,7 +1,7 @@
 {
   "name": "@openclawcash/mcp-server",
-  "version": "0.1.4",
-  "description": "OpenClawCash MCP server for managed agent wallets, balances, transfers, swaps, and approvals.",
+  "version": "0.1.6",
+  "description": "OpenClawCash MCP server for managed agent wallets, balances, transfers, swaps, approvals, Get Paid checkout escrow flows, and Polymarket market resolution/order tools.",
   "type": "module",
   "license": "Proprietary",
   "homepage": "https://openclawcash.com/mcp",