truemarkets-mcp-server

Instructions

Implementation Reference

• src/tools/trade.ts:172-232 (handler)

  The handler function for 'tm_execute_trade' that retrieves a cached quote, signs its payloads using the provided signer, and executes the trade via the API.

    async ({ quote_id }) => {
      const quote = getCachedQuote(quote_id);
      if (!quote) {
        return {
          isError: true,
          content: [{
            type: "text",
            text: "Quote expired or not found. Call tm_get_quote to get a fresh quote.",
          }],
        };
      }
  
      if (quote.issues.length > 0) {
        return {
          isError: true,
          content: [{
            type: "text",
            text: `Quote has issues: ${quote.issues.map((i) => i.message).join(", ")}. Cannot execute.`,
          }],
        };
      }
  
      if (!quote.payloads || quote.payloads.length === 0) {
        return {
          isError: true,
          content: [{ type: "text", text: "Quote has no payloads to sign." }],
        };
      }
  
      // Sign payloads
      const signer = getSigner();
      const signatures = signer.signAll(quote.payloads);
  
      // Execute
      const result = await api.executeTrade({
        quote_id: quote.quote_id,
        signatures,
        auth_type: "api_key",
      });
  
      // Clean up cache
      quoteCache.delete(quote_id);
  
      const chain = quote.base_asset.startsWith("0x") ? "base" : "solana";
      const explorerUrl = result.tx_hash
        ? txExplorerUrl(chain, result.tx_hash)
        : null;
  
      const output = {
        success: true,
        order_id: result.order_id ?? null,
        tx_hash: result.tx_hash ?? null,
        explorer_url: explorerUrl,
      };
  
      return {
        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
        structuredContent: output,
      };
    }
  );

• src/tools/trade.ts:145-171 (registration)

  Registration of the 'tm_execute_trade' tool within the McpServer.

    // ─── tm_execute_trade ────────────────────────────────────────
    server.registerTool(
      "tm_execute_trade",
      {
        title: "Execute a quoted trade",
        description: `Execute a trade using a quote_id from tm_get_quote.
  
  IMPORTANT: Only call this after inspecting the quote from tm_get_quote.
  The quote must be less than 60 seconds old and have no issues.
  
  This tool signs the quote payloads with the user's Turnkey API key
  and submits the trade. It is irreversible.
  
  Args:
    - quote_id (string): The quote_id from tm_get_quote
  
  Returns: { success, order_id, tx_hash, explorer_url }`,
        inputSchema: {
          quote_id: z.string().describe("quote_id from tm_get_quote"),
        },
        annotations: {
          readOnlyHint: false,
          destructiveHint: true,
          idempotentHint: false,
          openWorldHint: true,
        },
      },