clanker-sdk 1.1.0 → 1.4.0

package/README.md

@@ -21,7 +21,11 @@ We'll evaluate each request individually as we carefully scale our platform acce
 Create a `.env` file in your project root:
 
 ```bash
+# Clanker API Key (required for token operations)
 CLANKER_API_KEY=your_api_key_here
+
+# Dune Analytics API Key (required for market data)
+DUNE_API_KEY=your_dune_api_key_here
 ```
 
 Copy the `.env.example` file to get started:
@@ -30,47 +34,45 @@ Copy the `.env.example` file to get started:
 cp .env.example .env
 ```
 
-Make sure to add your API key to the `.env` file and never commit it to version control.
+Make sure to add your API keys to the `.env` file and never commit it to version control.
+
+### 3. Getting Your Dune API Key
+
+To access market data features, you'll need a Dune Analytics API key:
+
+1. Visit [dune.xyz](https://dune.xyz) and sign up for an account
+2. Go to your [API Keys page](https://dune.com/settings/api)
+3. Create a new API key
+4. Add the key to your `.env` file as `DUNE_API_KEY`
+
+Note: Dune API access requires a paid subscription. Check their [pricing page](https://dune.com/pricing) for more details.
 
-### 3. Basic Usage
+### 4. Basic Usage
 
 ```typescript
 import * as dotenv from 'dotenv';
-import { ClankerSDK } from 'clanker-sdk';
-import { randomBytes } from 'crypto';  // Node.js built-in crypto module
+import { ClankerSDK, MarketDataClient } from 'clanker-sdk';
 
 // Load environment variables
 dotenv.config();
 
-// Validate API key
-const API_KEY = process.env.CLANKER_API_KEY;
-if (!API_KEY) {
-  throw new Error('Missing CLANKER_API_KEY in environment variables');
-}
+// Initialize SDK for token operations
+const clanker = new ClankerSDK(process.env.CLANKER_API_KEY);
 
-// Generate a unique 32-character request key for idempotency
-function generateRequestKey(): string {
-  return randomBytes(16).toString('hex');  // Generates a 32-character hex string
-}
+// Initialize market data client for analytics
+const marketData = new MarketDataClient(process.env.DUNE_API_KEY);
 
-// Initialize SDK
-const clanker = new ClankerSDK(API_KEY);
-
-// Deploy a token with custom splits (requires requestKey)
-const token = await clanker.deployTokenWithSplits({
+// Deploy a token
+const token = await clanker.deployToken({
   name: "Community Token",
   symbol: "CMTY",
   image: "https://example.com/token.png",
   requestorAddress: "0x1234567890123456789012345678901234567890", // Address receiving 40% creator rewards
-  requestKey: generateRequestKey(), // Required for preventing duplicate deployments
-  splitAddress: "0x935Ce0B6bBE179B45061BD5477A4BBA304fc3FFe"
 });
-```
 
-## Important Notes
-
-- **requestKey**: A unique 32-character string required for custom deployments (like splits) to prevent duplicate tokens (idempotency check)
-- **requestorAddress**: The address where 40% of creator rewards will be sent
+// Get market data for your tokens
+const marketStats = await marketData.getClankerDictionary();
+```
 
 ## Features
 
@@ -79,6 +81,45 @@ const token = await clanker.deployTokenWithSplits({
 - 📊 Rewards Tracking
 - 🔒 Type-safe API
 - 📝 Full TypeScript Support
+- 📈 Market Data Analytics
+
+## Market Data Features
+
+The SDK provides access to comprehensive market data through Dune Analytics integration:
+
+### Clanker Dictionary
+Get detailed information about all Clanker tokens:
+```typescript
+const dictionary = await marketData.getClankerDictionary();
+// Returns: Array of tokens with market cap, volume, and liquidity data
+```
+
+### DEX Pair Statistics
+Get detailed DEX pair statistics for any token:
+```typescript
+const dexStats = await marketData.getDexPairStats(
+  'ethereum',  // Chain name (ethereum, arbitrum, etc.)
+  '0x1234...'  // Optional: Token address to filter by
+);
+// Returns: Detailed DEX pair statistics including:
+// - Trading volumes (24h, 7d, 30d)
+// - Liquidity
+// - Volume/Liquidity ratios
+```
+
+Supported chains for DEX stats:
+- ethereum
+- arbitrum
+- base
+- bnb
+- celo
+- fantom
+- gnosis
+- optimism
+- polygon
+- scroll
+- zk_sync
+- solana
 
 ## Examples
 
@@ -86,12 +127,14 @@ Check out the `examples/` directory for more usage examples:
 
 - Token Deployment (`examples/token-deployment.ts`)
 - Rewards and Fees (`examples/rewards-and-fees.ts`)
+- Market Data (`examples/market-data.ts`)
 
 Run examples using:
 
 ```bash
 npm run example:deploy    # Run token deployment example
 npm run example:rewards   # Run rewards tracking example
+npm run example:market   # Run market data example
 npm run example          # Run all examples
 ```
 

package/dist/index.d.mts

@@ -67,4 +67,37 @@ declare class ClankerSDK {
     private validateDeployOptions;
 }
 
-export { ClankerError, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, type Token, type UncollectedFeesResponse, ClankerSDK as default };
+interface ClankerMarketData {
+    name: string;
+    symbol: string;
+    marketCap?: number;
+    volume24h?: number;
+    volume7d?: number;
+    liquidity?: number;
+}
+declare class MarketDataClient {
+    private readonly dune;
+    private readonly apiKey;
+    private readonly DICTIONARY_QUERY_ID;
+    constructor(duneApiKey: string);
+    /**
+     * Get market data from the materialized view
+     */
+    getClankerDictionary(): Promise<ClankerMarketData[]>;
+    /**
+     * Get DEX pair stats for a specific chain
+     * @param chain - The blockchain to query (e.g., 'ethereum', 'arbitrum', etc.)
+     * @param tokenAddress - Optional token address to filter by
+     */
+    getDexPairStats(chain: string, tokenAddress?: string): Promise<any>;
+    /**
+     * Transform raw dictionary data into a standardized format
+     */
+    private transformDictionaryData;
+    /**
+     * Filter DEX pairs by token address
+     */
+    private filterPairsByToken;
+}
+
+export { ClankerError, type ClankerMarketData, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, MarketDataClient, type Token, type UncollectedFeesResponse, ClankerSDK as default };

package/dist/index.d.ts

@@ -67,4 +67,37 @@ declare class ClankerSDK {
     private validateDeployOptions;
 }
 
-export { ClankerError, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, type Token, type UncollectedFeesResponse, ClankerSDK as default };
+interface ClankerMarketData {
+    name: string;
+    symbol: string;
+    marketCap?: number;
+    volume24h?: number;
+    volume7d?: number;
+    liquidity?: number;
+}
+declare class MarketDataClient {
+    private readonly dune;
+    private readonly apiKey;
+    private readonly DICTIONARY_QUERY_ID;
+    constructor(duneApiKey: string);
+    /**
+     * Get market data from the materialized view
+     */
+    getClankerDictionary(): Promise<ClankerMarketData[]>;
+    /**
+     * Get DEX pair stats for a specific chain
+     * @param chain - The blockchain to query (e.g., 'ethereum', 'arbitrum', etc.)
+     * @param tokenAddress - Optional token address to filter by
+     */
+    getDexPairStats(chain: string, tokenAddress?: string): Promise<any>;
+    /**
+     * Transform raw dictionary data into a standardized format
+     */
+    private transformDictionaryData;
+    /**
+     * Filter DEX pairs by token address
+     */
+    private filterPairsByToken;
+}
+
+export { ClankerError, type ClankerMarketData, ClankerSDK, type DeployTokenOptions, type DeployTokenWithSplitsOptions, type DeployedToken, type DeployedTokensResponse, type EstimatedRewardsResponse, MarketDataClient, type Token, type UncollectedFeesResponse, ClankerSDK as default };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   ClankerError: () => ClankerError,
   ClankerSDK: () => ClankerSDK,
+  MarketDataClient: () => MarketDataClient,
   default: () => ClankerSDK
 });
 module.exports = __toCommonJS(index_exports);
@@ -164,8 +165,92 @@ var ClankerSDK = class {
     }
   }
 };
+
+// src/MarketData.ts
+var import_client_sdk = require("@duneanalytics/client-sdk");
+var MarketDataClient = class {
+  // Your materialized view query ID
+  constructor(duneApiKey) {
+    this.DICTIONARY_QUERY_ID = 4405741;
+    if (!duneApiKey) {
+      throw new ClankerError("Dune API key is required for market data");
+    }
+    this.apiKey = duneApiKey;
+    this.dune = new import_client_sdk.DuneClient(duneApiKey);
+  }
+  /**
+   * Get market data from the materialized view
+   */
+  async getClankerDictionary() {
+    try {
+      const result = await this.dune.getLatestResult({ queryId: this.DICTIONARY_QUERY_ID });
+      if (!result?.result?.rows) {
+        throw new ClankerError("No data returned from Dune");
+      }
+      return this.transformDictionaryData(result.result.rows);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new ClankerError(`Failed to fetch Clanker dictionary: ${error.message}`);
+      }
+      throw new ClankerError("Failed to fetch Clanker dictionary");
+    }
+  }
+  /**
+   * Get DEX pair stats for a specific chain
+   * @param chain - The blockchain to query (e.g., 'ethereum', 'arbitrum', etc.)
+   * @param tokenAddress - Optional token address to filter by
+   */
+  async getDexPairStats(chain, tokenAddress) {
+    const url = `https://api.dune.com/api/v1/dex/pairs/${chain}`;
+    const options = {
+      method: "GET",
+      headers: {
+        "X-Dune-Api-Key": this.apiKey
+      }
+    };
+    try {
+      const response = await fetch(url, options);
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const data = await response.json();
+      if (tokenAddress) {
+        return this.filterPairsByToken(data, tokenAddress);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new ClankerError(`Failed to fetch DEX pair stats: ${error.message}`);
+      }
+      throw new ClankerError("Failed to fetch DEX pair stats");
+    }
+  }
+  /**
+   * Transform raw dictionary data into a standardized format
+   */
+  transformDictionaryData(rows) {
+    return rows.map((row) => ({
+      name: row.name || "",
+      symbol: row.symbol || "",
+      marketCap: row.market_cap || void 0,
+      volume24h: row.volume_24h || void 0,
+      volume7d: row.volume_7d || void 0,
+      liquidity: row.liquidity || void 0
+    }));
+  }
+  /**
+   * Filter DEX pairs by token address
+   */
+  filterPairsByToken(data, tokenAddress) {
+    const rows = data?.result?.rows || [];
+    return rows.filter(
+      (pair) => pair.token_a_address?.toLowerCase() === tokenAddress.toLowerCase() || pair.token_b_address?.toLowerCase() === tokenAddress.toLowerCase()
+    );
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ClankerError,
-  ClankerSDK
+  ClankerSDK,
+  MarketDataClient
 });

package/dist/index.mjs

@@ -126,8 +126,92 @@ var ClankerSDK = class {
     }
   }
 };
+
+// src/MarketData.ts
+import { DuneClient } from "@duneanalytics/client-sdk";
+var MarketDataClient = class {
+  // Your materialized view query ID
+  constructor(duneApiKey) {
+    this.DICTIONARY_QUERY_ID = 4405741;
+    if (!duneApiKey) {
+      throw new ClankerError("Dune API key is required for market data");
+    }
+    this.apiKey = duneApiKey;
+    this.dune = new DuneClient(duneApiKey);
+  }
+  /**
+   * Get market data from the materialized view
+   */
+  async getClankerDictionary() {
+    try {
+      const result = await this.dune.getLatestResult({ queryId: this.DICTIONARY_QUERY_ID });
+      if (!result?.result?.rows) {
+        throw new ClankerError("No data returned from Dune");
+      }
+      return this.transformDictionaryData(result.result.rows);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new ClankerError(`Failed to fetch Clanker dictionary: ${error.message}`);
+      }
+      throw new ClankerError("Failed to fetch Clanker dictionary");
+    }
+  }
+  /**
+   * Get DEX pair stats for a specific chain
+   * @param chain - The blockchain to query (e.g., 'ethereum', 'arbitrum', etc.)
+   * @param tokenAddress - Optional token address to filter by
+   */
+  async getDexPairStats(chain, tokenAddress) {
+    const url = `https://api.dune.com/api/v1/dex/pairs/${chain}`;
+    const options = {
+      method: "GET",
+      headers: {
+        "X-Dune-Api-Key": this.apiKey
+      }
+    };
+    try {
+      const response = await fetch(url, options);
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const data = await response.json();
+      if (tokenAddress) {
+        return this.filterPairsByToken(data, tokenAddress);
+      }
+      return data;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new ClankerError(`Failed to fetch DEX pair stats: ${error.message}`);
+      }
+      throw new ClankerError("Failed to fetch DEX pair stats");
+    }
+  }
+  /**
+   * Transform raw dictionary data into a standardized format
+   */
+  transformDictionaryData(rows) {
+    return rows.map((row) => ({
+      name: row.name || "",
+      symbol: row.symbol || "",
+      marketCap: row.market_cap || void 0,
+      volume24h: row.volume_24h || void 0,
+      volume7d: row.volume_7d || void 0,
+      liquidity: row.liquidity || void 0
+    }));
+  }
+  /**
+   * Filter DEX pairs by token address
+   */
+  filterPairsByToken(data, tokenAddress) {
+    const rows = data?.result?.rows || [];
+    return rows.filter(
+      (pair) => pair.token_a_address?.toLowerCase() === tokenAddress.toLowerCase() || pair.token_b_address?.toLowerCase() === tokenAddress.toLowerCase()
+    );
+  }
+};
 export {
   ClankerError,
   ClankerSDK,
+  MarketDataClient,
   ClankerSDK as default
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-sdk",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "description": "A lightweight TypeScript SDK for interacting with the Clanker API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -17,7 +17,8 @@
     "prepare": "npm run build",
     "example:deploy": "ts-node examples/token-deployment.ts",
     "example:rewards": "ts-node examples/rewards-and-fees.ts",
-    "example": "npm run example:deploy && npm run example:rewards"
+    "example:market": "ts-node examples/market-data.ts",
+    "example": "npm run example:deploy && npm run example:rewards && npm run example:market"
   },
   "publishConfig": {
     "access": "public",
@@ -43,6 +44,7 @@
   "author": "Clanker Team",
   "license": "ISC",
   "dependencies": {
+    "@duneanalytics/client-sdk": "^0.2.5",
     "axios": "^1.6.7"
   },
   "devDependencies": {