four-flap-meme-sdk 1.4.87 → 1.4.89

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

@@ -0,0 +1,367 @@
+/**
+ * Jupiter Portfolio API V1
+ * @module sol/dex/jup/portfolio
+ *
+ * Portfolio API 提供钱包投资组合/持仓查询
+ * 包括各平台的 DeFi 头寸、代币持仓等
+ */
+import { jupGet } from './client.js';
+// ============================================================================
+// Portfolio API - 投资组合查询
+// ============================================================================
+/**
+ * 获取钱包投资组合 (V1)
+ *
+ * 查询钱包在各 DeFi 平台的持仓情况。
+ *
+ * @param params 查询参数
+ * @param config Jupiter 配置
+ * @returns 投资组合响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 获取钱包投资组合
+ * const portfolio = await Sol.getPortfolio({
+ *   address: 'YourWalletAddress...',
+ * })
+ *
+ * console.log(`钱包: ${portfolio.owner}`)
+ * console.log(`查询时间: ${new Date(portfolio.date * 1000)}`)
+ * console.log(`耗时: ${portfolio.duration}ms`)
+ *
+ * // 遍历投资组合元素
+ * portfolio.elements.forEach(element => {
+ *   console.log(`[${element.platformId}] ${element.label}`)
+ *   console.log(`  类型: ${element.type}`)
+ *   console.log(`  价值: $${element.value}`)
+ * })
+ *
+ * // 按平台筛选
+ * const raydiumOnly = await Sol.getPortfolio({
+ *   address: 'YourWalletAddress...',
+ *   platforms: 'raydium',
+ * })
+ * ```
+ */
+export async function getPortfolio(params, config) {
+    const queryParams = {};
+    if (params.platforms) {
+        queryParams.platforms = params.platforms;
+    }
+    return jupGet(`/portfolio/v1/positions/${params.address}`, queryParams, config);
+}
+/**
+ * 获取钱包投资组合（简化版）
+ *
+ * @param address 钱包地址
+ * @param platforms 平台 ID 数组（可选）
+ * @param config Jupiter 配置
+ * @returns 投资组合响应
+ */
+export async function getWalletPortfolio(address, platforms, config) {
+    return getPortfolio({
+        address,
+        platforms: platforms?.join(','),
+    }, config);
+}
+// ============================================================================
+// Staked JUP API - JUP 质押查询
+// ============================================================================
+/**
+ * 获取 JUP 质押信息
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns JUP 质押信息
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * const staked = await Sol.getStakedJup('YourWalletAddress...')
+ *
+ * console.log(`已质押: ${staked.stakedAmount} JUP`)
+ *
+ * if (staked.unstaking.length > 0) {
+ *   console.log('解锁中:')
+ *   staked.unstaking.forEach(u => {
+ *     const unlockDate = new Date(u.until * 1000)
+ *     console.log(`  ${u.amount} JUP - ${unlockDate.toLocaleString()}`)
+ *   })
+ * }
+ * ```
+ */
+export async function getStakedJup(address, config) {
+    return jupGet(`/portfolio/v1/staked-jup/${address}`, {}, config);
+}
+/**
+ * 获取 JUP 质押总量
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 已质押的 JUP 数量
+ */
+export async function getStakedJupAmount(address, config) {
+    const info = await getStakedJup(address, config);
+    return info.stakedAmount;
+}
+/**
+ * 获取解锁中的 JUP 总量
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 解锁中的 JUP 总量
+ */
+export async function getUnstakingJupAmount(address, config) {
+    const info = await getStakedJup(address, config);
+    return info.unstaking.reduce((sum, u) => sum + u.amount, 0);
+}
+/**
+ * 检查是否有即将解锁的 JUP
+ *
+ * @param address 钱包地址
+ * @param withinHours 在多少小时内（默认 24）
+ * @param config Jupiter 配置
+ * @returns 即将解锁的列表
+ */
+export async function getUpcomingUnlocks(address, withinHours = 24, config) {
+    const info = await getStakedJup(address, config);
+    const now = Math.floor(Date.now() / 1000);
+    const cutoff = now + (withinHours * 3600);
+    return info.unstaking.filter(u => u.until <= cutoff && u.until > now);
+}
+// ============================================================================
+// Platforms API - 平台列表
+// ============================================================================
+/**
+ * 获取所有平台列表
+ *
+ * @param config Jupiter 配置
+ * @returns 平台信息列表
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * const platforms = await Sol.getPlatforms()
+ *
+ * platforms.forEach(p => {
+ *   console.log(`[${p.id}] ${p.name}`)
+ *   console.log(`  ${p.description}`)
+ *   console.log(`  标签: ${p.tags.join(', ')}`)
+ *   if (p.links.website) {
+ *     console.log(`  网站: ${p.links.website}`)
+ *   }
+ * })
+ * ```
+ */
+export async function getPlatforms(config) {
+    return jupGet('/portfolio/v1/platforms', {}, config);
+}
+/**
+ * 获取平台 ID 列表
+ *
+ * @param config Jupiter 配置
+ * @returns 平台 ID 数组
+ */
+export async function getPlatformIds(config) {
+    const platforms = await getPlatforms(config);
+    return platforms.map(p => p.id);
+}
+/**
+ * 获取活跃平台列表（非弃用）
+ *
+ * @param config Jupiter 配置
+ * @returns 活跃平台列表
+ */
+export async function getActivePlatforms(config) {
+    const platforms = await getPlatforms(config);
+    return platforms.filter(p => !p.isDeprecated);
+}
+/**
+ * 按标签筛选平台
+ *
+ * @param tag 标签
+ * @param config Jupiter 配置
+ * @returns 匹配的平台列表
+ */
+export async function getPlatformsByTag(tag, config) {
+    const platforms = await getPlatforms(config);
+    return platforms.filter(p => p.tags.includes(tag));
+}
+/**
+ * 搜索平台
+ *
+ * @param keyword 关键词（搜索名称和描述）
+ * @param config Jupiter 配置
+ * @returns 匹配的平台列表
+ */
+export async function searchPlatforms(keyword, config) {
+    const platforms = await getPlatforms(config);
+    const lowerKeyword = keyword.toLowerCase();
+    return platforms.filter(p => p.name.toLowerCase().includes(lowerKeyword) ||
+        p.description.toLowerCase().includes(lowerKeyword) ||
+        p.id.toLowerCase().includes(lowerKeyword));
+}
+/**
+ * 获取平台详情
+ *
+ * @param platformId 平台 ID
+ * @param config Jupiter 配置
+ * @returns 平台信息或 null
+ */
+export async function getPlatformById(platformId, config) {
+    const platforms = await getPlatforms(config);
+    return platforms.find(p => p.id === platformId) ?? null;
+}
+// ============================================================================
+// 便捷方法
+// ============================================================================
+/**
+ * 获取投资组合总价值
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 总价值 (USD)
+ */
+export async function getPortfolioTotalValue(address, config) {
+    const portfolio = await getWalletPortfolio(address, undefined, config);
+    return portfolio.elements.reduce((sum, el) => sum + el.value, 0);
+}
+/**
+ * 获取按平台分组的投资组合
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 平台 -> 元素列表 映射
+ */
+export async function getPortfolioByPlatform(address, config) {
+    const portfolio = await getWalletPortfolio(address, undefined, config);
+    const platformMap = new Map();
+    portfolio.elements.forEach(element => {
+        const existing = platformMap.get(element.platformId) || [];
+        existing.push(element);
+        platformMap.set(element.platformId, existing);
+    });
+    return platformMap;
+}
+/**
+ * 获取按类型分组的投资组合
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 类型 -> 元素列表 映射
+ */
+export async function getPortfolioByType(address, config) {
+    const portfolio = await getWalletPortfolio(address, undefined, config);
+    const typeMap = new Map();
+    portfolio.elements.forEach(element => {
+        const existing = typeMap.get(element.type) || [];
+        existing.push(element);
+        typeMap.set(element.type, existing);
+    });
+    return typeMap;
+}
+/**
+ * 获取平台价值汇总
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 平台 -> 总价值 映射
+ */
+export async function getPlatformValueSummary(address, config) {
+    const platformElements = await getPortfolioByPlatform(address, config);
+    const summaryMap = new Map();
+    platformElements.forEach((elements, platformId) => {
+        const totalValue = elements.reduce((sum, el) => sum + el.value, 0);
+        summaryMap.set(platformId, totalValue);
+    });
+    return summaryMap;
+}
+/**
+ * 获取投资组合摘要
+ *
+ * @param address 钱包地址
+ * @param config Jupiter 配置
+ * @returns 投资组合摘要
+ */
+export async function getPortfolioSummary(address, config) {
+    const portfolio = await getWalletPortfolio(address, undefined, config);
+    // 按平台汇总
+    const platformMap = new Map();
+    portfolio.elements.forEach(element => {
+        const existing = platformMap.get(element.platformId) || { value: 0, count: 0 };
+        existing.value += element.value;
+        existing.count += 1;
+        platformMap.set(element.platformId, existing);
+    });
+    const platforms = Array.from(platformMap.entries())
+        .map(([id, data]) => ({ id, ...data }))
+        .sort((a, b) => b.value - a.value);
+    return {
+        owner: portfolio.owner,
+        totalValue: portfolio.elements.reduce((sum, el) => sum + el.value, 0),
+        platformCount: platformMap.size,
+        elementCount: portfolio.elements.length,
+        platforms,
+        fetchDuration: portfolio.duration,
+    };
+}
+/**
+ * 筛选特定平台的元素
+ *
+ * @param elements 元素列表
+ * @param platformId 平台 ID
+ * @returns 筛选后的元素
+ */
+export function filterByPlatform(elements, platformId) {
+    return elements.filter(el => el.platformId === platformId);
+}
+/**
+ * 筛选特定类型的元素
+ *
+ * @param elements 元素列表
+ * @param type 类型
+ * @returns 筛选后的元素
+ */
+export function filterByType(elements, type) {
+    return elements.filter(el => el.type === type);
+}
+/**
+ * 筛选价值大于阈值的元素
+ *
+ * @param elements 元素列表
+ * @param minValue 最小价值 (USD)
+ * @returns 筛选后的元素
+ */
+export function filterByMinValue(elements, minValue) {
+    return elements.filter(el => el.value >= minValue);
+}
+/**
+ * 按价值排序元素
+ *
+ * @param elements 元素列表
+ * @param descending 是否降序（默认 true）
+ * @returns 排序后的元素
+ */
+export function sortByValue(elements, descending = true) {
+    return [...elements].sort((a, b) => descending ? b.value - a.value : a.value - b.value);
+}
+/**
+ * 获取前 N 个高价值元素
+ *
+ * @param elements 元素列表
+ * @param n 数量
+ * @returns 前 N 个元素
+ */
+export function getTopElements(elements, n) {
+    return sortByValue(elements).slice(0, n);
+}

package/dist/sol/dex/jup/price.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Jupiter Price API V3
+ * @module sol/dex/jup/price
+ *
+ * Price API 提供代币价格查询
+ * 支持批量查询，返回 USD 价格和 24h 变化
+ */
+import type { JupiterConfig } from './types.js';
+/** 单个代币价格信息 */
+export interface TokenPriceInfo {
+    /** 小数位数 */
+    decimals: number;
+    /** USD 价格 */
+    usdPrice: number;
+    /** 区块 ID */
+    blockId?: number | null;
+    /** 24小时价格变化百分比 */
+    priceChange24h?: number | null;
+}
+/** 价格响应 (key 为代币 Mint 地址) */
+export type PriceResponse = Record<string, TokenPriceInfo>;
+/**
+ * 获取代币价格 (V3)
+ *
+ * 批量查询代币的 USD 价格。
+ *
+ * @param ids 代币 Mint 地址数组
+ * @param config Jupiter 配置
+ * @returns 价格响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 批量获取价格
+ * const prices = await Sol.getTokenPricesV3([
+ *   'So11111111111111111111111111111111111111112',  // SOL
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB', // USDT
+ * ])
+ *
+ * Object.entries(prices).forEach(([mint, info]) => {
+ *   console.log(`${mint}:`)
+ *   console.log(`  价格: $${info.usdPrice}`)
+ *   console.log(`  24h变化: ${info.priceChange24h ?? 0}%`)
+ * })
+ * ```
+ */
+export declare function getTokenPricesV3(ids: string[], config?: JupiterConfig): Promise<PriceResponse>;
+/**
+ * 获取单个代币价格 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 价格信息或 null
+ *
+ * @example
+ * ```typescript
+ * const solPrice = await Sol.getSingleTokenPriceV3(
+ *   'So11111111111111111111111111111111111111112'
+ * )
+ *
+ * if (solPrice) {
+ *   console.log(`SOL: $${solPrice.usdPrice}`)
+ *   console.log(`24h: ${solPrice.priceChange24h}%`)
+ * }
+ * ```
+ */
+export declare function getSingleTokenPriceV3(mint: string, config?: JupiterConfig): Promise<TokenPriceInfo | null>;
+/**
+ * 获取 USD 价格 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns USD 价格或 null
+ */
+export declare function getUsdPrice(mint: string, config?: JupiterConfig): Promise<number | null>;
+/**
+ * 批量获取 USD 价格 (V3)
+ *
+ * @param mints 代币 Mint 地址数组
+ * @param config Jupiter 配置
+ * @returns Mint -> 价格 映射
+ */
+export declare function batchGetUsdPrices(mints: string[], config?: JupiterConfig): Promise<Map<string, number | null>>;
+/**
+ * 获取 24h 价格变化 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 24h 价格变化百分比或 null
+ */
+export declare function get24hPriceChange(mint: string, config?: JupiterConfig): Promise<number | null>;
+/**
+ * 计算代币价值 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param amount 代币数量 (最小单位)
+ * @param config Jupiter 配置
+ * @returns USD 价值或 null
+ *
+ * @example
+ * ```typescript
+ * // 计算 1 SOL 的 USD 价值
+ * const value = await Sol.calculateTokenValue(
+ *   'So11111111111111111111111111111111111111112',
+ *   1_000_000_000, // 1 SOL = 10^9 lamports
+ * )
+ * console.log(`1 SOL = $${value}`)
+ * ```
+ */
+export declare function calculateTokenValue(mint: string, amount: number | bigint, config?: JupiterConfig): Promise<number | null>;
+/**
+ * 批量计算代币价值 (V3)
+ *
+ * @param holdings 持仓数组 [{mint, amount}]
+ * @param config Jupiter 配置
+ * @returns 总 USD 价值和明细
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.calculatePortfolioValue([
+ *   { mint: 'So11111111111111111111111111111111111111112', amount: 1_000_000_000 },
+ *   { mint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', amount: 100_000_000 },
+ * ])
+ *
+ * console.log(`总价值: $${result.totalValue}`)
+ * result.details.forEach(d => {
+ *   console.log(`  ${d.mint}: $${d.value}`)
+ * })
+ * ```
+ */
+export declare function calculatePortfolioValue(holdings: Array<{
+    mint: string;
+    amount: number | bigint;
+}>, config?: JupiterConfig): Promise<{
+    totalValue: number;
+    details: Array<{
+        mint: string;
+        amount: number;
+        price: number | null;
+        value: number | null;
+    }>;
+}>;
+/** 常用代币 Mint 地址 */
+export declare const COMMON_TOKENS: {
+    /** SOL (Wrapped) */
+    readonly SOL: "So11111111111111111111111111111111111111112";
+    /** USDC */
+    readonly USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+    /** USDT */
+    readonly USDT: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB";
+    /** JUP */
+    readonly JUP: "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN";
+    /** BONK */
+    readonly BONK: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263";
+    /** RAY */
+    readonly RAY: "4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R";
+};
+/**
+ * 获取 SOL 价格 (V3)
+ */
+export declare function getSolPrice(config?: JupiterConfig): Promise<number | null>;
+/**
+ * 获取 USDC 价格 (V3)
+ */
+export declare function getUsdcPrice(config?: JupiterConfig): Promise<number | null>;
+/**
+ * 获取常用代币价格 (V3)
+ */
+export declare function getCommonTokenPrices(config?: JupiterConfig): Promise<PriceResponse>;