coingecko-pro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xJesus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+<p align="center">
+  <h1 align="center">coingecko-pro</h1>
+  <p align="center">The most comprehensive CoinGecko API SDK for JavaScript &amp; TypeScript</p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/coingecko-pro"><img src="https://img.shields.io/npm/v/coingecko-pro.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/coingecko-pro"><img src="https://img.shields.io/npm/dm/coingecko-pro.svg" alt="npm downloads"></a>
+  <a href="https://github.com/0xJesus/coingecko-pro/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/coingecko-pro.svg" alt="license"></a>
+  <img src="https://img.shields.io/badge/TypeScript-first-blue.svg" alt="TypeScript">
+  <img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="zero dependencies">
+</p>
+
+---
+
+Full coverage of the **CoinGecko Pro API** and **On-chain DEX data (GeckoTerminal)** in a single, typed SDK. One import, every endpoint.
+
+## Features
+
+- **86 endpoints** across 8 namespaces -- coins, exchanges, derivatives, NFTs, on-chain DEX, global, treasury, and meta
+- **TypeScript-first** -- every request and response is fully typed, with JSDoc on every method
+- **Zero runtime dependencies** -- uses the built-in `fetch` API (Node 18+, Bun, Deno, browsers)
+- **In-memory TTL cache** -- deduplicates identical requests within a configurable window
+- **Token-bucket rate limiter** -- automatically enforces CoinGecko rate limits (30/min free, 500/min Pro)
+- **Exponential-backoff retry** -- retries on 429 and 503 with configurable attempts and delay
+- **Request timeout** -- AbortController-based timeout with clean error reporting
+- **Lifecycle hooks** -- `onRequest`, `onResponse`, `onError` for logging, metrics, and debugging
+- **Dual format** -- ships ESM and CommonJS builds with full source maps and declaration files
+- **Tree-shakeable** -- import only the endpoint classes you need for minimal bundle size
+
+## Quick Start
+
+### Install
+
+```bash
+npm install coingecko-pro
+```
+
+```bash
+pnpm add coingecko-pro
+```
+
+```bash
+yarn add coingecko-pro
+```
+
+### Basic Usage
+
+```typescript
+import { CoinGecko } from 'coingecko-pro';
+
+// Pro tier (recommended)
+const cg = new CoinGecko({ apiKey: 'CG-xxx' });
+
+// Free tier (lower rate limits, some endpoints unavailable)
+const cg = new CoinGecko();
+
+// Check connectivity
+const { gecko_says } = await cg.ping();
+console.log(gecko_says); // "(V3) To the Moon!"
+
+// Get Bitcoin market data
+const btc = await cg.coins.getById('bitcoin');
+console.log(btc.market_data.current_price.usd);
+
+// Get top coins by market cap
+const markets = await cg.coins.markets({ vs_currency: 'usd', per_page: 10 });
+markets.forEach(coin => {
+  console.log(`${coin.name}: $${coin.current_price}`);
+});
+```
+
+## Configuration
+
+All options are optional. Sensible defaults are applied automatically.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | -- | CoinGecko Pro API key. Switches base URL to `pro-api.coingecko.com` and sets the auth header. |
+| `baseUrl` | `string` | auto | Override the base URL (useful for proxies or testing). |
+| `cacheTtl` | `number` | `30000` | Default response cache TTL in milliseconds. Set to `0` to disable. |
+| `maxRetries` | `number` | `3` | Maximum retry attempts for transient errors (429, 503). |
+| `retryDelay` | `number` | `1000` | Base delay (ms) for the first retry. Uses exponential backoff: `retryDelay * 2^attempt`. |
+| `rateLimit` | `number` | `500` (Pro) / `30` (Free) | Maximum requests per minute. |
+| `timeout` | `number` | `15000` | Request timeout in milliseconds. |
+| `onRequest` | `(url) => void` | -- | Hook called before every outgoing request. |
+| `onResponse` | `(url, status, ms) => void` | -- | Hook called after every completed request. |
+| `onError` | `(url, error) => void` | -- | Hook called when a request fails after all retries. |
+
+```typescript
+const cg = new CoinGecko({
+  apiKey: process.env.CG_API_KEY,
+  cacheTtl: 60_000,       // 1 minute cache
+  maxRetries: 5,
+  retryDelay: 2_000,
+  rateLimit: 500,
+  timeout: 30_000,
+  onRequest: (url) => console.log(`-> ${url}`),
+  onResponse: (url, status, ms) => console.log(`<- ${status} ${ms}ms`),
+  onError: (url, err) => console.error(`!! ${url}`, err.message),
+});
+```
+
+## API Reference
+
+### Namespace Overview
+
+| Namespace | Methods | Description |
+|---|---|---|
+| `cg.coins` | 23 | Prices, markets, charts, OHLC, supply, categories, contract lookups |
+| `cg.exchanges` | 6 | Exchange listings, details, tickers, volume charts |
+| `cg.derivatives` | 4 | Derivatives tickers and exchange data |
+| `cg.nfts` | 7 | NFT collections, market data, charts, tickers |
+| `cg.onchain` | 27 | On-chain DEX pools, tokens, trades, OHLCV, top traders/holders |
+| `cg.global` | 8 | Global stats, search, trending, exchange rates, asset platforms |
+| `cg.treasury` | 5 | Public treasury holdings, charts, transactions |
+| `cg.ping()` | 1 | API connectivity check |
+| `cg.apiUsage()` | 1 | API key usage stats (Pro only) |
+
+### Coins
+
+```typescript
+// Simple price lookup
+const prices = await cg.coins.price({
+  ids: 'bitcoin,ethereum',
+  vs_currencies: 'usd,eur',
+});
+
+// Token price by contract address
+const tokenPrice = await cg.coins.tokenPrice('ethereum', {
+  contract_addresses: '0xdac17f958d2ee523a2206206994597c13d831ec7',
+  vs_currencies: 'usd',
+});
+
+// Market data with sorting and pagination
+const markets = await cg.coins.markets({
+  vs_currency: 'usd',
+  order: 'market_cap_desc',
+  per_page: 100,
+  page: 1,
+  sparkline: true,
+});
+
+// Full coin detail
+const btc = await cg.coins.getById('bitcoin', {
+  localization: false,
+  tickers: false,
+  community_data: false,
+});
+
+// Historical market chart
+const chart = await cg.coins.marketChart('bitcoin', {
+  vs_currency: 'usd',
+  days: '30',
+});
+
+// OHLC candlestick data
+const ohlc = await cg.coins.ohlc('bitcoin', {
+  vs_currency: 'usd',
+  days: '14',
+});
+
+// Top gainers and losers
+const movers = await cg.coins.topGainersLosers({ vs_currency: 'usd' });
+
+// Categories
+const categories = await cg.coins.categories({ order: 'market_cap_desc' });
+```
+
+### On-chain DEX (GeckoTerminal)
+
+```typescript
+// Trending pools across all networks
+const { data: trending } = await cg.onchain.trendingPools();
+
+// Top pools on a specific DEX
+const { data: uniPools } = await cg.onchain.topPoolsByDex('eth', 'uniswap_v3');
+
+// Pool OHLCV candlestick data
+const ohlcv = await cg.onchain.poolOhlcv(
+  'eth',
+  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
+  'hour',
+  { aggregate: '4', limit: 200 },
+);
+
+// Token info with security flags
+const { data: tokenInfo } = await cg.onchain.tokenInfo(
+  'eth',
+  '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+);
+
+// Top traders (whale tracking) -- Pro only
+const { data: whales } = await cg.onchain.topTraders(
+  'eth',
+  '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+);
+
+// Top holders -- Pro only
+const { data: holders } = await cg.onchain.topHolders(
+  'eth',
+  '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+);
+
+// Search pools by name or address
+const { data: results } = await cg.onchain.searchPools('PEPE', { network: 'eth' });
+
+// Advanced pool filtering (megafilter) -- Pro only
+const { data: filtered } = await cg.onchain.megafilter({
+  network: 'eth',
+  reserve_in_usd_gte: 100_000,
+  sort: 'h24_volume_usd',
+});
+```
+
+### Treasury
+
+```typescript
+// Companies holding Bitcoin
+const btcTreasury = await cg.treasury.companyHoldings('bitcoin');
+console.log(btcTreasury.total_holdings, btcTreasury.total_value_usd);
+
+// Entity details
+const entity = await cg.treasury.entityHoldings('microstrategy');
+
+// Holding chart over time
+const chart = await cg.treasury.entityHoldingChart('microstrategy', 'bitcoin');
+
+// Transaction history
+const txs = await cg.treasury.entityTransactions('microstrategy');
+```
+
+### Global & Search
+
+```typescript
+// Global crypto market data
+const global = await cg.global.global();
+console.log(global.data.total_market_cap.usd);
+
+// DeFi market data
+const defi = await cg.global.globalDefi();
+
+// Search coins, exchanges, categories
+const results = await cg.global.search('solana');
+
+// Trending coins and NFTs
+const trending = await cg.global.trending();
+
+// BTC exchange rates
+const rates = await cg.global.exchangeRates();
+```
+
+### Exchanges & Derivatives
+
+```typescript
+// Top exchanges by trust score
+const exchanges = await cg.exchanges.list({ per_page: 10 });
+
+// Exchange tickers
+const tickers = await cg.exchanges.tickers('binance', {
+  coin_ids: 'bitcoin',
+});
+
+// Derivatives tickers
+const derivTickers = await cg.derivatives.tickers();
+
+// Derivatives exchanges
+const derivExchanges = await cg.derivatives.exchanges();
+```
+
+### NFTs
+
+```typescript
+// NFT collections list
+const collections = await cg.nfts.list();
+
+// Collection detail
+const bayc = await cg.nfts.getById('bored-ape-yacht-club');
+
+// NFT market chart -- Pro only
+const nftChart = await cg.nfts.marketChart('bored-ape-yacht-club', { days: '30' });
+```
+
+## Pro vs Free API
+
+CoinGecko offers both free and paid API tiers. This SDK works with both -- just pass your API key to unlock Pro features.
+
+| Feature | Free | Pro (Analyst+) |
+|---|---|---|
+| Rate limit | 30 req/min | 500 req/min |
+| Base URL | `api.coingecko.com` | `pro-api.coingecko.com` |
+| Top gainers/losers | -- | Yes |
+| OHLC range | -- | Yes |
+| Supply charts | -- | Yes |
+| NFT market charts | -- | Yes |
+| On-chain megafilter | -- | Yes |
+| On-chain top traders | -- | Yes |
+| On-chain top holders | -- | Yes |
+| Treasury data | -- | Yes |
+| Global market cap chart | -- | Yes |
+| API usage endpoint | -- | Yes |
+
+```typescript
+// Free tier -- no API key needed
+const cg = new CoinGecko();
+
+// Pro tier -- pass your API key
+const cg = new CoinGecko({ apiKey: 'CG-xxxxxxxxxxxxxxxxxxxx' });
+```
+
+Get a Pro API key at [coingecko.com/api/pricing](https://www.coingecko.com/api/pricing).
+
+## Error Handling
+
+All API errors throw a `CoinGeckoError` with structured information:
+
+```typescript
+import { CoinGecko, CoinGeckoError } from 'coingecko-pro';
+
+const cg = new CoinGecko({ apiKey: 'CG-xxx' });
+
+try {
+  await cg.coins.getById('this-coin-does-not-exist');
+} catch (err) {
+  if (err instanceof CoinGeckoError) {
+    console.error(err.message);  // Human-readable error description
+    console.error(err.status);   // HTTP status code (0 for network errors)
+    console.error(err.url);      // The URL that was requested
+    console.error(err.data);     // Raw response body, if available
+  }
+}
+```
+
+| Status | Meaning | SDK Behavior |
+|---|---|---|
+| `0` | Network error / timeout | Retried up to `maxRetries` times |
+| `429` | Rate limited | Retried with exponential backoff |
+| `401` | Invalid API key | Thrown immediately (not retried) |
+| `403` | Pro-only endpoint | Thrown immediately (not retried) |
+| `404` | Resource not found | Thrown immediately (not retried) |
+| `503` | Service unavailable | Retried with exponential backoff |
+
+## Cache & Rate Limiting
+
+### Built-in Cache
+
+Every response is cached in memory with a configurable TTL. Identical requests within the cache window are served instantly without hitting the API.
+
+```typescript
+const cg = new CoinGecko({
+  apiKey: 'CG-xxx',
+  cacheTtl: 60_000,  // Cache responses for 60 seconds
+});
+
+// First call hits the API
+const btc1 = await cg.coins.getById('bitcoin');
+
+// Second call within 60s returns cached data instantly
+const btc2 = await cg.coins.getById('bitcoin');
+```
+
+Disable caching globally by setting `cacheTtl: 0`.
+
+### Rate Limiter
+
+A token-bucket rate limiter runs in-process and ensures your application never exceeds the CoinGecko rate limit. When the bucket is empty, requests automatically wait until a token becomes available.
+
+```typescript
+// Pro tier: 500 requests/minute (default when apiKey is set)
+const cg = new CoinGecko({ apiKey: 'CG-xxx' });
+
+// Custom rate limit
+const cg = new CoinGecko({ apiKey: 'CG-xxx', rateLimit: 100 });
+```
+
+## Advanced Usage
+
+### Standalone Endpoint Classes
+
+For maximum tree-shaking or custom compositions, import endpoint classes directly:
+
+```typescript
+import { CoinGeckoClient } from 'coingecko-pro';
+import { CoinsEndpoints } from 'coingecko-pro';
+import { OnchainEndpoints } from 'coingecko-pro';
+
+const client = new CoinGeckoClient({ apiKey: 'CG-xxx' });
+const coins = new CoinsEndpoints(client);
+const onchain = new OnchainEndpoints(client);
+
+const btc = await coins.getById('bitcoin');
+const pools = await onchain.trendingPools();
+```
+
+### Lifecycle Hooks
+
+Use hooks for logging, metrics, or request tracing:
+
+```typescript
+const cg = new CoinGecko({
+  apiKey: 'CG-xxx',
+  onRequest: (url) => {
+    performance.mark(`cg-start-${url}`);
+  },
+  onResponse: (url, status, ms) => {
+    metrics.histogram('coingecko.latency', ms, { status: String(status) });
+  },
+  onError: (url, error) => {
+    logger.error('CoinGecko request failed', { url, error: error.message });
+  },
+});
+```
+
+## Requirements
+
+- **Node.js 18+**, **Bun**, **Deno**, or any environment with a global `fetch` implementation
+- No polyfills needed -- zero runtime dependencies
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes with tests
+4. Run checks: `npm run lint && npm test`
+5. Submit a pull request
+
+## License
+
+[MIT](LICENSE) -- 0xJesus