crypull 1.0.2 → 1.0.3

package/dist/index.d.mts

@@ -103,8 +103,10 @@ interface SearchResult {
 }
 interface ICryptoProvider {
     name: string;
-    getPrice(symbol: string): Promise<PriceData | null>;
-    getTokenInfo(address: string, network?: string): Promise<TokenInfo | null>;
+    /** True for DEX providers that resolve contract addresses, not ticker symbols. */
+    addressBased?: boolean;
+    getPrice(query: string, network?: string): Promise<PriceData | null>;
+    getTokenInfo(query: string, network?: string): Promise<TokenInfo | null>;
     search(query: string): Promise<SearchResult[]>;
 }
 
@@ -113,28 +115,23 @@ interface CrypullOptions {
 }
 declare class Crypull {
     providers: ICryptoProvider[];
-    private coinGecko;
-    private dexScreener;
-    private geckoTerminal;
-    private binance;
-    private coinpaprika;
-    private coincap;
-    private cryptoCompare;
     constructor(options?: CrypullOptions);
-    private isAddress;
+    private symbolProviders;
+    private addressProviders;
+    private coinGecko;
     /**
-     * Search for a token or coin across multiple providers in parallel
+     * Search for a token or coin across symbol + DEX providers in parallel.
      */
     search(query: string): Promise<SearchResult[]>;
     /**
-     * Get the current price of a cryptocurrency
-     * @param query Can be a symbol (e.g., 'BTC') or a contract address
-     * @param network Optional network for DEX addresses (e.g., 'eth', 'bsc')
+     * Get the current price of a cryptocurrency.
+     * @param query Symbol (e.g. 'BTC') or contract address
+     * @param network Optional network for DEX addresses (e.g. 'eth', 'bsc', 'solana')
      */
     price(query: string, network?: string): Promise<PriceData | null>;
     /**
      * Get detailed token info (market cap, volume, liquidity, etc.)
-     * @param query Can be a symbol (e.g., 'BTC') or a contract address
+     * @param query Symbol (e.g. 'BTC') or contract address
      * @param network Optional network for DEX addresses
      */
     info(query: string, network?: string): Promise<TokenInfo | null>;
@@ -160,22 +157,53 @@ declare class Crypull {
     gas(): Promise<GasData | null>;
     /**
      * Get historical chart data for a coin
-     * @param query Coin symbol or ID
+     * @param query Coin symbol or CoinGecko ID
      * @param days Number of days (e.g. 1, 7, 30)
      */
     chart(query: string, days?: number): Promise<ChartData | null>;
 }
 
+/**
+ * Detect contract addresses (EVM / Solana-style) vs ticker symbols.
+ */
+declare function isContractAddress(query: string): boolean;
+/**
+ * Normalize to a Binance USD quote pair (library prices are always USD-oriented).
+ * e.g. BTC → BTCUSDT, WBTC → WBTCUSDT, ETHUSDT → ETHUSDT
+ */
+declare function toBinancePair(symbol: string): string;
+/**
+ * Strip a Binance USD quote suffix back to the base asset symbol.
+ */
+declare function fromBinancePair(pair: string): string;
+/**
+ * Default GeckoTerminal network for an address when none is provided.
+ */
+declare function defaultDexNetwork(address: string): string;
+/** Parse a number; return undefined for NaN/non-finite (preserves 0). */
+declare function finiteOrUndefined(value: unknown): number | undefined;
+
 declare class CoinGeckoProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
+    /** Resolve a symbol or slug to a CoinGecko coin id. */
+    resolveId(symbolOrId: string): Promise<{
+        id: string;
+        symbol: string;
+    } | null>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
-    getTokenInfo(id: string): Promise<TokenInfo | null>;
+    getTokenInfo(symbolOrId: string): Promise<TokenInfo | null>;
+    getGlobalMarket(): Promise<GlobalMarketData | null>;
+    getTrending(): Promise<TrendingCoin[]>;
+    getTop(limit?: number): Promise<TopCoin[]>;
+    getChart(query: string, days?: number): Promise<ChartData | null>;
 }
 
 declare class DexScreenerProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(address: string): Promise<PriceData | null>;
@@ -184,6 +212,7 @@ declare class DexScreenerProvider implements ICryptoProvider {
 
 declare class GeckoTerminalProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(address: string, network?: string): Promise<PriceData | null>;
@@ -192,6 +221,7 @@ declare class GeckoTerminalProvider implements ICryptoProvider {
 
 declare class BinanceProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbol: string): Promise<PriceData | null>;
@@ -200,6 +230,7 @@ declare class BinanceProvider implements ICryptoProvider {
 
 declare class CoinpaprikaProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
@@ -208,6 +239,7 @@ declare class CoinpaprikaProvider implements ICryptoProvider {
 
 declare class CoinCapProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
@@ -216,12 +248,116 @@ declare class CoinCapProvider implements ICryptoProvider {
 
 declare class CryptoCompareProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(_query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * CoinMarketCap keyless public API (no API key required).
+ * https://pro-api.coinmarketcap.com/public-api
+ */
+declare class CoinMarketCapProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private headers;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbolOrSlug: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * CoinLore free public API (no API key).
+ * https://api.coinlore.net/api/
+ */
+declare class CoinLoreProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    /** Scan top tickers pages to resolve symbol → coin id. */
+    private findTicker;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbolOrId: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Coinbase public spot price API (no API key).
+ * https://api.coinbase.com/v2/
+ */
+declare class CoinbaseProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Kraken public ticker API (no API key).
+ * https://api.kraken.com/0/public/
+ *
+ * Note: Kraken uses XBT for Bitcoin.
+ */
+declare class KrakenProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private toPair;
+    private fromPairKey;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * KuCoin public market API (no API key).
+ * https://api.kucoin.com/api/v1/
+ */
+declare class KuCoinProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private toSymbol;
+    private baseAsset;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Bybit public spot ticker API (no API key).
+ * https://api.bybit.com/v5/market/
+ */
+declare class BybitProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Gate.io public spot API (no API key).
+ * https://api.gateio.ws/api/v4/
+ */
+declare class GateIoProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
     private baseUrl;
+    private toPair;
+    private baseAsset;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbol: string): Promise<PriceData | null>;
     getTokenInfo(symbol: string): Promise<TokenInfo | null>;
 }
 
+/** Default shared instance for quick usage */
 declare const crypull: Crypull;
 
-export { BinanceProvider, type ChartData, CoinCapProvider, CoinGeckoProvider, CoinpaprikaProvider, CryptoCompareProvider, Crypull, type CrypullOptions, type DexPairInfo, DexScreenerProvider, type GasData, GeckoTerminalProvider, type GlobalMarketData, type ICryptoProvider, type PriceData, type SearchResult, type SentimentData, type TokenInfo, type TokenLinks, type TopCoin, type TrendingCoin, crypull };
+export { BinanceProvider, BybitProvider, type ChartData, CoinCapProvider, CoinGeckoProvider, CoinLoreProvider, CoinMarketCapProvider, CoinbaseProvider, CoinpaprikaProvider, CryptoCompareProvider, Crypull, type CrypullOptions, type DexPairInfo, DexScreenerProvider, type GasData, GateIoProvider, GeckoTerminalProvider, type GlobalMarketData, type ICryptoProvider, KrakenProvider, KuCoinProvider, type PriceData, type SearchResult, type SentimentData, type TokenInfo, type TokenLinks, type TopCoin, type TrendingCoin, crypull, defaultDexNetwork, finiteOrUndefined, fromBinancePair, isContractAddress, toBinancePair };

package/dist/index.d.ts

@@ -103,8 +103,10 @@ interface SearchResult {
 }
 interface ICryptoProvider {
     name: string;
-    getPrice(symbol: string): Promise<PriceData | null>;
-    getTokenInfo(address: string, network?: string): Promise<TokenInfo | null>;
+    /** True for DEX providers that resolve contract addresses, not ticker symbols. */
+    addressBased?: boolean;
+    getPrice(query: string, network?: string): Promise<PriceData | null>;
+    getTokenInfo(query: string, network?: string): Promise<TokenInfo | null>;
     search(query: string): Promise<SearchResult[]>;
 }
 
@@ -113,28 +115,23 @@ interface CrypullOptions {
 }
 declare class Crypull {
     providers: ICryptoProvider[];
-    private coinGecko;
-    private dexScreener;
-    private geckoTerminal;
-    private binance;
-    private coinpaprika;
-    private coincap;
-    private cryptoCompare;
     constructor(options?: CrypullOptions);
-    private isAddress;
+    private symbolProviders;
+    private addressProviders;
+    private coinGecko;
     /**
-     * Search for a token or coin across multiple providers in parallel
+     * Search for a token or coin across symbol + DEX providers in parallel.
      */
     search(query: string): Promise<SearchResult[]>;
     /**
-     * Get the current price of a cryptocurrency
-     * @param query Can be a symbol (e.g., 'BTC') or a contract address
-     * @param network Optional network for DEX addresses (e.g., 'eth', 'bsc')
+     * Get the current price of a cryptocurrency.
+     * @param query Symbol (e.g. 'BTC') or contract address
+     * @param network Optional network for DEX addresses (e.g. 'eth', 'bsc', 'solana')
      */
     price(query: string, network?: string): Promise<PriceData | null>;
     /**
      * Get detailed token info (market cap, volume, liquidity, etc.)
-     * @param query Can be a symbol (e.g., 'BTC') or a contract address
+     * @param query Symbol (e.g. 'BTC') or contract address
      * @param network Optional network for DEX addresses
      */
     info(query: string, network?: string): Promise<TokenInfo | null>;
@@ -160,22 +157,53 @@ declare class Crypull {
     gas(): Promise<GasData | null>;
     /**
      * Get historical chart data for a coin
-     * @param query Coin symbol or ID
+     * @param query Coin symbol or CoinGecko ID
      * @param days Number of days (e.g. 1, 7, 30)
      */
     chart(query: string, days?: number): Promise<ChartData | null>;
 }
 
+/**
+ * Detect contract addresses (EVM / Solana-style) vs ticker symbols.
+ */
+declare function isContractAddress(query: string): boolean;
+/**
+ * Normalize to a Binance USD quote pair (library prices are always USD-oriented).
+ * e.g. BTC → BTCUSDT, WBTC → WBTCUSDT, ETHUSDT → ETHUSDT
+ */
+declare function toBinancePair(symbol: string): string;
+/**
+ * Strip a Binance USD quote suffix back to the base asset symbol.
+ */
+declare function fromBinancePair(pair: string): string;
+/**
+ * Default GeckoTerminal network for an address when none is provided.
+ */
+declare function defaultDexNetwork(address: string): string;
+/** Parse a number; return undefined for NaN/non-finite (preserves 0). */
+declare function finiteOrUndefined(value: unknown): number | undefined;
+
 declare class CoinGeckoProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
+    /** Resolve a symbol or slug to a CoinGecko coin id. */
+    resolveId(symbolOrId: string): Promise<{
+        id: string;
+        symbol: string;
+    } | null>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
-    getTokenInfo(id: string): Promise<TokenInfo | null>;
+    getTokenInfo(symbolOrId: string): Promise<TokenInfo | null>;
+    getGlobalMarket(): Promise<GlobalMarketData | null>;
+    getTrending(): Promise<TrendingCoin[]>;
+    getTop(limit?: number): Promise<TopCoin[]>;
+    getChart(query: string, days?: number): Promise<ChartData | null>;
 }
 
 declare class DexScreenerProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(address: string): Promise<PriceData | null>;
@@ -184,6 +212,7 @@ declare class DexScreenerProvider implements ICryptoProvider {
 
 declare class GeckoTerminalProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(address: string, network?: string): Promise<PriceData | null>;
@@ -192,6 +221,7 @@ declare class GeckoTerminalProvider implements ICryptoProvider {
 
 declare class BinanceProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbol: string): Promise<PriceData | null>;
@@ -200,6 +230,7 @@ declare class BinanceProvider implements ICryptoProvider {
 
 declare class CoinpaprikaProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
@@ -208,6 +239,7 @@ declare class CoinpaprikaProvider implements ICryptoProvider {
 
 declare class CoinCapProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
     private baseUrl;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbolOrId: string): Promise<PriceData | null>;
@@ -216,12 +248,116 @@ declare class CoinCapProvider implements ICryptoProvider {
 
 declare class CryptoCompareProvider implements ICryptoProvider {
     name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(_query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * CoinMarketCap keyless public API (no API key required).
+ * https://pro-api.coinmarketcap.com/public-api
+ */
+declare class CoinMarketCapProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private headers;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbolOrSlug: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * CoinLore free public API (no API key).
+ * https://api.coinlore.net/api/
+ */
+declare class CoinLoreProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    /** Scan top tickers pages to resolve symbol → coin id. */
+    private findTicker;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbolOrId: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Coinbase public spot price API (no API key).
+ * https://api.coinbase.com/v2/
+ */
+declare class CoinbaseProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Kraken public ticker API (no API key).
+ * https://api.kraken.com/0/public/
+ *
+ * Note: Kraken uses XBT for Bitcoin.
+ */
+declare class KrakenProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private toPair;
+    private fromPairKey;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * KuCoin public market API (no API key).
+ * https://api.kucoin.com/api/v1/
+ */
+declare class KuCoinProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    private toSymbol;
+    private baseAsset;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Bybit public spot ticker API (no API key).
+ * https://api.bybit.com/v5/market/
+ */
+declare class BybitProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
+    private baseUrl;
+    search(query: string): Promise<SearchResult[]>;
+    getPrice(symbol: string): Promise<PriceData | null>;
+    getTokenInfo(symbol: string): Promise<TokenInfo | null>;
+}
+
+/**
+ * Gate.io public spot API (no API key).
+ * https://api.gateio.ws/api/v4/
+ */
+declare class GateIoProvider implements ICryptoProvider {
+    name: string;
+    addressBased: boolean;
     private baseUrl;
+    private toPair;
+    private baseAsset;
     search(query: string): Promise<SearchResult[]>;
     getPrice(symbol: string): Promise<PriceData | null>;
     getTokenInfo(symbol: string): Promise<TokenInfo | null>;
 }
 
+/** Default shared instance for quick usage */
 declare const crypull: Crypull;
 
-export { BinanceProvider, type ChartData, CoinCapProvider, CoinGeckoProvider, CoinpaprikaProvider, CryptoCompareProvider, Crypull, type CrypullOptions, type DexPairInfo, DexScreenerProvider, type GasData, GeckoTerminalProvider, type GlobalMarketData, type ICryptoProvider, type PriceData, type SearchResult, type SentimentData, type TokenInfo, type TokenLinks, type TopCoin, type TrendingCoin, crypull };
+export { BinanceProvider, BybitProvider, type ChartData, CoinCapProvider, CoinGeckoProvider, CoinLoreProvider, CoinMarketCapProvider, CoinbaseProvider, CoinpaprikaProvider, CryptoCompareProvider, Crypull, type CrypullOptions, type DexPairInfo, DexScreenerProvider, type GasData, GateIoProvider, GeckoTerminalProvider, type GlobalMarketData, type ICryptoProvider, KrakenProvider, KuCoinProvider, type PriceData, type SearchResult, type SentimentData, type TokenInfo, type TokenLinks, type TopCoin, type TrendingCoin, crypull, defaultDexNetwork, finiteOrUndefined, fromBinancePair, isContractAddress, toBinancePair };