coinscan-sdk 0.1.0__tar.gz

coinscan_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.DS_Store

coinscan_sdk-0.1.0/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.

coinscan_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: coinscan-sdk
+Version: 0.1.0
+Summary: Official Python client for the CoinScan API: token scans, holders, bubble maps, wallets, charts and market data for Solana, Ethereum, BSC and Base.
+Project-URL: Homepage, https://coinscan.tech
+Project-URL: Documentation, https://coinscan.tech/docs/sdks
+Project-URL: API reference, https://coinscan.tech/docs/reference
+Project-URL: Pricing, https://coinscan.tech/pricing
+Author-email: PIRB <contact@pirb.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,base,bsc,coinscan,crypto,ethereum,honeypot,pump.fun,rug check,sdk,solana,token scanner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# coinscan-sdk
+
+Official Python 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
+pip install coinscan-sdk
+```
+
+Imported as `coinscan`. Python 3.9+. One dependency (`httpx`). Sync and async clients, typed responses, 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 from Python:
+
+```python
+from coinscan import CoinScan
+
+print(CoinScan.signup(email="you@example.com")["api_key"])   # shown once
+```
+
+```python
+from coinscan import CoinScan
+
+cs = CoinScan("cs_live_...")          # or set COINSCAN_API_KEY
+scan = cs.scan("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")
+
+print(scan["name"], scan["market"]["mcap"], scan["market"]["liquidity"])
+print("bundles", scan["holders"]["bundle_pct"], "snipers", scan["holders"]["sniper_pct"])
+print("rug probability", scan["ai_predictions"]["p_rug"])
+print(cs.last_usage.remaining, "credits left today")
+```
+
+### Async
+
+```python
+import asyncio
+from coinscan import AsyncCoinScan
+
+async def main():
+    async with AsyncCoinScan() as cs:
+        scans = await asyncio.gather(*(cs.scan(a) for a in ["6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
+                                                              "0x6982508145454Ce325dDbE47a25d4ec3d2311933"]))
+        for s in scans:
+            print(s["symbol"], s["flags"])
+
+asyncio.run(main())
+```
+
+## What you can call
+
+| method | what it returns | credits |
+|-|-|-|
+| `cs.scan(address, chain=None)` | full token scan (dict) | 10 |
+| `cs.scan_lp_lock(address)` | finishes a scan made with `lp_defer=True` | 6 |
+| `cs.detect(address)` | `{"address", "chain"}` from the address shape | 0 |
+| `cs.resolve_ticker("PEPE")` | candidate contracts ranked by liquidity | 2 |
+| `cs.resolve_pair(chain, pair)` | the token behind a pool | 0 |
+| `cs.major("BTC")` | price, cap, supply, ATH of a major coin | 0 |
+| `cs.mcap_batch([addr, ...])` | `{address: mcap}` for up to 500 tokens | 1 |
+| `cs.max_mcap_batch(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, plot_type="ta")` | PNG bytes | 3 |
+| `cs.subscan.holders(token, chain=)` | top holders report | 1 |
+| `cs.subscan.holders_map(token, chain=)` | holders by behaviour | 1 |
+| `cs.subscan.whale_map(token, chain=)` | holders by size | 2 |
+| `cs.subscan.bubble_map(token, chain=)` | `{"messages", "image": PNG bytes}` | 5 |
+| `cs.subscan.early_buyers(token, chain=)` | first 50 buyers and what they did | 2 |
+| `cs.subscan.wallet_map(token, chain=)` | holders labelled bot, insider, smart money | 1 |
+| `cs.subscan.kol_holders(token)` | influencer wallets holding (Solana) | 1 |
+| `cs.subscan.top_holder_bags(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.top_traders(token, chain=)` | traders by realized PnL (list of dicts) | 1 |
+| `cs.subscan.wallet_stats(wallet)` | 30-day stats across chains | 3 |
+| `cs.subscan.pumpfun_meta()` | trending pump.fun words | 0 |
+| `cs.wallet.pnl(wallet, chain=)` | PnL report | 5 |
+| `cs.wallet.floor(token, chain=)` | holders' entry caps, supply in loss | 1 |
+| `cs.wallet.token_balance(wallet, token, chain=)` | float | 1 |
+| `cs.wallet.token_balances(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.dex_paid()`, `.dex_trending()`, `.dex_paid_status(token)` | DexScreener signals | 0 |
+| `cs.market.pumpfun_graduates()`, `.pumpfun_search(q)` | pump.fun | 0 |
+| `cs.market.treemap()`, `.top_coins_card()`, `.fear_greed_image()`, `.pnl_card(...)` | PNG bytes | 0 |
+| `cs.launchpads.summary()`, `.stats()`, `.chart()`, `.heat()` | launchpad volume and heat | 0 |
+| `cs.account.me()`, `.usage()`, `.rotate_key()` | your plan, usage, keys | 0 |
+| `cs.billing.plans()`, `.create_invoice(...)`, `.wait_for_payment(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. `to_text` turns them into plain text:
+
+```python
+from coinscan import CoinScan, to_text
+
+cs = CoinScan()
+print(to_text(cs.subscan.dev("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")))
+```
+
+## Images
+
+```python
+from pathlib import Path
+
+Path("chart.png").write_bytes(cs.chart("solana", "PAIR_ADDRESS", timeframe="hour", plot_type="ta"))
+
+bubble = cs.subscan.bubble_map("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")
+if bubble["image"]:
+    Path("bubble.png").write_bytes(bubble["image"])
+```
+
+## Credits, limits and errors
+
+`cs.last_usage` holds the usage headers of the last metered call: `cost`, `limit`, `remaining`, `reset` (next 00:00 UTC), `rate_limit`, `rate_remaining`.
+
+```python
+from coinscan import CoinScan, QuotaExceededError, NotFoundError, UpstreamTimeoutError
+
+cs = CoinScan()
+try:
+    scan = cs.scan("So11111111111111111111111111111111111111112")
+except NotFoundError:
+    print("no such token")
+except QuotaExceededError as e:
+    print("out of credits until", e.reset_at, "upgrade:", e.upgrade_url)
+except UpstreamTimeoutError:
+    print("a data provider was slow; try again")
+```
+
+| exception | 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 automatically, then raised; has `retry_after`) |
+| `QuotaExceededError` | 429 daily credits spent (`reset_at`, `upgrade_url`) |
+| `UpstreamTimeoutError` | a 45 s upstream deadline passed |
+| `InternalServerError` | 5xx (502/503/504 retried; credits are refunded) |
+| `APIConnectionError`, `APITimeoutError` | network problems |
+
+All inherit from `CoinScanError`. Retries: `CoinScan(max_retries=2)` by default; `0` turns them off. The default timeout is 90 s because a scan can take up to 60.
+
+## Paying from code
+
+```python
+cs = CoinScan()
+inv = cs.billing.create_invoice("starter", chain="solana", token="USDC")
+print(f"send exactly {inv['amount']} {inv['token']} to {inv['pay_to']}")
+print(inv["payment_uri"])                     # Solana Pay / EIP-681 link
+paid = cs.billing.wait_for_payment(inv["id"])
+print(paid["status"], paid.get("plan_expires_at"))
+```
+
+## Command line
+
+```bash
+export COINSCAN_API_KEY=cs_live_...
+coinscan scan 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
+coinscan holders 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
+coinscan chart solana PAIR_ADDRESS --plot-type ta > chart.png
+coinscan me
+```
+
+## Configuration
+
+| setting | argument | environment variable | default |
+|-|-|-|-|
+| API key | `CoinScan(api_key)` | `COINSCAN_API_KEY` | none |
+| base URL | `base_url=` | `COINSCAN_BASE_URL` | `https://api.coinscan.tech` |
+| timeout | `timeout=` | | 90 s |
+| retries | `max_retries=` | | 2 |
+| HTTP client | `http_client=httpx.Client(...)` | | one per client |
+
+## 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.

coinscan_sdk-0.1.0/README.md

@@ -0,0 +1,184 @@
+# coinscan-sdk
+
+Official Python 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
+pip install coinscan-sdk
+```
+
+Imported as `coinscan`. Python 3.9+. One dependency (`httpx`). Sync and async clients, typed responses, 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 from Python:
+
+```python
+from coinscan import CoinScan
+
+print(CoinScan.signup(email="you@example.com")["api_key"])   # shown once
+```
+
+```python
+from coinscan import CoinScan
+
+cs = CoinScan("cs_live_...")          # or set COINSCAN_API_KEY
+scan = cs.scan("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")
+
+print(scan["name"], scan["market"]["mcap"], scan["market"]["liquidity"])
+print("bundles", scan["holders"]["bundle_pct"], "snipers", scan["holders"]["sniper_pct"])
+print("rug probability", scan["ai_predictions"]["p_rug"])
+print(cs.last_usage.remaining, "credits left today")
+```
+
+### Async
+
+```python
+import asyncio
+from coinscan import AsyncCoinScan
+
+async def main():
+    async with AsyncCoinScan() as cs:
+        scans = await asyncio.gather(*(cs.scan(a) for a in ["6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
+                                                              "0x6982508145454Ce325dDbE47a25d4ec3d2311933"]))
+        for s in scans:
+            print(s["symbol"], s["flags"])
+
+asyncio.run(main())
+```
+
+## What you can call
+
+| method | what it returns | credits |
+|-|-|-|
+| `cs.scan(address, chain=None)` | full token scan (dict) | 10 |
+| `cs.scan_lp_lock(address)` | finishes a scan made with `lp_defer=True` | 6 |
+| `cs.detect(address)` | `{"address", "chain"}` from the address shape | 0 |
+| `cs.resolve_ticker("PEPE")` | candidate contracts ranked by liquidity | 2 |
+| `cs.resolve_pair(chain, pair)` | the token behind a pool | 0 |
+| `cs.major("BTC")` | price, cap, supply, ATH of a major coin | 0 |
+| `cs.mcap_batch([addr, ...])` | `{address: mcap}` for up to 500 tokens | 1 |
+| `cs.max_mcap_batch(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, plot_type="ta")` | PNG bytes | 3 |
+| `cs.subscan.holders(token, chain=)` | top holders report | 1 |
+| `cs.subscan.holders_map(token, chain=)` | holders by behaviour | 1 |
+| `cs.subscan.whale_map(token, chain=)` | holders by size | 2 |
+| `cs.subscan.bubble_map(token, chain=)` | `{"messages", "image": PNG bytes}` | 5 |
+| `cs.subscan.early_buyers(token, chain=)` | first 50 buyers and what they did | 2 |
+| `cs.subscan.wallet_map(token, chain=)` | holders labelled bot, insider, smart money | 1 |
+| `cs.subscan.kol_holders(token)` | influencer wallets holding (Solana) | 1 |
+| `cs.subscan.top_holder_bags(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.top_traders(token, chain=)` | traders by realized PnL (list of dicts) | 1 |
+| `cs.subscan.wallet_stats(wallet)` | 30-day stats across chains | 3 |
+| `cs.subscan.pumpfun_meta()` | trending pump.fun words | 0 |
+| `cs.wallet.pnl(wallet, chain=)` | PnL report | 5 |
+| `cs.wallet.floor(token, chain=)` | holders' entry caps, supply in loss | 1 |
+| `cs.wallet.token_balance(wallet, token, chain=)` | float | 1 |
+| `cs.wallet.token_balances(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.dex_paid()`, `.dex_trending()`, `.dex_paid_status(token)` | DexScreener signals | 0 |
+| `cs.market.pumpfun_graduates()`, `.pumpfun_search(q)` | pump.fun | 0 |
+| `cs.market.treemap()`, `.top_coins_card()`, `.fear_greed_image()`, `.pnl_card(...)` | PNG bytes | 0 |
+| `cs.launchpads.summary()`, `.stats()`, `.chart()`, `.heat()` | launchpad volume and heat | 0 |
+| `cs.account.me()`, `.usage()`, `.rotate_key()` | your plan, usage, keys | 0 |
+| `cs.billing.plans()`, `.create_invoice(...)`, `.wait_for_payment(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. `to_text` turns them into plain text:
+
+```python
+from coinscan import CoinScan, to_text
+
+cs = CoinScan()
+print(to_text(cs.subscan.dev("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")))
+```
+
+## Images
+
+```python
+from pathlib import Path
+
+Path("chart.png").write_bytes(cs.chart("solana", "PAIR_ADDRESS", timeframe="hour", plot_type="ta"))
+
+bubble = cs.subscan.bubble_map("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")
+if bubble["image"]:
+    Path("bubble.png").write_bytes(bubble["image"])
+```
+
+## Credits, limits and errors
+
+`cs.last_usage` holds the usage headers of the last metered call: `cost`, `limit`, `remaining`, `reset` (next 00:00 UTC), `rate_limit`, `rate_remaining`.
+
+```python
+from coinscan import CoinScan, QuotaExceededError, NotFoundError, UpstreamTimeoutError
+
+cs = CoinScan()
+try:
+    scan = cs.scan("So11111111111111111111111111111111111111112")
+except NotFoundError:
+    print("no such token")
+except QuotaExceededError as e:
+    print("out of credits until", e.reset_at, "upgrade:", e.upgrade_url)
+except UpstreamTimeoutError:
+    print("a data provider was slow; try again")
+```
+
+| exception | 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 automatically, then raised; has `retry_after`) |
+| `QuotaExceededError` | 429 daily credits spent (`reset_at`, `upgrade_url`) |
+| `UpstreamTimeoutError` | a 45 s upstream deadline passed |
+| `InternalServerError` | 5xx (502/503/504 retried; credits are refunded) |
+| `APIConnectionError`, `APITimeoutError` | network problems |
+
+All inherit from `CoinScanError`. Retries: `CoinScan(max_retries=2)` by default; `0` turns them off. The default timeout is 90 s because a scan can take up to 60.
+
+## Paying from code
+
+```python
+cs = CoinScan()
+inv = cs.billing.create_invoice("starter", chain="solana", token="USDC")
+print(f"send exactly {inv['amount']} {inv['token']} to {inv['pay_to']}")
+print(inv["payment_uri"])                     # Solana Pay / EIP-681 link
+paid = cs.billing.wait_for_payment(inv["id"])
+print(paid["status"], paid.get("plan_expires_at"))
+```
+
+## Command line
+
+```bash
+export COINSCAN_API_KEY=cs_live_...
+coinscan scan 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
+coinscan holders 6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
+coinscan chart solana PAIR_ADDRESS --plot-type ta > chart.png
+coinscan me
+```
+
+## Configuration
+
+| setting | argument | environment variable | default |
+|-|-|-|-|
+| API key | `CoinScan(api_key)` | `COINSCAN_API_KEY` | none |
+| base URL | `base_url=` | `COINSCAN_BASE_URL` | `https://api.coinscan.tech` |
+| timeout | `timeout=` | | 90 s |
+| retries | `max_retries=` | | 2 |
+| HTTP client | `http_client=httpx.Client(...)` | | one per client |
+
+## 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.

coinscan_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "coinscan-sdk"
+dynamic = ["version"]
+description = "Official Python client for the CoinScan API: token scans, holders, bubble maps, wallets, charts and market data for Solana, Ethereum, BSC and Base."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "PIRB", email = "contact@pirb.tech" }]
+keywords = ["crypto", "token scanner", "solana", "ethereum", "bsc", "base", "pump.fun", "rug check", "honeypot", "api", "sdk", "coinscan"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.24,<1",
+  "typing_extensions>=4.5; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://coinscan.tech"
+Documentation = "https://coinscan.tech/docs/sdks"
+"API reference" = "https://coinscan.tech/docs/reference"
+Pricing = "https://coinscan.tech/pricing"
+
+[project.scripts]
+coinscan = "coinscan.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.version]
+path = "src/coinscan/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coinscan"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

coinscan_sdk-0.1.0/scripts/gen_async.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Generate src/coinscan/_async.py from src/coinscan/_sync.py.
+
+    python scripts/gen_async.py          # write
+    python scripts/gen_async.py --check  # exit 1 if _async.py is stale (CI)
+"""
+import re
+import sys
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent.parent / "src" / "coinscan"
+SRC = PKG / "_sync.py"
+DST = PKG / "_async.py"
+
+CLASSES = ["CoinScan", "Subscan", "Wallet", "Market", "Launchpads", "AccountAPI", "Billing"]
+NON_IO = {"__init__", "__repr__", "_headers", "__enter__", "__exit__"}
+
+
+def convert(src: str) -> str:
+    out = src
+    out = out.replace('"""Synchronous client.', '"""Asynchronous client. GENERATED from _sync.py by scripts/gen_async.py; do not edit.', 1)
+    out = out.replace("import time\n", "import asyncio\nimport time\n", 1)
+    out = out.replace("httpx.Client", "httpx.AsyncClient")
+    out = out.replace("Synchronous CoinScan API client.", "Asynchronous CoinScan API client.")
+    out = out.replace("        from coinscan import CoinScan\n        cs = CoinScan()",
+                      "        from coinscan import AsyncCoinScan\n        cs = AsyncCoinScan()")
+    out = out.replace("scan = cs.scan(", "scan = await cs.scan(")
+
+    for name in CLASSES:
+        out = re.sub(rf"\b{name}\b", f"Async{name}", out)
+    # Keep the product name in docs and messages.
+    out = out.replace("AsyncCoinScan API", "CoinScan API")
+
+    def _def(m):
+        indent, name = m.group(1), m.group(2)
+        if name in NON_IO:
+            return m.group(0)
+        return f"{indent}async def {name}("
+    out = re.sub(r"^(\s*)def (\w+)\(", _def, out, flags=re.M)
+
+    out = out.replace("def __enter__(self):", "async def __aenter__(self):")
+    out = out.replace("def __exit__(self, *exc):\n        self.close()",
+                      "async def __aexit__(self, *exc):\n        await self.close()")
+    out = out.replace("self._http.close()", "await self._http.aclose()")
+    out = out.replace("self._http.request(", "await self._http.request(")
+    out = out.replace("time.sleep(", "await asyncio.sleep(")
+    out = re.sub(r"(?<!await )self\._c\._request\(", "await self._c._request(", out)
+    out = re.sub(r"(?<![\w.])(?<!await )self\._request\(", "await self._request(", out)
+    out = out.replace("invoice = self.get_invoice(", "invoice = await self.get_invoice(")
+    out = out.replace("with cls(api_key=\"\", base_url=base_url) as c:\n            return c.account.signup(",
+                      "async with cls(api_key=\"\", base_url=base_url) as c:\n            return await c.account.signup(")
+    # A function that only defines the request (helpers like _evm_body, _gas) stays sync.
+    out = out.replace("async def _evm_body(", "def _evm_body(").replace("async def _gas(", "def _gas(")
+    return out
+
+
+def main() -> int:
+    generated = convert(SRC.read_text())
+    if "--check" in sys.argv:
+        if not DST.exists() or DST.read_text() != generated:
+            print("_async.py is stale: run python scripts/gen_async.py", file=sys.stderr)
+            return 1
+        return 0
+    DST.write_text(generated)
+    print(f"wrote {DST.relative_to(PKG.parent.parent)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

coinscan_sdk-0.1.0/src/coinscan/__init__.py

@@ -0,0 +1,28 @@
+"""Official Python client for the CoinScan API (https://coinscan.tech).
+
+    from coinscan import CoinScan
+
+    cs = CoinScan()  # reads COINSCAN_API_KEY
+    scan = cs.scan("6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN")
+    print(scan["holders"]["bundle_pct"], scan["ai_predictions"]["p_rug"])
+"""
+from coinscan._async import (
+    AsyncAccountAPI, AsyncBilling, AsyncCoinScan, AsyncLaunchpads, AsyncMarket, AsyncSubscan, AsyncWallet,
+)
+from coinscan._base import DEFAULT_BASE_URL, Usage, to_text
+from coinscan._errors import (
+    APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError, BadRequestError, CoinScanError,
+    ConflictError, InternalServerError, NotFoundError, PermissionDeniedError, QuotaExceededError, RateLimitError,
+    UpstreamTimeoutError, ValidationError,
+)
+from coinscan._sync import AccountAPI, Billing, CoinScan, Launchpads, Market, Subscan, Wallet
+from coinscan._version import __version__
+
+__all__ = [
+    "CoinScan", "AsyncCoinScan", "Usage", "to_text", "DEFAULT_BASE_URL", "__version__",
+    "Subscan", "Wallet", "Market", "Launchpads", "AccountAPI", "Billing",
+    "AsyncSubscan", "AsyncWallet", "AsyncMarket", "AsyncLaunchpads", "AsyncAccountAPI", "AsyncBilling",
+    "CoinScanError", "APIConnectionError", "APITimeoutError", "APIStatusError", "BadRequestError",
+    "AuthenticationError", "PermissionDeniedError", "NotFoundError", "ConflictError", "ValidationError",
+    "RateLimitError", "QuotaExceededError", "InternalServerError", "UpstreamTimeoutError",
+]

coinscan_sdk-0.1.0/src/coinscan/__main__.py

@@ -0,0 +1,92 @@
+"""Command line: `coinscan scan <address>`, `coinscan me`, ... prints JSON.
+
+The key comes from --api-key or COINSCAN_API_KEY.
+"""
+import argparse
+import json
+import sys
+
+from coinscan._base import to_text
+from coinscan._errors import CoinScanError
+from coinscan._sync import CoinScan
+
+
+def _print(value, text: bool = False) -> None:
+    if isinstance(value, (bytes, bytearray)):
+        sys.stdout.buffer.write(value)
+        return
+    if text and isinstance(value, (str, list)):
+        print(to_text(value))
+        return
+    print(json.dumps(value, indent=2, ensure_ascii=False, default=str))
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="coinscan", description="CoinScan API from the command line.")
+    p.add_argument("--api-key", help="defaults to $COINSCAN_API_KEY")
+    p.add_argument("--base-url", help="defaults to $COINSCAN_BASE_URL or https://api.coinscan.tech")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="full token scan (10 credits)")
+    s.add_argument("address")
+    s.add_argument("--chain")
+    d = sub.add_parser("detect", help="chain of an address (free)")
+    d.add_argument("address")
+    t = sub.add_parser("ticker", help="addresses behind a ticker (2 credits)")
+    t.add_argument("query")
+    h = sub.add_parser("holders", help="top holders (1 credit)")
+    h.add_argument("address")
+    h.add_argument("--chain", default="solana")
+    dv = sub.add_parser("dev", help="deployer history (4 credits)")
+    dv.add_argument("address")
+    dv.add_argument("--chain")
+    w = sub.add_parser("pnl", help="wallet PnL report (5 credits)")
+    w.add_argument("wallet")
+    w.add_argument("--chain", default="solana")
+    c = sub.add_parser("chart", help="PNG chart to stdout (3 credits): coinscan chart solana <pair> > chart.png")
+    c.add_argument("network")
+    c.add_argument("pool_address")
+    c.add_argument("--timeframe", default="hour")
+    c.add_argument("--plot-type", default="ohlcv")
+    sub.add_parser("macro", help="market snapshot (free)")
+    sub.add_parser("me", help="your plan and today's usage")
+    sub.add_parser("plans", help="plans and route costs")
+    su = sub.add_parser("signup", help="create a free account and print its key")
+    su.add_argument("--email")
+
+    a = p.parse_args(argv)
+    try:
+        if a.cmd == "signup":
+            _print(CoinScan.signup(email=a.email, base_url=a.base_url))
+            return 0
+        with CoinScan(a.api_key, base_url=a.base_url) as cs:
+            if a.cmd == "scan":
+                _print(cs.scan(a.address, chain=a.chain))
+            elif a.cmd == "detect":
+                _print(cs.detect(a.address))
+            elif a.cmd == "ticker":
+                _print(cs.resolve_ticker(a.query))
+            elif a.cmd == "holders":
+                _print(cs.subscan.holders(a.address, chain=a.chain), text=True)
+            elif a.cmd == "dev":
+                _print(cs.subscan.dev(a.address, chain=a.chain), text=True)
+            elif a.cmd == "pnl":
+                _print(cs.wallet.pnl(a.wallet, chain=a.chain), text=True)
+            elif a.cmd == "chart":
+                _print(cs.chart(a.network, a.pool_address, timeframe=a.timeframe, plot_type=a.plot_type))
+            elif a.cmd == "macro":
+                _print(cs.market.macro())
+            elif a.cmd == "me":
+                _print(cs.account.me())
+            elif a.cmd == "plans":
+                _print(cs.billing.plans())
+            if cs.last_usage and cs.last_usage.remaining is not None:
+                print(f"{cs.last_usage.remaining} credits left today", file=sys.stderr)
+        return 0
+    except CoinScanError as e:
+        print(f"error: {e.message}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())