@mercnet/windmill

Windmill integration adapter for MercNet GraphQL API - A simplified interface for Windmill workflows to interact with MercNet's trading data.

Installation

npm install @mercnet/windmill

Quick Start

import { createClient, createMercNetClient } from '@mercnet/windmill'

// Using the default MercNet endpoint
const client = createMercNetClient({
  token: 'your-auth-token'
})

// Or specify a custom endpoint
const customClient = createClient({
  endpoint: 'https://your-graphql-endpoint.com/graphql',
  token: 'your-auth-token'
})

// Get all markets
const markets = await client.getAllMarkets()

// Get specific market by ID
const market = await client.getMarketById(1)

// Get market by ticker
const btcMarket = await client.getMarketByTicker('BTC')

Features

• Pre-configured GraphQL Client: Ready-to-use client with authentication and error handling
• Type-safe Operations: Full TypeScript support with generated types
• Windmill Optimized: Designed specifically for Windmill workflow integration
• Utility Functions: Common trading operations simplified for workflow use
• Flexible Configuration: Support for custom endpoints and authentication

API Reference

Core Functions

createClient(config: WindmillClientConfig)

Creates a pre-configured MercNet GraphQL client.

const client = createClient({
  endpoint: 'http://graphql.rocketeer.trade/rpc/graphql_query',
  token: 'your-auth-token',
  debug: true,
  retries: 3
})

createMercNetClient(config: Partial<WindmillClientConfig>)

Creates a client with the default MercNet endpoint pre-configured.

const client = createMercNetClient({
  token: 'your-auth-token'
})

Market Operations

getAllMarkets()

Retrieves all available markets.

const markets = await client.getAllMarkets()
console.log(`Found ${markets.length} markets`)

getMarketById(id: number)

Retrieves a specific market by its ID.

const market = await client.getMarketById(1)
if (market) {
  console.log(`Market: ${market.name} (${market.ticker})`)
}

getMarketByTicker(ticker: string)

Retrieves a market by its ticker symbol.

const btcMarket = await client.getMarketByTicker('BTC')

getMarketsByStatus(status: string)

Retrieves all markets with a specific status.

const activeMarkets = await client.getMarketsByStatus('active')

Utility Class

WindmillMercNetUtils

Provides specialized utility functions for common Windmill workflow operations.

import { createUtils } from '@mercnet/windmill'

const utils = createUtils({
  endpoint: 'http://graphql.rocketeer.trade/rpc/graphql_query',
  token: 'your-token'
})

// Get only active markets
const activeMarkets = await utils.getActiveMarkets()

// Get market summary for reporting
const summary = await utils.getMarketSummary(1)

// Search markets by ticker pattern
const cryptoMarkets = await utils.searchMarketsByTicker('BTC')

// Get sentiment analysis for all markets
const sentiments = await utils.getMarketsSentiment()

Configuration Options

interface WindmillClientConfig {
  /** GraphQL endpoint URL */
  endpoint: string
  /** Authentication token for API access */
  token?: string
  /** Additional headers to include in requests */
  headers?: Record<string, string>
  /** Number of retry attempts for failed requests */
  retries?: number
  /** Enable debug logging */
  debug?: boolean
}

Market Data Structure

interface Market {
  id: number
  name?: string | null
  short_name?: string | null
  ticker: string
  price?: string | null
  type?: string | null
  created_at?: string | null
  last_update_at?: string | null
  trend_status?: string | null
  sentiment?: string | null
  sentiment_update_at?: string | null
  market_activity_score_1h?: string | null
  market_activity_score_1d?: string | null
  data?: Record<string, unknown> | null
  status?: string | null
}

Windmill Integration Examples

Basic Market Data Retrieval

// windmill-market-data.ts
import { createMercNetClient } from '@mercnet/windmill'

export async function main(token: string) {
  const client = createMercNetClient({ token })
  
  const markets = await client.getAllMarkets()
  
  return {
    totalMarkets: markets.length,
    activeMarkets: markets.filter(m => m.status === 'active').length,
    markets: markets.map(m => ({
      id: m.id,
      name: m.name,
      ticker: m.ticker,
      price: m.price,
      sentiment: m.sentiment
    }))
  }
}

Market Monitoring Workflow

// windmill-market-monitor.ts
import { createUtils } from '@mercnet/windmill'

export async function main(token: string, alertThreshold: number = 5.0) {
  const utils = createUtils({
    endpoint: 'http://graphql.rocketeer.trade/rpc/graphql_query',
    token
  })
  
  const activeMarkets = await utils.getActiveMarkets()
  const alerts = []
  
  for (const market of activeMarkets) {
    const summary = await utils.getMarketSummary(market.id)
    
    if (summary?.activityScore1h && parseFloat(summary.activityScore1h) > alertThreshold) {
      alerts.push({
        ticker: market.ticker,
        activityScore: summary.activityScore1h,
        sentiment: summary.sentiment,
        trend: summary.trend
      })
    }
  }
  
  return {
    timestamp: new Date().toISOString(),
    totalMarkets: activeMarkets.length,
    alertsTriggered: alerts.length,
    alerts
  }
}

Sentiment Analysis Report

// windmill-sentiment-report.ts
import { createUtils } from '@mercnet/windmill'

export async function main(token: string) {
  const utils = createUtils({
    endpoint: 'http://graphql.rocketeer.trade/rpc/graphql_query',
    token
  })
  
  const sentiments = await utils.getMarketsSentiment()
  
  const sentimentCounts = sentiments.reduce((acc, market) => {
    const sentiment = market.sentiment || 'unknown'
    acc[sentiment] = (acc[sentiment] || 0) + 1
    return acc
  }, {} as Record<string, number>)
  
  return {
    timestamp: new Date().toISOString(),
    totalMarketsWithSentiment: sentiments.length,
    sentimentBreakdown: sentimentCounts,
    recentUpdates: sentiments
      .filter(m => m.sentimentUpdateAt)
      .sort((a, b) => new Date(b.sentimentUpdateAt!).getTime() - new Date(a.sentimentUpdateAt!).getTime())
      .slice(0, 10)
  }
}

Error Handling

The client includes comprehensive error handling with retry logic and detailed error information:

import { MercNetError } from '@mercnet/windmill'

try {
  const markets = await client.getAllMarkets()
} catch (error) {
  if (error instanceof MercNetError) {
    console.error('MercNet API Error:', error.message)
    console.error('Error Code:', error.code)
    console.error('Details:', error.details)
  } else {
    console.error('Unexpected error:', error)
  }
}

TypeScript Support

This package is built with TypeScript and provides full type safety:

import type { Market, WindmillClientConfig, GraphQLResponse } from '@mercnet/windmill'

// All operations are fully typed
const client = createMercNetClient({ token: 'your-token' })
const markets: Market[] = await client.getAllMarkets()

Contributing

This package is part of the MercNet v2 monorepo. See the main repository for contribution guidelines.

License

MIT