four-flap-meme-sdk 1.5.55 → 1.5.56

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

@@ -0,0 +1,220 @@
+/**
+ * Jupiter Price API V3
+ * @module sol/dex/jup/price
+ *
+ * Price API 提供代币价格查询
+ * 支持批量查询，返回 USD 价格和 24h 变化
+ */
+import { jupGet } from './client.js';
+// ============================================================================
+// Price API - 价格查询
+// ============================================================================
+/**
+ * 获取代币价格 (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 async function getTokenPricesV3(ids, config) {
+    if (ids.length === 0) {
+        return {};
+    }
+    return jupGet('/price/v3', { ids: ids.join(',') }, config);
+}
+/**
+ * 获取单个代币价格 (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 async function getSingleTokenPriceV3(mint, config) {
+    const prices = await getTokenPricesV3([mint], config);
+    return prices[mint] ?? null;
+}
+/**
+ * 获取 USD 价格 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns USD 价格或 null
+ */
+export async function getUsdPrice(mint, config) {
+    const info = await getSingleTokenPriceV3(mint, config);
+    return info?.usdPrice ?? null;
+}
+/**
+ * 批量获取 USD 价格 (V3)
+ *
+ * @param mints 代币 Mint 地址数组
+ * @param config Jupiter 配置
+ * @returns Mint -> 价格 映射
+ */
+export async function batchGetUsdPrices(mints, config) {
+    const prices = await getTokenPricesV3(mints, config);
+    const priceMap = new Map();
+    mints.forEach(mint => {
+        priceMap.set(mint, prices[mint]?.usdPrice ?? null);
+    });
+    return priceMap;
+}
+/**
+ * 获取 24h 价格变化 (V3)
+ *
+ * @param mint 代币 Mint 地址
+ * @param config Jupiter 配置
+ * @returns 24h 价格变化百分比或 null
+ */
+export async function get24hPriceChange(mint, config) {
+    const info = await getSingleTokenPriceV3(mint, config);
+    return info?.priceChange24h ?? 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 async function calculateTokenValue(mint, amount, config) {
+    const info = await getSingleTokenPriceV3(mint, config);
+    if (!info)
+        return null;
+    const amountNum = typeof amount === 'bigint' ? Number(amount) : amount;
+    const adjustedAmount = amountNum / Math.pow(10, info.decimals);
+    return adjustedAmount * info.usdPrice;
+}
+/**
+ * 批量计算代币价值 (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 async function calculatePortfolioValue(holdings, config) {
+    if (holdings.length === 0) {
+        return { totalValue: 0, details: [] };
+    }
+    const mints = holdings.map(h => h.mint);
+    const prices = await getTokenPricesV3(mints, config);
+    let totalValue = 0;
+    const details = holdings.map(holding => {
+        const amountNum = typeof holding.amount === 'bigint'
+            ? Number(holding.amount)
+            : holding.amount;
+        const info = prices[holding.mint];
+        if (!info) {
+            return {
+                mint: holding.mint,
+                amount: amountNum,
+                price: null,
+                value: null,
+            };
+        }
+        const adjustedAmount = amountNum / Math.pow(10, info.decimals);
+        const value = adjustedAmount * info.usdPrice;
+        totalValue += value;
+        return {
+            mint: holding.mint,
+            amount: adjustedAmount,
+            price: info.usdPrice,
+            value,
+        };
+    });
+    return { totalValue, details };
+}
+// ============================================================================
+// 常用代币地址
+// ============================================================================
+/** 常用代币 Mint 地址 */
+export const COMMON_TOKENS = {
+    /** SOL (Wrapped) */
+    SOL: 'So11111111111111111111111111111111111111112',
+    /** USDC */
+    USDC: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+    /** USDT */
+    USDT: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
+    /** JUP */
+    JUP: 'JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN',
+    /** BONK */
+    BONK: 'DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263',
+    /** RAY */
+    RAY: '4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R',
+};
+/**
+ * 获取 SOL 价格 (V3)
+ */
+export async function getSolPrice(config) {
+    return getUsdPrice(COMMON_TOKENS.SOL, config);
+}
+/**
+ * 获取 USDC 价格 (V3)
+ */
+export async function getUsdcPrice(config) {
+    return getUsdPrice(COMMON_TOKENS.USDC, config);
+}
+/**
+ * 获取常用代币价格 (V3)
+ */
+export async function getCommonTokenPrices(config) {
+    return getTokenPricesV3(Object.values(COMMON_TOKENS), config);
+}

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

@@ -0,0 +1,437 @@
+/**
+ * Jupiter Recurring API (定投/定期订单)
+ * @module sol/dex/jup/recurring
+ *
+ * Recurring API 提供定投/DCA (Dollar Cost Averaging) 功能
+ * 用户可以创建定期自动执行的订单
+ */
+import type { JupiterConfig } from './types.js';
+/** 时间模式参数 */
+export interface RecurringTimeParams {
+    /** 每次投入数量 (最小单位) */
+    inAmount: number;
+    /** 间隔时间 (秒) */
+    interval: number;
+    /** 订单次数 */
+    numberOfOrders: number;
+    /** 最高价格限制 (可选) */
+    maxPrice?: number | null;
+    /** 最低价格限制 (可选) */
+    minPrice?: number | null;
+    /** 开始时间 (Unix 时间戳，可选) */
+    startAt?: number | null;
+}
+/** 价格模式参数 */
+export interface RecurringPriceParams {
+    /** 每次投入数量 (最小单位) */
+    inAmount: number;
+    /** 目标价格 */
+    targetPrice: number;
+    /** 订单次数 */
+    numberOfOrders: number;
+    /** 开始时间 (Unix 时间戳，可选) */
+    startAt?: number | null;
+}
+/** 订单参数 (时间模式) */
+export interface RecurringParamsTime {
+    time: RecurringTimeParams;
+}
+/** 订单参数 (价格模式) */
+export interface RecurringParamsPrice {
+    price: RecurringPriceParams;
+}
+/** 订单参数 */
+export type RecurringParams = RecurringParamsTime | RecurringParamsPrice;
+/** 创建订单请求参数 */
+export interface RecurringCreateOrderParams {
+    /** 用户地址 */
+    user: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 订单参数 */
+    params: RecurringParams;
+}
+/** 创建订单响应 */
+export interface RecurringCreateOrderResponse {
+    /** 请求 ID (用于 /execute) */
+    requestId: string;
+    /** Base64 编码的未签名交易 */
+    transaction: string;
+}
+/** 定投类型 */
+export type RecurringType = 'time' | 'price' | 'all';
+/** 取消订单请求参数 */
+export interface RecurringCancelOrderParams {
+    /** 用户地址 */
+    user: string;
+    /** 订单账户地址 */
+    order: string;
+    /** 定投类型 */
+    recurringType: RecurringType;
+}
+/** 取消订单响应 */
+export interface RecurringCancelOrderResponse {
+    /** 请求 ID */
+    requestId: string;
+    /** Base64 编码的未签名交易 */
+    transaction: string;
+}
+/** 执行交易请求参数 */
+export interface RecurringExecuteParams {
+    /** 请求 ID */
+    requestId: string;
+    /** 已签名的交易 (Base64) */
+    signedTransaction: string;
+}
+/** 执行状态 */
+export type RecurringExecuteStatus = 'Success' | 'Failed';
+/** 执行交易响应 */
+export interface RecurringExecuteResponse {
+    /** 交易签名 */
+    signature: string;
+    /** 执行状态 */
+    status: RecurringExecuteStatus;
+    /** 错误信息 (失败时) */
+    error?: string;
+    /** 订单账户地址 */
+    order?: string;
+}
+/** 订单列表状态 */
+export type RecurringOrderListStatus = 'active' | 'history';
+/** 交易记录 */
+export interface RecurringTrade {
+    /** 订单账户地址 */
+    orderKey: string;
+    /** Keeper 地址 */
+    keeper: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 输入数量 (UI) */
+    inputAmount: string;
+    /** 输出数量 (UI) */
+    outputAmount: string;
+    /** 原始输入数量 */
+    rawInputAmount: string;
+    /** 原始输出数量 */
+    rawOutputAmount: string;
+    /** 手续费代币 Mint */
+    feeMint: string;
+    /** 手续费数量 (UI) */
+    feeAmount: string;
+    /** 原始手续费数量 */
+    rawFeeAmount: string;
+    /** 交易签名 */
+    txId: string;
+    /** 确认时间 */
+    confirmedAt: string;
+    /** 操作类型 */
+    action: string;
+    /** 产品元数据 */
+    productMeta?: unknown;
+}
+/** 时间模式订单详情 */
+export interface RecurringTimeOrder {
+    /** 订单账户地址 */
+    orderKey: string;
+    /** 用户地址 */
+    userPubkey: string;
+    /** 输入代币 Mint */
+    inputMint: string;
+    /** 输出代币 Mint */
+    outputMint: string;
+    /** 周期频率 */
+    cycleFrequency: string;
+    /** 每周期投入数量 (UI) */
+    inAmountPerCycle: string;
+    /** 原始每周期投入数量 */
+    rawInAmountPerCycle: string;
+    /** 已存入数量 (UI) */
+    inDeposited: string;
+    /** 原始已存入数量 */
+    rawInDeposited: string;
+    /** 已使用数量 (UI) */
+    inUsed: string;
+    /** 原始已使用数量 */
+    rawInUsed: string;
+    /** 已提取输入数量 (UI) */
+    inWithdrawn: string;
+    /** 原始已提取输入数量 */
+    rawInWithdrawn: string;
+    /** 已收到输出数量 (UI) */
+    outReceived: string;
+    /** 原始已收到输出数量 */
+    rawOutReceived: string;
+    /** 已提取输出数量 (UI) */
+    outWithdrawn: string;
+    /** 原始已提取输出数量 */
+    rawOutWithdrawn: string;
+    /** 最大输出数量 (UI) */
+    maxOutAmount: string;
+    /** 原始最大输出数量 */
+    rawMaxOutAmount: string;
+    /** 最小输出数量 (UI) */
+    minOutAmount: string;
+    /** 原始最小输出数量 */
+    rawMinOutAmount: string;
+    /** 开单交易签名 */
+    openTx: string;
+    /** 关单交易签名 */
+    closeTx: string;
+    /** 用户是否已关闭 */
+    userClosed: boolean;
+    /** 创建时间 */
+    createdAt: string;
+    /** 更新时间 */
+    updatedAt: string;
+    /** 交易记录 */
+    trades: RecurringTrade[];
+}
+/** 获取订单请求参数 */
+export interface RecurringGetOrdersParams {
+    /** 用户地址 */
+    user: string;
+    /** 定投类型 */
+    recurringType: RecurringType;
+    /** 订单状态 */
+    orderStatus: RecurringOrderListStatus;
+    /** 页码 (默认: 1) */
+    page?: number;
+    /** 代币 Mint 筛选 */
+    mint?: string;
+    /** 是否包含失败交易 */
+    includeFailedTx?: boolean;
+}
+/** 获取订单响应 */
+export interface RecurringGetOrdersResponse {
+    /** 用户地址 */
+    user: string;
+    /** 订单状态 */
+    orderStatus: RecurringOrderListStatus;
+    /** 当前页 */
+    page: number;
+    /** 总页数 */
+    totalPages: number;
+    /** 时间模式订单列表 */
+    time?: RecurringTimeOrder[];
+}
+/**
+ * 创建定投订单（时间模式）
+ *
+ * 按固定时间间隔自动执行的定投订单。
+ *
+ * @param params 创建订单参数
+ * @param config Jupiter 配置
+ * @returns 创建订单响应
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ *
+ * Sol.setJupiterConfig({ apiKey: 'your-api-key' })
+ *
+ * // 创建定投：每天用 1 SOL 买入 USDC，共10天
+ * const result = await Sol.createRecurringOrder({
+ *   user: wallet.publicKey.toBase58(),
+ *   inputMint: 'So11111111111111111111111111111111111111112',  // SOL
+ *   outputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   params: {
+ *     time: {
+ *       inAmount: 1_000_000_000,  // 1 SOL
+ *       numberOfOrders: 10,       // 10次
+ *       interval: 86400,          // 每天 (86400秒)
+ *     }
+ *   }
+ * })
+ *
+ * // 签名并执行
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ *
+ * await Sol.executeRecurringOrder({
+ *   requestId: result.requestId,
+ *   signedTransaction: Buffer.from(tx.serialize()).toString('base64'),
+ * })
+ * ```
+ */
+export declare function createRecurringOrder(params: RecurringCreateOrderParams, config?: JupiterConfig): Promise<RecurringCreateOrderResponse>;
+/**
+ * 创建简单定投订单（时间模式）
+ *
+ * @param user 用户地址
+ * @param inputMint 输入代币 Mint
+ * @param outputMint 输出代币 Mint
+ * @param inAmount 每次投入数量 (最小单位)
+ * @param numberOfOrders 订单次数
+ * @param intervalSeconds 间隔时间 (秒)
+ * @param options 可选参数
+ * @param config Jupiter 配置
+ * @returns 创建订单响应
+ *
+ * @example
+ * ```typescript
+ * // 每天定投 1 SOL 买 USDC，共30天
+ * const result = await Sol.createSimpleRecurringOrder(
+ *   wallet.publicKey.toBase58(),
+ *   'So11111111111111111111111111111111111111112',  // SOL
+ *   'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+ *   1_000_000_000,  // 1 SOL
+ *   30,             // 30次
+ *   86400,          // 每天
+ * )
+ * ```
+ */
+export declare function createSimpleRecurringOrder(user: string, inputMint: string, outputMint: string, inAmount: number, numberOfOrders: number, intervalSeconds: number, options?: {
+    maxPrice?: number;
+    minPrice?: number;
+    startAt?: number;
+}, config?: JupiterConfig): Promise<RecurringCreateOrderResponse>;
+/** 预设时间间隔 (秒) */
+export declare const RECURRING_INTERVALS: {
+    /** 每分钟 */
+    readonly MINUTE: 60;
+    /** 每小时 */
+    readonly HOUR: 3600;
+    /** 每天 */
+    readonly DAY: 86400;
+    /** 每周 */
+    readonly WEEK: 604800;
+    /** 每月 (30天) */
+    readonly MONTH: 2592000;
+};
+/**
+ * 创建每日定投
+ */
+export declare function createDailyRecurring(user: string, inputMint: string, outputMint: string, inAmount: number, days: number, config?: JupiterConfig): Promise<RecurringCreateOrderResponse>;
+/**
+ * 创建每周定投
+ */
+export declare function createWeeklyRecurring(user: string, inputMint: string, outputMint: string, inAmount: number, weeks: number, config?: JupiterConfig): Promise<RecurringCreateOrderResponse>;
+/**
+ * 取消定投订单
+ *
+ * @param params 取消参数
+ * @param config Jupiter 配置
+ * @returns 取消订单响应
+ *
+ * @example
+ * ```typescript
+ * const result = await Sol.cancelRecurringOrder({
+ *   user: wallet.publicKey.toBase58(),
+ *   order: 'orderAccountAddress',
+ *   recurringType: 'time',
+ * })
+ *
+ * // 签名并执行
+ * const tx = VersionedTransaction.deserialize(
+ *   Buffer.from(result.transaction, 'base64')
+ * )
+ * tx.sign([wallet])
+ *
+ * await Sol.executeRecurringOrder({
+ *   requestId: result.requestId,
+ *   signedTransaction: Buffer.from(tx.serialize()).toString('base64'),
+ * })
+ * ```
+ */
+export declare function cancelRecurringOrder(params: RecurringCancelOrderParams, config?: JupiterConfig): Promise<RecurringCancelOrderResponse>;
+/**
+ * 快捷取消时间模式定投订单
+ *
+ * @param user 用户地址
+ * @param order 订单账户地址
+ * @param config Jupiter 配置
+ * @returns 取消订单响应
+ */
+export declare function cancelTimeRecurringOrder(user: string, order: string, config?: JupiterConfig): Promise<RecurringCancelOrderResponse>;
+/**
+ * 执行已签名的定投订单交易
+ *
+ * @param params 执行参数
+ * @param config Jupiter 配置
+ * @returns 执行结果
+ */
+export declare function executeRecurringOrder(params: RecurringExecuteParams, config?: JupiterConfig): Promise<RecurringExecuteResponse>;
+/**
+ * 获取用户的定投订单
+ *
+ * @param params 查询参数
+ * @param config Jupiter 配置
+ * @returns 订单列表响应（含分页）
+ *
+ * @example
+ * ```typescript
+ * const response = await Sol.getRecurringOrders({
+ *   user: wallet.publicKey.toBase58(),
+ *   recurringType: 'time',
+ *   orderStatus: 'active',
+ *   page: 1,
+ * })
+ *
+ * console.log(`共 ${response.totalPages} 页`)
+ * response.time?.forEach(order => {
+ *   console.log(`订单: ${order.orderKey}`)
+ *   console.log(`  每周期: ${order.inAmountPerCycle}`)
+ *   console.log(`  已用: ${order.inUsed}`)
+ *   console.log(`  已收: ${order.outReceived}`)
+ *   console.log(`  交易数: ${order.trades.length}`)
+ * })
+ * ```
+ */
+export declare function getRecurringOrders(params: RecurringGetOrdersParams, config?: JupiterConfig): Promise<RecurringGetOrdersResponse>;
+/**
+ * 获取用户的活跃时间模式定投订单
+ *
+ * @param user 用户地址
+ * @param page 页码
+ * @param config Jupiter 配置
+ * @returns 订单列表响应
+ */
+export declare function getActiveTimeRecurringOrders(user: string, page?: number, config?: JupiterConfig): Promise<RecurringGetOrdersResponse>;
+/**
+ * 获取用户的历史时间模式定投订单
+ *
+ * @param user 用户地址
+ * @param page 页码
+ * @param config Jupiter 配置
+ * @returns 订单列表响应
+ */
+export declare function getHistoryTimeRecurringOrders(user: string, page?: number, config?: JupiterConfig): Promise<RecurringGetOrdersResponse>;
+/**
+ * 获取所有活跃时间模式定投订单（自动分页）
+ *
+ * @param user 用户地址
+ * @param config Jupiter 配置
+ * @returns 所有活跃订单
+ */
+export declare function getAllActiveTimeRecurringOrders(user: string, config?: JupiterConfig): Promise<RecurringTimeOrder[]>;
+/**
+ * 计算定投总投入
+ *
+ * @param inAmount 每次投入数量
+ * @param numberOfOrders 订单次数
+ * @returns 总投入数量
+ */
+export declare function calculateTotalInvestment(inAmount: number, numberOfOrders: number): number;
+/**
+ * 计算定投周期
+ *
+ * @param intervalSeconds 间隔时间 (秒)
+ * @param numberOfOrders 订单次数
+ * @returns 总持续时间 (秒)
+ */
+export declare function calculateTotalDuration(intervalSeconds: number, numberOfOrders: number): number;
+/**
+ * 估算定投结束时间
+ *
+ * @param intervalSeconds 间隔时间 (秒)
+ * @param numberOfOrders 订单次数
+ * @param startAt 开始时间 (Unix 时间戳，默认为当前时间)
+ * @returns 结束时间 (Date)
+ */
+export declare function estimateEndDate(intervalSeconds: number, numberOfOrders: number, startAt?: number): Date;