Zora Coins MCP Server

Instructions

Implementation Reference

• src/index.ts:432-490 (registration)

  Registration of the 'zora_trade_coin' MCP tool, including inline schema definition and handler function that orchestrates the trade using CoinsSDK.

  server.registerTool(
    "zora_trade_coin",
    {
      title: "Trade coin",
      description:
        "Swap ETH or ERC20 for a coin (or back). Uses permit2 for ERC20 where supported. Requires PRIVATE_KEY (EOA).",
      inputSchema: {
        sellType: z.enum(["eth", "erc20"]),
        sellAddress: z.string().optional(),     // required if sellType = erc20
        sellDecimals: z.number().int().min(0).max(36).optional(), // required if sellType = erc20
        buyType: z.enum(["eth", "erc20"]),
        buyAddress: z.string().optional(),      // required if buyType = erc20
        amount: z.string().min(1),              // human-readable, e.g., "0.001" ETH or "4" USDC
        slippage: z.number().min(0).max(0.99).default(0.05).optional(),
        recipient: z.string().optional(),
        sender: z.string().optional(),
      },
    },
    async (args) => {
      ensureWallet();
      const {
        sellType,
        sellAddress,
        sellDecimals,
        buyType,
        buyAddress,
        amount,
        slippage,
        recipient,
        sender,
      } = args;
  
      const amountIn =
        sellType === "eth"
          ? parseEther(amount)
          : parseUnits(
              amount,
              typeof sellDecimals === "number" ? sellDecimals : 18
            );
  
      const tradeParameters: any = {
        sell: sellType === "eth" ? { type: "eth" } : { type: "erc20", address: sellAddress },
        buy: buyType === "eth" ? { type: "eth" } : { type: "erc20", address: buyAddress },
        amountIn,
        slippage: typeof slippage === "number" ? slippage : 0.05,
        sender: sender || account!.address,
        recipient: recipient || account!.address,
      };
  
      const receipt = await CoinsSDK.tradeCoin({
        tradeParameters,
        walletClient: walletClient!,
        account: account!,
        publicClient,
      });
  
      return { content: [{ type: "text", text: json(receipt) }] };
    }
  );

• src/index.ts:450-489 (handler)

  The core handler logic for executing the 'zora_trade_coin' tool. Parses input amounts, constructs trade parameters, ensures wallet is set up, calls external CoinsSDK.tradeCoin, and formats the response.

  async (args) => {
    ensureWallet();
    const {
      sellType,
      sellAddress,
      sellDecimals,
      buyType,
      buyAddress,
      amount,
      slippage,
      recipient,
      sender,
    } = args;
  
    const amountIn =
      sellType === "eth"
        ? parseEther(amount)
        : parseUnits(
            amount,
            typeof sellDecimals === "number" ? sellDecimals : 18
          );
  
    const tradeParameters: any = {
      sell: sellType === "eth" ? { type: "eth" } : { type: "erc20", address: sellAddress },
      buy: buyType === "eth" ? { type: "eth" } : { type: "erc20", address: buyAddress },
      amountIn,
      slippage: typeof slippage === "number" ? slippage : 0.05,
      sender: sender || account!.address,
      recipient: recipient || account!.address,
    };
  
    const receipt = await CoinsSDK.tradeCoin({
      tradeParameters,
      walletClient: walletClient!,
      account: account!,
      publicClient,
    });
  
    return { content: [{ type: "text", text: json(receipt) }] };
  }

• src/index.ts:434-449 (schema)

  Zod input schema for the 'zora_trade_coin' tool, validating parameters for selling ETH/ERC20 to buy coin or vice versa, including slippage and addresses.

  {
    title: "Trade coin",
    description:
      "Swap ETH or ERC20 for a coin (or back). Uses permit2 for ERC20 where supported. Requires PRIVATE_KEY (EOA).",
    inputSchema: {
      sellType: z.enum(["eth", "erc20"]),
      sellAddress: z.string().optional(),     // required if sellType = erc20
      sellDecimals: z.number().int().min(0).max(36).optional(), // required if sellType = erc20
      buyType: z.enum(["eth", "erc20"]),
      buyAddress: z.string().optional(),      // required if buyType = erc20
      amount: z.string().min(1),              // human-readable, e.g., "0.001" ETH or "4" USDC
      slippage: z.number().min(0).max(0.99).default(0.05).optional(),
      recipient: z.string().optional(),
      sender: z.string().optional(),
    },
  },