cryptoetf 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cryptoetf.today
+
+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,104 @@
-# Temporary Holding Version
+# CryptoETF — TypeScript SDK for spot crypto ETF flows
 
-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.
+[![npm](https://img.shields.io/npm/v/cryptoetf?color=cb3837&logo=npm)](https://www.npmjs.com/package/cryptoetf)
+
+The official client for the [CryptoETF API](https://docs.cryptoetf.today): daily net
+flows of every US-listed spot crypto ETF, fund by fund, plus fund AUM, the CEFI
+sentiment index and coin prices. Data by [cryptoetf.today](https://cryptoetf.today).
+
+Sixteen assets: **BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB,
+DOT, SUI, NEAR, TRX, ZEC**. Zero dependencies, fully typed, Node 18+, Deno, Bun
+and modern browsers.
+
+## Install
+
+```bash
+npm install cryptoetf
+```
+
+## Get an API key
+
+Sign in at [cryptoetf.today](https://cryptoetf.today/en/profile) and create a key
+in **Profile → For developers**. It is free.
+
+## Quick start
+
+```ts
+import { CryptoETF } from "cryptoetf";
+
+const etf = new CryptoETF({ apiKey: process.env.CRYPTOETF_API_KEY });
+
+// Latest daily net flow for every asset, US$ millions
+const { assets } = await etf.flows.summary();
+for (const a of assets) console.log(a.symbol, a.date, a.netFlowUsdM);
+
+// Bitcoin ETFs fund by fund
+const btc = await etf.flows.funds("btc");
+const lastDay = btc.days.at(-1);
+console.log(lastDay?.funds.map((f) => `${f.ticker} ${f.netFlowUsdM}`));
+```
+
+If `apiKey` is omitted, the client reads `CRYPTOETF_API_KEY` from the environment.
+
+## Methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `flows.summary()` | `GET /v1/flows/summary` | Latest net flow per asset |
+| `flows.asset(asset)` | `GET /v1/flows/{asset}` | Daily net flows of one asset |
+| `flows.funds(asset)` | `GET /v1/flows/{asset}/funds` | Daily net flows of one asset, per fund |
+| `funds(asset?)` | `GET /v1/funds` | Fund directory with AUM, fees, coins held |
+| `cefi()` | `GET /v1/index/cefi` | CEFI sentiment index (0–100) and its history |
+| `tickers()` | `GET /v1/tickers` | Tracked assets |
+| `prices()` | `GET /v1/prices` | Spot prices of the 16 coins |
+| `weekly()` | `GET /v1/analytics/weekly` | Seven-day totals per asset |
+
+`asset` is a code such as `btc`, `eth`, `sol`, `hype` or a full name such as
+`bitcoin`. All values are net US$ millions: positive = inflow, negative = outflow.
+Full field reference: [docs.cryptoetf.today](https://docs.cryptoetf.today).
+
+## Errors and limits
+
+Every failed call throws `CryptoETFError` with `status`, an optional `code` and,
+on HTTP 429, `retryAfter` in seconds:
+
+```ts
+import { CryptoETFError } from "cryptoetf";
+
+try {
+  await etf.prices();
+} catch (e) {
+  if (e instanceof CryptoETFError && e.status === 429) {
+    console.log(`rate limited, retry in ${e.retryAfter}s`);
+  }
+}
+```
+
+- **Rate limit:** 120 requests per minute per key. The latest limit headers are
+  available as `etf.rateLimit`.
+- **History:** the free tier covers the **last 30 days**. Full history will be
+  available on a paid plan.
+- **Freshness:** a trading day appears the next morning (UTC), before the US
+  open. The newest day can be revised once later that day. SUI funds arrive a
+  day later.
+
+## Options
+
+```ts
+new CryptoETF({
+  apiKey: "…",       // default: process.env.CRYPTOETF_API_KEY
+  timeoutMs: 15000,  // per request
+  baseUrl: "https://api.cryptoetf.today/api/v1",
+  fetch: customFetch,
+});
+```
+
+## Related
+
+- **Python SDK:** [cryptoetf on PyPI](https://pypi.org/project/cryptoetf/), same methods.
+- **No-code access for AI agents:** the hosted MCP server at
+  `https://mcp.cryptoetf.today/api/mcp`
+  ([@zerosix-studio/cryptoetf-mcp](https://www.npmjs.com/package/@zerosix-studio/cryptoetf-mcp)).
+- **Embeddable widgets:** [cryptoetf.today/en/crypto-etf-widgets](https://cryptoetf.today/en/crypto-etf-widgets)
+
+Not investment advice. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import type { AssetCode, AssetFlows, AssetFundFlows, CefiIndex, Funds, FlowsSummary, Prices, RateLimit, Ticker, WeeklyAnalytics } from "./types.js";
+export type * from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.cryptoetf.today/api/v1";
+export interface CryptoETFOptions {
+    /** API key from https://cryptoetf.today/en/profile. Defaults to the `CRYPTOETF_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Override the API root, e.g. for a proxy. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 15 000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (tests, proxies, older runtimes). */
+    fetch?: typeof fetch;
+}
+/** Error returned by the API (4xx/5xx) or raised by the client (timeout, network). */
+export declare class CryptoETFError extends Error {
+    /** HTTP status; 0 for network errors and timeouts. */
+    readonly status: number;
+    /** Machine-readable code when the API sends one, e.g. `api_key_suspended`. */
+    readonly code?: string;
+    /** Seconds to wait before retrying, on 429. */
+    readonly retryAfter?: number;
+    constructor(message: string, status: number, code?: string, retryAfter?: number);
+}
+/**
+ * Client for the CryptoETF public API: daily net flows of US spot crypto ETFs
+ * for 16 assets, fund by fund, plus fund AUM, the CEFI sentiment index and coin prices.
+ *
+ * ```ts
+ * const etf = new CryptoETF({ apiKey: "…" });
+ * const { assets } = await etf.flows.summary();
+ * ```
+ */
+export declare class CryptoETF {
+    /** Rate-limit headers of the most recent response, or null before the first call. */
+    rateLimit: RateLimit | null;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: CryptoETFOptions);
+    /** Daily net flows. */
+    readonly flows: {
+        /** Latest daily net flow for every asset. */
+        summary: () => Promise<FlowsSummary>;
+        /** Daily net flows of one asset over the history window (30 days on the free tier). */
+        asset: (asset: AssetCode | (string & {})) => Promise<AssetFlows>;
+        /** Daily net flows of one asset, fund by fund. */
+        funds: (asset: AssetCode | (string & {})) => Promise<AssetFundFlows>;
+    };
+    /** Fund directory with assets under management; all 16 assets unless `asset` is given. */
+    funds(asset?: AssetCode | (string & {})): Promise<Funds>;
+    /** CEFI — Crypto ETF Flow Index, a 0–100 sentiment gauge, with its recent history. */
+    cefi(): Promise<CefiIndex>;
+    /** Assets the API tracks. */
+    tickers(): Promise<Ticker[]>;
+    /** Spot prices of the 16 coins. */
+    prices(): Promise<Prices>;
+    /** Seven-day flow totals per asset. */
+    weekly(): Promise<WeeklyAnalytics>;
+    private get;
+}
+export default CryptoETF;

package/dist/index.js

@@ -0,0 +1,119 @@
+export const DEFAULT_BASE_URL = "https://api.cryptoetf.today/api/v1";
+/** Error returned by the API (4xx/5xx) or raised by the client (timeout, network). */
+export class CryptoETFError extends Error {
+    /** HTTP status; 0 for network errors and timeouts. */
+    status;
+    /** Machine-readable code when the API sends one, e.g. `api_key_suspended`. */
+    code;
+    /** Seconds to wait before retrying, on 429. */
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
+        super(message);
+        this.name = "CryptoETFError";
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+    }
+}
+function envKey() {
+    const p = globalThis.process;
+    return p?.env?.CRYPTOETF_API_KEY;
+}
+/**
+ * Client for the CryptoETF public API: daily net flows of US spot crypto ETFs
+ * for 16 assets, fund by fund, plus fund AUM, the CEFI sentiment index and coin prices.
+ *
+ * ```ts
+ * const etf = new CryptoETF({ apiKey: "…" });
+ * const { assets } = await etf.flows.summary();
+ * ```
+ */
+export class CryptoETF {
+    /** Rate-limit headers of the most recent response, or null before the first call. */
+    rateLimit = null;
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options = {}) {
+        const key = options.apiKey ?? envKey();
+        if (!key) {
+            throw new CryptoETFError("API key required. Get a free key at https://cryptoetf.today/en/profile and pass it as { apiKey } or set CRYPTOETF_API_KEY.", 401);
+        }
+        this.apiKey = key;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new CryptoETFError("No fetch available: use Node 18+ or pass { fetch }.", 0);
+        this.fetchImpl = f.bind(globalThis);
+    }
+    /** Daily net flows. */
+    flows = {
+        /** Latest daily net flow for every asset. */
+        summary: () => this.get("/flows/summary"),
+        /** Daily net flows of one asset over the history window (30 days on the free tier). */
+        asset: (asset) => this.get(`/flows/${encodeURIComponent(asset)}`),
+        /** Daily net flows of one asset, fund by fund. */
+        funds: (asset) => this.get(`/flows/${encodeURIComponent(asset)}/funds`),
+    };
+    /** Fund directory with assets under management; all 16 assets unless `asset` is given. */
+    funds(asset) {
+        return this.get("/funds", asset ? { asset } : undefined);
+    }
+    /** CEFI — Crypto ETF Flow Index, a 0–100 sentiment gauge, with its recent history. */
+    cefi() {
+        return this.get("/index/cefi");
+    }
+    /** Assets the API tracks. */
+    tickers() {
+        return this.get("/tickers");
+    }
+    /** Spot prices of the 16 coins. */
+    prices() {
+        return this.get("/prices");
+    }
+    /** Seven-day flow totals per asset. */
+    weekly() {
+        return this.get("/analytics/weekly");
+    }
+    async get(path, query) {
+        const url = new URL(this.baseUrl + path);
+        if (query)
+            for (const [k, v] of Object.entries(query))
+                url.searchParams.set(k, v);
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json" },
+                signal: ctrl.signal,
+            });
+        }
+        catch (err) {
+            const timedOut = err?.name === "AbortError";
+            throw new CryptoETFError(timedOut ? `Request timed out after ${this.timeoutMs} ms` : `Network error: ${err?.message ?? err}`, 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const limit = Number(res.headers.get("x-ratelimit-limit"));
+        if (limit) {
+            this.rateLimit = {
+                limit,
+                remaining: Number(res.headers.get("x-ratelimit-remaining")),
+                reset: Number(res.headers.get("x-ratelimit-reset")),
+            };
+        }
+        const body = await res.json().catch(() => null);
+        if (!res.ok) {
+            const b = (body ?? {});
+            const message = Array.isArray(b.message) ? b.message.join("; ") : typeof b.message === "string" ? b.message : res.statusText || `HTTP ${res.status}`;
+            const retry = Number(res.headers.get("retry-after"));
+            throw new CryptoETFError(message, res.status, typeof b.code === "string" ? b.code : undefined, retry || undefined);
+        }
+        return body;
+    }
+}
+export default CryptoETF;

package/dist/types.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Response shapes of the CryptoETF public API v1 (https://docs.cryptoetf.today).
+ * Flow values are net US$ millions, rounded to one decimal: positive = inflow,
+ * negative = outflow. Dates are `YYYY-MM-DD` (UTC trading days), timestamps ISO 8601.
+ */
+/** Asset accepted by the per-asset endpoints. Case-insensitive; full names (`bitcoin`, `solana`, …) and `hype` also work. */
+export type AssetCode = "btc" | "eth" | "sol" | "xrp" | "hyp" | "doge" | "link" | "avax" | "hbar" | "ltc" | "bnb" | "dot" | "sui" | "near" | "trx" | "zec";
+export interface FlowsSummaryItem {
+    /** Uppercase ticker of the coin, e.g. `BTC`. */
+    symbol: string;
+    /** Internal asset id, e.g. `bitcoin`, `hyp`. */
+    asset: string;
+    /** Latest trading day with data, or null if the asset has none yet. */
+    date: string | null;
+    netFlowUsdM: number;
+}
+export interface FlowsSummary {
+    assets: FlowsSummaryItem[];
+    updatedAt: string;
+}
+export interface FlowPoint {
+    date: string;
+    netFlowUsdM: number;
+}
+export interface AssetFlows {
+    symbol: string;
+    asset: string;
+    /** History window in days (30 on the free tier). */
+    windowDays: number;
+    days: FlowPoint[];
+    updatedAt: string;
+}
+export interface FundFlow {
+    ticker: string;
+    issuer: string;
+    /** Null when the fund has not reported this day yet. */
+    netFlowUsdM: number | null;
+}
+export interface FundDay {
+    date: string;
+    totalUsdM: number;
+    funds: FundFlow[];
+}
+export interface AssetFundFlows {
+    symbol: string;
+    asset: string;
+    windowDays: number;
+    days: FundDay[];
+    updatedAt: string;
+}
+export interface AssetNetAssets {
+    symbol: string;
+    asset: string;
+    totalNetAssetsUsdM: number | null;
+    date: string | null;
+}
+export interface Fund {
+    ticker: string;
+    name: string;
+    issuer: string;
+    symbol: string;
+    asset: string;
+    exchange: string;
+    listedAt: string;
+    /** Sponsor fee, percent per year. */
+    sponsorFeePct: number | null;
+    netAssetsUsdM: number | null;
+    coinsHeld: number | null;
+    coinsHeldDate: string | null;
+    netAssetsDate: string | null;
+    netAssetsBasis: "reported" | "repriced" | "estimated" | null;
+}
+export interface Funds {
+    assets: AssetNetAssets[];
+    funds: Fund[];
+    updatedAt: string;
+}
+export interface CefiComponents {
+    flow: number;
+    trend: number;
+    breadth: number;
+}
+export interface IndexPoint {
+    date: string;
+    value: number;
+}
+export interface CefiIndex {
+    index: string;
+    /** 0–100: below 25 extreme fear, above 75 extreme greed. */
+    current: number;
+    components: CefiComponents | null;
+    date: string;
+    windowDays: number;
+    history: IndexPoint[];
+}
+export interface Ticker {
+    symbol: string;
+    asset: string;
+    name: string;
+}
+export interface Price {
+    symbol: string;
+    priceUsd: number;
+    change24hPct: number;
+}
+export interface Prices {
+    prices: Price[];
+    updatedAt: string;
+}
+export interface WeeklyAsset {
+    symbol: string;
+    asset: string;
+    netFlowUsdM: number;
+    avgDailyUsdM: number;
+    positiveDays: number;
+    negativeDays: number;
+}
+export interface WeeklyAnalytics {
+    /** First day of the seven-day window. */
+    from: string;
+    /** Last day of the window (today, UTC). */
+    to: string;
+    assets: WeeklyAsset[];
+}
+/** Rate-limit state taken from the headers of the latest response. */
+export interface RateLimit {
+    limit: number;
+    remaining: number;
+    /** Unix time (seconds) when the current window resets. */
+    reset: number;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Response shapes of the CryptoETF public API v1 (https://docs.cryptoetf.today).
+ * Flow values are net US$ millions, rounded to one decimal: positive = inflow,
+ * negative = outflow. Dates are `YYYY-MM-DD` (UTC trading days), timestamps ISO 8601.
+ */
+export {};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "cryptoetf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Official TypeScript client for the CryptoETF API: daily net flows of US spot crypto ETFs for 16 assets (BTC, ETH, SOL, XRP, HYPE, DOGE, LINK, AVAX, HBAR, LTC, BNB, DOT, SUI, NEAR, TRX, ZEC), fund by fund, plus fund AUM, the CEFI sentiment index and coin prices. Zero dependencies.",
+  "keywords": [
+    "crypto",
+    "etf",
+    "bitcoin-etf",
+    "ethereum-etf",
+    "etf-flows",
+    "spot-etf",
+    "ibit",
+    "api",
+    "sdk"
+  ],
+  "homepage": "https://cryptoetf.today/en/api",
+  "bugs": {
+    "url": "https://github.com/zerosix-studio/cryptoetf-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerosix-studio/cryptoetf-sdk.git",
+    "directory": "typescript"
+  },
+  "license": "MIT",
+  "author": "cryptoetf.today",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}