coinscan 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIRB
+
+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

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# coinscan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official TypeScript/JavaScript client for the [CoinScan API](https://coinscan.tech): scan any token on Solana, Ethereum, BSC, Base and more for price, liquidity, holders, snipers, bundles, LP lock, honeypot and tax checks, dev history and an AI rug estimate; map holders and bubble clusters; read wallet PnL; render charts; pull market and launchpad data.
+
+```bash
+npm install coinscan
+```
+
+Zero dependencies. Node 18+, Bun, Deno and edge runtimes (anything with `fetch`). ESM and CommonJS, full TypeScript types, automatic retries on rate limits, and your remaining credits after every call.
+
+## Quickstart
+
+Get a free key (25 scans a day) at [coinscan.tech/signup](https://coinscan.tech/signup), or:
+
+```ts
+import { CoinScan } from "coinscan";
+
+const { api_key } = await CoinScan.signup({ email: "you@example.com" }); // shown once
+```
+
+```ts
+import { CoinScan } from "coinscan";
+
+const cs = new CoinScan({ apiKey: process.env.COINSCAN_API_KEY }); // the default, too
+const scan = await cs.scan("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN");
+
+console.log(scan.name, scan.market?.mcap, scan.market?.liquidity);
+console.log("bundles", scan.holders?.bundle_pct, "snipers", scan.holders?.sniper_pct);
+console.log("rug probability", scan.ai_predictions?.p_rug);
+console.log(cs.lastUsage?.remaining, "credits left today");
+```
+
+CommonJS: `const { CoinScan } = require("coinscan");`
+
+Keep the key on a server. A key shipped in browser or app code is public.
+
+## What you can call
+
+| method | returns | credits |
+|-|-|-|
+| `cs.scan(address, { chain })` | full token scan | 10 |
+| `cs.scanLpLock(address)` | finishes a scan made with `lpDefer: true` | 6 |
+| `cs.detect(address)` | `{ address, chain }` from the address shape | 0 |
+| `cs.resolveTicker("PEPE")` | candidate contracts ranked by liquidity | 2 |
+| `cs.resolvePair(chain, pair)` | the token behind a pool | 0 |
+| `cs.major("BTC")` | price, cap, supply, ATH of a major coin | 0 |
+| `cs.mcapBatch([addr, ...])` | `{ [address]: mcap }` for up to 500 tokens | 1 |
+| `cs.maxMcapBatch(items)` | highest cap since a timestamp | 3 |
+| `cs.lore(address)`, `cs.community(address)` | backstory; X community stats | 4 |
+| `cs.search("cat")` | DexScreener pairs | 0 |
+| `cs.chart(network, pool, { plotType: "ta" })` | PNG `Uint8Array` | 3 |
+| `cs.subscan.holders(token, { chain })` | top holders report | 1 |
+| `cs.subscan.holdersMap(token, { chain })` | holders by behaviour | 1 |
+| `cs.subscan.whaleMap(token, { chain })` | holders by size | 2 |
+| `cs.subscan.bubbleMap(token, { chain })` | `{ messages, image }` (PNG bytes) | 5 |
+| `cs.subscan.earlyBuyers(token, { chain })` | first 50 buyers and what they did | 2 |
+| `cs.subscan.walletMap(token, { chain })` | holders labelled bot, insider, smart money | 1 |
+| `cs.subscan.kolHolders(token)` | influencer wallets holding (Solana) | 1 |
+| `cs.subscan.topHolderBags(token)` | top holders' other pump.fun bags | 1 |
+| `cs.subscan.overlap(token1, token2)` | wallets holding both (Solana) | 2 |
+| `cs.subscan.dev(address, { chain })` | deployer launch history | 4 |
+| `cs.subscan.topTraders(token, { chain })` | traders by realized PnL | 1 |
+| `cs.subscan.walletStats(wallet)` | 30-day stats across chains | 3 |
+| `cs.wallet.pnl(wallet, { chain })` | PnL report | 5 |
+| `cs.wallet.floor(token, { chain })` | holders' entry caps, supply in loss | 1 |
+| `cs.wallet.tokenBalance(wallet, token, { chain })` | number | 1 |
+| `cs.wallet.tokenBalances(token, wallets, { chain })` | `{ [wallet]: balance }` | 1 |
+| `cs.wallet.tx(hash, { chain })` | `{ from, to, value_wei, block_number }` | 1 |
+| `cs.market.macro()`, `.news()`, `.calendar()`, `.gas()` | market data | 0 |
+| `cs.market.dexPaid()`, `.dexTrending()`, `.dexPaidStatus(token)` | DexScreener signals | 0 |
+| `cs.market.pumpfunGraduates()`, `.pumpfunSearch(q)` | pump.fun | 0 |
+| `cs.market.treemap()`, `.topCoinsCard()`, `.fearGreedImage()`, `.pnlCard({...})` | PNG bytes | 0 |
+| `cs.launchpads.summary()`, `.stats()`, `.chart()`, `.heat()` | launchpad volume and heat | 0 |
+| `cs.account.me()`, `.usage()`, `.rotateKey()` | your plan, usage, keys | 0 |
+| `cs.billing.plans()`, `.createInvoice({...})`, `.waitForPayment(id)` | plans and USDT/USDC invoices | 0 |
+
+Field-by-field documentation: [coinscan.tech/docs](https://coinscan.tech/docs).
+
+## Text reports
+
+Holder, wallet and deployer routes return formatted reports (Telegram-style HTML), ready to post in a bot. `toText` makes them plain:
+
+```ts
+import { CoinScan, toText } from "coinscan";
+
+const cs = new CoinScan();
+console.log(toText(await cs.subscan.dev("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")));
+```
+
+## Images
+
+```ts
+import { writeFile } from "node:fs/promises";
+
+await writeFile("chart.png", await cs.chart("solana", "PAIR_ADDRESS", { timeframe: "hour", plotType: "ta" }));
+
+const bubble = await cs.subscan.bubbleMap("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN");
+if (bubble.image) await writeFile("bubble.png", bubble.image);
+```
+
+## Credits, limits and errors
+
+`cs.lastUsage` holds the usage headers of the last metered call: `cost`, `limit`, `remaining`, `reset` (next 00:00 UTC), `rateLimit`, `rateRemaining`.
+
+```ts
+import { CoinScan, NotFoundError, QuotaExceededError, UpstreamTimeoutError } from "coinscan";
+
+try {
+  await cs.scan("So11111111111111111111111111111111111111112");
+} catch (e) {
+  if (e instanceof NotFoundError) console.log("no such token");
+  else if (e instanceof QuotaExceededError) console.log("out of credits until", e.resetAt, e.upgradeUrl);
+  else if (e instanceof UpstreamTimeoutError) console.log("a provider was slow; try again");
+  else throw e;
+}
+```
+
+| error | when |
+|-|-|
+| `AuthenticationError` | 401: missing or unknown key |
+| `NotFoundError` | 404: token, pair or data not found |
+| `ValidationError` | 422: bad input |
+| `RateLimitError` | 429 per-minute limit (retried, then thrown; has `retryAfter`) |
+| `QuotaExceededError` | 429 daily credits spent (`resetAt`, `upgradeUrl`) |
+| `UpstreamTimeoutError` | a 45 s upstream deadline passed |
+| `InternalServerError` | 5xx (502/503/504 retried; credits are refunded) |
+| `APIConnectionError`, `APITimeoutError` | network problems |
+
+All extend `CoinScanError`. `new CoinScan({ maxRetries: 0 })` turns retries off. The default timeout is 90 s per attempt because a scan can take up to 60.
+
+## Paying from code
+
+```ts
+const inv = await cs.billing.createInvoice({ plan: "starter", chain: "solana", token: "USDC" });
+console.log(`send exactly ${inv.amount} ${inv.token} to ${inv.pay_to}`);
+console.log(inv.payment_uri); // Solana Pay / EIP-681 link
+const paid = await cs.billing.waitForPayment(inv.id);
+console.log(paid.status, paid.plan_expires_at);
+```
+
+## Configuration
+
+| option | environment variable | default |
+|-|-|-|
+| `apiKey` | `COINSCAN_API_KEY` | none |
+| `baseURL` | `COINSCAN_BASE_URL` | `https://api.coinscan.tech` |
+| `timeout` (ms) | | 90 000 |
+| `maxRetries` | | 2 |
+| `fetch` | | `globalThis.fetch` |
+
+## Links
+
+- Docs: https://coinscan.tech/docs
+- Pricing: https://coinscan.tech/pricing (free 25 scans a day; from $50 a month, paid in USDT or USDC)
+- MCP server for Claude and Cursor: https://coinscan.tech/docs/mcp
+- Support: contact@pirb.tech
+
+MIT licensed.