four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/dex/jup/tokens.js

@@ -0,0 +1,697 @@
+/**
+ * Jupiter Tokens API V2 (Beta)
+ * @module sol/dex/jup/tokens
+ *
+ * Tokens API V2 提供更详细的代币信息查询
+ * 包括市场数据、统计数据、审计信息等
+ */
+import { jupGet } from './client.js';
+// ============================================================================
+// Search API - 搜索代币
+// ============================================================================
+/**
+ * 搜索代币 (V2)
+ *
+ * 通过符号、名称或 Mint 地址搜索代币，返回详细信息。
+ *
+ * @param query 搜索查询（符号/名称/Mint地址，多个用逗号分隔）
+ * @param config Jupiter 配置
+ * @returns 代币信息列表
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 按符号搜索
+ * const results = await Sol.searchTokensV2('USDC')
+ *
+ * // 按 Mint 地址搜索
+ * const usdcInfo = await Sol.searchTokensV2(
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
+ * )
+ *
+ * // 批量搜索多个 Mint
+ * const tokens = await Sol.searchTokensV2(
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v,So11111111111111111111111111111111111111112'
+ * )
+ *
+ * tokens.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ *   console.log(`  市值: $${token.mcap?.toLocaleString()}`)
+ *   console.log(`  流动性: $${token.liquidity?.toLocaleString()}`)
+ *   console.log(`  24h变化: ${token.stats24h?.priceChange}%`)
+ * })
+ * ```
+ */
+export async function searchTokensV2(query, config) {
+    return jupGet('/tokens/v2/search', { query }, config);
+}
+/**
+ * 获取单个代币信息 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 代币信息或 null
+ */
+export async function getTokenInfoV2(mint, config) {
+    const results = await searchTokensV2(mint, config);
+    return results.length > 0 ? results[0] : null;
+}
+/**
+ * 批量获取代币信息 (V2)
+ *
+ * @param mints 代币 Mint 地址数组（最多100个）
+ * @param config Jupiter 配置
+ * @returns 代币信息列表
+ *
+ * @example
+ * ```typescript
+ * const tokens = await Sol.batchGetTokenInfoV2([
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   'So11111111111111111111111111111111111111112',  // SOL
+ *   'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT
+ * ])
+ * ```
+ */
+export async function batchGetTokenInfoV2(mints, config) {
+    if (mints.length === 0)
+        return [];
+    if (mints.length > 100) {
+        throw new Error('最多支持查询100个代币');
+    }
+    return searchTokensV2(mints.join(','), config);
+}
+// ============================================================================
+// Tag API - 按标签获取代币
+// ============================================================================
+/**
+ * 按标签获取代币列表 (V2)
+ *
+ * 获取特定标签的所有代币，返回详细信息。
+ *
+ * @param tag 标签类型 ('lst' | 'verified')
+ * @param config Jupiter 配置
+ * @returns 代币信息列表
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取所有已验证代币
+ * const verifiedTokens = await Sol.getTokensByTag('verified')
+ * console.log(`共 ${verifiedTokens.length} 个已验证代币`)
+ *
+ * // 获取所有 LST (流动性质押代币)
+ * const lstTokens = await Sol.getTokensByTag('lst')
+ * lstTokens.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ * })
+ * ```
+ */
+export async function getTokensByTag(tag, config) {
+    return jupGet('/tokens/v2/tag', { query: tag }, config);
+}
+/**
+ * 获取所有已验证代币 (V2)
+ *
+ * @param config Jupiter 配置
+ * @returns 已验证代币列表
+ *
+ * @example
+ * ```typescript
+ * const verifiedTokens = await Sol.getVerifiedTokensV2()
+ * verifiedTokens.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ * })
+ * ```
+ */
+export async function getVerifiedTokensV2(config) {
+    return getTokensByTag('verified', config);
+}
+/**
+ * 获取所有 LST (流动性质押代币) (V2)
+ *
+ * LST = Liquid Staking Tokens (如 mSOL, jitoSOL, bSOL 等)
+ *
+ * @param config Jupiter 配置
+ * @returns LST 代币列表
+ *
+ * @example
+ * ```typescript
+ * const lstTokens = await Sol.getLstTokensV2()
+ * lstTokens.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ *   console.log(`  流动性: $${token.liquidity?.toLocaleString()}`)
+ * })
+ * ```
+ */
+export async function getLstTokensV2(config) {
+    return getTokensByTag('lst', config);
+}
+// ============================================================================
+// Category API - 按分类获取热门代币
+// ============================================================================
+/**
+ * 按分类获取热门代币 (V2)
+ *
+ * 获取不同交易分类的热门代币，结果会过滤掉 SOL、USDC 等通用代币。
+ *
+ * @param category 分类类型
+ * @param interval 时间间隔
+ * @param limit 返回数量（默认50，最多100）
+ * @param config Jupiter 配置
+ * @returns 代币信息列表
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取24小时内交易量最高的代币
+ * const topTraded = await Sol.getTopTokensV2('toptraded', '24h')
+ *
+ * // 获取1小时内最热门的代币
+ * const trending = await Sol.getTopTokensV2('toptrending', '1h', 20)
+ *
+ * // 获取有机分数最高的代币
+ * const topOrganic = await Sol.getTopTokensV2('toporganicscore', '6h')
+ *
+ * topTraded.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ *   console.log(`  24h交易量: $${(token.stats24h?.buyVolume ?? 0) + (token.stats24h?.sellVolume ?? 0)}`)
+ * })
+ * ```
+ */
+export async function getTopTokensV2(category, interval, limit, config) {
+    const params = {};
+    if (limit) {
+        if (limit < 1 || limit > 100) {
+            throw new Error('limit 必须在 1-100 之间');
+        }
+        params.limit = limit;
+    }
+    return jupGet(`/tokens/v2/${category}/${interval}`, params, config);
+}
+/**
+ * 获取交易量最高的代币 (V2)
+ *
+ * @param interval 时间间隔
+ * @param limit 返回数量
+ * @param config Jupiter 配置
+ * @returns 代币列表
+ */
+export async function getTopTradedTokensV2(interval = '24h', limit, config) {
+    return getTopTokensV2('toptraded', interval, limit, config);
+}
+/**
+ * 获取最热门的代币 (V2)
+ *
+ * @param interval 时间间隔
+ * @param limit 返回数量
+ * @param config Jupiter 配置
+ * @returns 代币列表
+ */
+export async function getTrendingTokensV2(interval = '1h', limit, config) {
+    return getTopTokensV2('toptrending', interval, limit, config);
+}
+/**
+ * 获取有机分数最高的代币 (V2)
+ *
+ * @param interval 时间间隔
+ * @param limit 返回数量
+ * @param config Jupiter 配置
+ * @returns 代币列表
+ */
+export async function getTopOrganicTokensV2(interval = '24h', limit, config) {
+    return getTopTokensV2('toporganicscore', interval, limit, config);
+}
+// ============================================================================
+// Recent API - 获取最近的代币
+// ============================================================================
+/**
+ * 获取最近的代币 (V2)
+ *
+ * 获取最近创建或上市的代币列表。
+ *
+ * @param config Jupiter 配置
+ * @returns 代币信息列表
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取最近的代币
+ * const recentTokens = await Sol.getRecentTokensV2()
+ *
+ * recentTokens.forEach(token => {
+ *   console.log(`${token.symbol}: $${token.usdPrice}`)
+ *   console.log(`  创建于: ${token.firstPool?.createdAt}`)
+ *   console.log(`  发射台: ${token.launchpad || '无'}`)
+ * })
+ * ```
+ */
+export async function getRecentTokensV2(config) {
+    return jupGet('/tokens/v2/recent', {}, config);
+}
+/**
+ * 获取代币内容 (V2)
+ *
+ * 获取代币的相关内容，包括文章、推文、摘要等。
+ *
+ * @param mints 代币 Mint 地址数组（最多50个）
+ * @param config Jupiter 配置
+ * @returns 代币内容响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取代币内容
+ * const response = await Sol.getTokenContentV2([
+ *   'JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN',
+ *   'So11111111111111111111111111111111111111112',
+ * ])
+ *
+ * response.data.forEach(item => {
+ *   console.log(`代币: ${item.mint}`)
+ *
+ *   // 代币摘要
+ *   if (item.tokenSummary.summaryShort) {
+ *     console.log(`摘要: ${item.tokenSummary.summaryShort}`)
+ *   }
+ *
+ *   // 新闻摘要
+ *   if (item.newsSummary.summaryShort) {
+ *     console.log(`新闻: ${item.newsSummary.summaryShort}`)
+ *   }
+ *
+ *   // 内容列表
+ *   item.contents.forEach(content => {
+ *     console.log(`[${content.contentType}] ${content.content.slice(0, 100)}...`)
+ *   })
+ * })
+ * ```
+ */
+export async function getTokenContentV2(mints, config) {
+    if (mints.length === 0) {
+        return { data: [] };
+    }
+    if (mints.length > 50) {
+        throw new Error('最多支持查询50个代币');
+    }
+    return jupGet('/tokens/v2/content', { mints: mints.join(',') }, config);
+}
+/**
+ * 获取单个代币内容 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 代币内容数据或 null
+ */
+export async function getSingleTokenContentV2(mint, config) {
+    const response = await getTokenContentV2([mint], config);
+    return response.data.length > 0 ? response.data[0] : null;
+}
+/**
+ * 获取代币摘要 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 代币摘要或 null
+ */
+export async function getTokenSummaryV2(mint, config) {
+    const content = await getSingleTokenContentV2(mint, config);
+    if (!content)
+        return null;
+    return {
+        token: content.tokenSummary,
+        news: content.newsSummary,
+    };
+}
+/**
+ * 获取代币推文内容 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 推文内容列表
+ */
+export async function getTokenTweetsV2(mint, config) {
+    const content = await getSingleTokenContentV2(mint, config);
+    if (!content)
+        return [];
+    return content.contents.filter(c => c.contentType === 'tweet');
+}
+/**
+ * 获取代币文章内容 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 文章内容列表
+ */
+export async function getTokenArticlesV2(mint, config) {
+    const content = await getSingleTokenContentV2(mint, config);
+    if (!content)
+        return [];
+    return content.contents.filter(c => c.contentType === 'text');
+}
+/**
+ * 获取 Cooking 代币内容 (V2)
+ *
+ * 获取正在 "cooking"（酝酿中/热门）的代币内容列表。
+ *
+ * @param config Jupiter 配置
+ * @returns 代币内容响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取 cooking 代币内容
+ * const response = await Sol.getCookingTokenContentV2()
+ *
+ * response.data.forEach(item => {
+ *   console.log(`代币: ${item.mint}`)
+ *
+ *   // 代币摘要
+ *   if (item.tokenSummary?.summaryShort) {
+ *     console.log(`摘要: ${item.tokenSummary.summaryShort}`)
+ *   }
+ *
+ *   // 新闻摘要
+ *   if (item.newsSummary?.summaryShort) {
+ *     console.log(`新闻: ${item.newsSummary.summaryShort}`)
+ *   }
+ *
+ *   // 内容列表
+ *   item.contents.forEach(content => {
+ *     console.log(`[${content.contentType}] ${content.content}`)
+ *   })
+ * })
+ * ```
+ */
+export async function getCookingTokenContentV2(config) {
+    return jupGet('/tokens/v2/content/cooking', {}, config);
+}
+/**
+ * 获取代币内容 Feed (V2) - 带分页
+ *
+ * 获取单个代币的内容 feed，支持分页。
+ *
+ * @param params 请求参数
+ * @param config Jupiter 配置
+ * @returns Feed 响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取代币内容 feed
+ * const response = await Sol.getTokenContentFeedV2({
+ *   mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *   page: 1,
+ *   limit: 50,
+ * })
+ *
+ * const { data } = response
+ *
+ * // 分页信息
+ * console.log(`第 ${data.pagination.page}/${data.pagination.totalPages} 页`)
+ * console.log(`共 ${data.pagination.total} 条内容`)
+ *
+ * // 代币摘要
+ * if (data.tokenSummary?.summaryShort) {
+ *   console.log(`简介: ${data.tokenSummary.summaryShort}`)
+ * }
+ *
+ * // 新闻摘要
+ * if (data.newsSummary?.summaryShort) {
+ *   console.log(`新闻: ${data.newsSummary.summaryShort}`)
+ * }
+ *
+ * // 内容列表
+ * data.contents.forEach(content => {
+ *   console.log(`[${content.contentType}] ${content.content}`)
+ *   console.log(`  发布于: ${content.postedAt}`)
+ * })
+ * ```
+ */
+export async function getTokenContentFeedV2(params, config) {
+    const queryParams = {
+        mint: params.mint,
+    };
+    if (params.page) {
+        if (params.page < 1)
+            throw new Error('page 必须 >= 1');
+        queryParams.page = params.page;
+    }
+    if (params.limit) {
+        if (params.limit < 1 || params.limit > 100) {
+            throw new Error('limit 必须在 1-100 之间');
+        }
+        queryParams.limit = params.limit;
+    }
+    return jupGet('/tokens/v2/content/feed', queryParams, config);
+}
+/**
+ * 获取代币所有内容 (V2) - 自动分页
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 所有内容列表
+ */
+export async function getAllTokenContentFeedV2(mint, config) {
+    const allContents = [];
+    let page = 1;
+    while (true) {
+        const response = await getTokenContentFeedV2({
+            mint,
+            page,
+            limit: 100,
+        }, config);
+        allContents.push(...response.data.contents);
+        if (page >= response.data.pagination.totalPages)
+            break;
+        page++;
+    }
+    return allContents;
+}
+/**
+ * 获取代币内容 Feed 简化版 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param page 页码
+ * @param limit 每页数量
+ * @param config Jupiter 配置
+ * @returns Feed 响应
+ */
+export async function getTokenFeedV2(mint, page = 1, limit = 50, config) {
+    return getTokenContentFeedV2({ mint, page, limit }, config);
+}
+/**
+ * 检查代币是否有内容/摘要 (V2)
+ *
+ * @param contentData 代币内容数据
+ * @returns 是否有内容
+ */
+export function hasTokenContent(contentData) {
+    return (contentData.contents.length > 0 ||
+        contentData.tokenSummary !== null ||
+        contentData.newsSummary !== null);
+}
+/**
+ * 获取代币所有引用来源 (V2)
+ *
+ * @param contentData 代币内容数据
+ * @returns 去重后的引用来源列表
+ */
+export function getAllCitations(contentData) {
+    const citations = new Set();
+    contentData.tokenSummary?.citations.forEach(c => citations.add(c));
+    contentData.newsSummary?.citations.forEach(c => citations.add(c));
+    return Array.from(citations);
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 获取代币价格 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 价格 (USD) 或 null
+ */
+export async function getTokenPriceV2(mint, config) {
+    const info = await getTokenInfoV2(mint, config);
+    return info?.usdPrice ?? null;
+}
+/**
+ * 批量获取代币价格 (V2)
+ *
+ * @param mints 代币 Mint 地址数组
+ * @param config Jupiter 配置
+ * @returns Mint -> 价格 映射
+ */
+export async function batchGetTokenPricesV2(mints, config) {
+    const tokens = await batchGetTokenInfoV2(mints, config);
+    const priceMap = new Map();
+    tokens.forEach(token => {
+        priceMap.set(token.id, token.usdPrice ?? null);
+    });
+    // 设置未找到的代币为 null
+    mints.forEach(mint => {
+        if (!priceMap.has(mint)) {
+            priceMap.set(mint, null);
+        }
+    });
+    return priceMap;
+}
+/**
+ * 获取代币市场数据 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 市场数据
+ */
+export async function getTokenMarketDataV2(mint, config) {
+    const info = await getTokenInfoV2(mint, config);
+    if (!info)
+        return null;
+    const buyVolume = info.stats24h?.buyVolume ?? 0;
+    const sellVolume = info.stats24h?.sellVolume ?? 0;
+    return {
+        price: info.usdPrice ?? null,
+        fdv: info.fdv ?? null,
+        mcap: info.mcap ?? null,
+        liquidity: info.liquidity ?? null,
+        volume24h: buyVolume + sellVolume || null,
+        priceChange24h: info.stats24h?.priceChange ?? null,
+    };
+}
+/**
+ * 检查代币是否安全 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 安全检查结果
+ */
+export async function checkTokenSafetyV2(mint, config) {
+    const info = await getTokenInfoV2(mint, config);
+    if (!info)
+        return null;
+    const warnings = [];
+    const audit = info.audit ?? {};
+    // 检查风险项
+    if (audit.isSus)
+        warnings.push('代币被标记为可疑');
+    if (audit.mintAuthorityDisabled === false)
+        warnings.push('Mint权限未禁用');
+    if (audit.freezeAuthorityDisabled === false)
+        warnings.push('冻结权限未禁用');
+    if ((audit.topHoldersPercentage ?? 0) > 50)
+        warnings.push(`前几大持有者占比过高: ${audit.topHoldersPercentage}%`);
+    if ((audit.devBalancePercentage ?? 0) > 20)
+        warnings.push(`开发者持仓过高: ${audit.devBalancePercentage}%`);
+    if ((info.organicScore ?? 0) < 30)
+        warnings.push(`有机分数过低: ${info.organicScore}`);
+    const isSafe = warnings.length === 0 &&
+        (info.isVerified ?? false) &&
+        (info.organicScoreLabel === 'high');
+    return {
+        isSafe,
+        isVerified: info.isVerified ?? false,
+        isSus: audit.isSus ?? false,
+        mintAuthorityDisabled: audit.mintAuthorityDisabled ?? false,
+        freezeAuthorityDisabled: audit.freezeAuthorityDisabled ?? false,
+        topHoldersPercentage: audit.topHoldersPercentage ?? null,
+        devBalancePercentage: audit.devBalancePercentage ?? null,
+        organicScore: info.organicScore ?? 0,
+        organicScoreLabel: info.organicScoreLabel ?? 'low',
+        warnings,
+    };
+}
+/**
+ * 获取代币统计摘要 (V2)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 统计摘要
+ */
+export async function getTokenStatsSummaryV2(mint, config) {
+    const info = await getTokenInfoV2(mint, config);
+    if (!info)
+        return null;
+    const buyVolume = info.stats24h?.buyVolume ?? 0;
+    const sellVolume = info.stats24h?.sellVolume ?? 0;
+    return {
+        symbol: info.symbol,
+        price: info.usdPrice ?? null,
+        priceChange: {
+            '5m': info.stats5m?.priceChange ?? null,
+            '1h': info.stats1h?.priceChange ?? null,
+            '6h': info.stats6h?.priceChange ?? null,
+            '24h': info.stats24h?.priceChange ?? null,
+            '7d': info.stats7d?.priceChange ?? null,
+            '30d': info.stats30d?.priceChange ?? null,
+        },
+        volume24h: buyVolume + sellVolume || null,
+        liquidity: info.liquidity ?? null,
+        mcap: info.mcap ?? null,
+        holderCount: info.holderCount ?? null,
+        numTraders24h: info.stats24h?.numTraders ?? null,
+    };
+}
+/**
+ * 搜索热门代币 (按有机分数)
+ *
+ * @param query 搜索查询
+ * @param config Jupiter 配置
+ * @returns 按有机分数排序的代币列表
+ */
+export async function searchTrendingTokensV2(query, config) {
+    const tokens = await searchTokensV2(query, config);
+    return tokens.sort((a, b) => (b.organicScore ?? 0) - (a.organicScore ?? 0));
+}
+/**
+ * 筛选已验证代币
+ *
+ * @param tokens 代币列表
+ * @returns 已验证的代币
+ */
+export function filterVerifiedTokens(tokens) {
+    return tokens.filter(t => t.isVerified === true);
+}
+/**
+ * 筛选高有机分数代币
+ *
+ * @param tokens 代币列表
+ * @returns 高有机分数代币
+ */
+export function filterHighOrganicTokens(tokens) {
+    return tokens.filter(t => t.organicScoreLabel === 'high');
+}
+/**
+ * 计算代币买卖比
+ *
+ * @param stats 统计数据
+ * @returns 买卖比 (买入量/卖出量)
+ */
+export function calculateBuySellRatio(stats) {
+    const buyVol = stats.buyVolume;
+    const sellVol = stats.sellVolume;
+    if (buyVol == null || sellVol == null || sellVol === 0)
+        return null;
+    return buyVol / sellVol;
+}