Package Exports

@coinstats/open-api
@coinstats/open-api/openapi.json

Readme

CoinStats Public API SDK for Node.js

Official TypeScript SDK for the CoinStats Public API. Use one client for market data, wallet balances, portfolio analytics, exchange connections, NFT data, crypto news, and usage credits.

npm install @coinstats/open-api

import { CoinStatsClient } from "@coinstats/open-api";

const coinstats = new CoinStatsClient({
  apiKey: process.env.COINSTATS_API_KEY!
});

const coins = await coinstats.api.getCoins({
  limit: 10,
  currency: "USD",
  sortBy: "marketCap",
  sortDir: "desc"
});

console.log(coins);

Highlights

TypeScript-first client generated from the current CoinStats OpenAPI schema.
56 public API operations exposed as friendly methods under client.api.
Portfolio helpers exposed under client.user.
Uses the native Node 20+ network runtime internally.
Structured CoinStatsApiError for non-2xx responses.

Authentication

Create an API key from the CoinStats API dashboard, then pass it to the SDK:

const coinstats = new CoinStatsClient({
  apiKey: process.env.COINSTATS_API_KEY!
});

Keep API keys on your server. Do not expose them in frontend code, mobile apps, public repositories, logs, or browser bundles.

Client Options

Most developers only need an API key. You can also set a request timeout:

const coinstats = new CoinStatsClient({
  apiKey: process.env.COINSTATS_API_KEY!,
  timeoutMs: 15_000
});

The SDK always calls the production CoinStats Public API at https://openapiv1.coinstats.app.

Option	Required	Description
`apiKey`	Yes	CoinStats Public API key sent as `X-API-KEY`.
`timeoutMs`	No	Aborts the request after the given number of milliseconds.

API Examples

Generated API methods accept one options object. Path fields, query fields, and supported header fields go in that same object. The complete public REST API lives under coinstats.api; portfolio helpers also live under coinstats.user.

Market Data

const bitcoin = await coinstats.api.getCoinById({
  coinId: "bitcoin",
  currency: "USD"
});

const chart = await coinstats.api.getCoinChartById({
  coinId: "bitcoin",
  period: "1m"
});

const tickers = await coinstats.api.getTickerMarkets({
  exchange: "binance",
  fromCoin: "BTC",
  toCoin: "USDT",
  limit: 25
});

Wallet Data

const blockchains = await coinstats.api.getBlockchains();

const balance = await coinstats.api.getWalletBalance({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  connectionId: "ethereum"
});

await coinstats.api.transactionsSync({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  connectionId: "ethereum"
});

const transactions = await coinstats.api.getWalletTransactions({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  connectionId: "ethereum",
  limit: 50
});

Exchange Data

Use getExchanges() to check the supported connectionId values and required credential fields for each exchange. Keep exchange API credentials on your server and prefer read-only exchange keys.

const exchanges = await coinstats.api.getExchanges();

const binanceBalance = await coinstats.api.getExchangeBalance({
  connectionId: "binance",
  connectionFields: {
    apiKey: process.env.BINANCE_API_KEY!,
    apiSecret: process.env.BINANCE_API_SECRET!
  }
});

console.log(binanceBalance.balances);
console.log(binanceBalance.portfolio.id);

Portfolio Connections

const connected = await coinstats.user.connectPortfolioWallet({
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  connectionId: "ethereum",
  name: "Main Wallet"
});

const value = await coinstats.user.getPortfolioValue({
  portfolioId: connected.portfolioId
});

const status = await coinstats.user.getPortfolioSyncStatus({
  portfolioId: connected.portfolioId
});

CoinStats User Portfolio APIs

Use coinstats.user for portfolio APIs. When you provide a CoinStats user sharetoken or passcode, the SDK sends those values as headers internally.

const value = await coinstats.user.getPortfolioValue({
  sharetoken: "shared-portfolio-token",
  passcode: "optional-passcode",
  currency: "USD"
});

const coins = await coinstats.user.getPortfolioCoins({
  limit: 100,
  includeRiskScore: "true",
  sharetoken: "shared-portfolio-token",
  passcode: "optional-passcode"
});

const transactions = await coinstats.user.getPortfolioTransactions({
  sharetoken: "shared-portfolio-token",
  limit: 50
});

News, NFTs, Insights, and Usage

const news = await coinstats.api.getNews({ limit: 10 });
const trendingNfts = await coinstats.api.getTrendingNfts({ limit: 20 });
const fearAndGreed = await coinstats.api.fearAndGreed();
const credits = await coinstats.api.getCreditUsage();

Function Reference

Client

Function	Description
`new CoinStatsClient({ apiKey, timeoutMs? })`	Create a Node.js client for the CoinStats Public API.
`coinstats.request<T>()`	Typed raw request escape hatch for new or custom endpoints.
`coinstats.api.*`	Full generated public REST API surface; portfolio methods are documented under `coinstats.user`.
`coinstats.user.*`	Portfolio convenience API.

`coinstats.api`

Portfolio endpoints are documented under coinstats.user below.

Market Data

Function	Endpoint
`getCoins()`	`GET /coins`
`getCoinById()`	`GET /coins/{coinId}`
`getCoinChartById()`	`GET /coins/{coinId}/charts`
`getCoinsCharts()`	`GET /coins/charts`
`getCoinAvgPrice()`	`GET /coins/price/avg`
`getCoinExchangePrice()`	`GET /coins/price/exchange`
`getTickerExchanges()`	`GET /tickers/exchanges`
`getTickerMarkets()`	`GET /tickers/markets`
`getFiatCurrencies()`	`GET /fiats`
`getCurrencies()`	`GET /currencies`
`getMarketCap()`	`GET /markets`

Wallet Data

Function	Endpoint
`getBlockchains()`	`GET /wallet/blockchains`
`getWalletBalance()`	`GET /wallet/balance`
`getWalletBalanceMany()`	`GET /wallet/balance/many`
`transactionsSync()`	`PATCH /wallet/transactions`
`getWalletTransactions()`	`GET /wallet/transactions`
`getWalletSyncStatus()`	`GET /wallet/status`
`getWalletPl()`	`GET /wallet/pl`
`walletChart()`	`GET /wallet/chart`
`walletCharts()`	`GET /wallet/charts`
`getWalletDefi()`	`GET /wallet/defi`

Exchange Data

Function	Endpoint
`getExchanges()`	`GET /exchange/support`
`getExchangeBalance()`	`POST /exchange/balance`
`getExchangeSyncStatus()`	`GET /exchange/status`
`getExchangeTransactions()`	`GET /exchange/transactions`
`getExchangePl()`	`GET /exchange/pl`
`getExchangeChart()`	`GET /exchange/chart`
`exchangeSyncStatus()`	`PATCH /exchange/sync`

News, NFTs, Insights, and System

Function	Endpoint
`getNewsSources()`	`GET /news/sources`
`getNews()`	`GET /news`
`getNewsByType()`	`GET /news/type/{type}`
`getNewsById()`	`GET /news/{id}`
`getTrendingNfts()`	`GET /nft/trending`
`getNftsByWallet()`	`GET /nft/wallet/{address}/assets`
`getNftCollectionByAddress()`	`GET /nft/collection/{collectionAddress}`
`getNftCollectionAssetsByAddress()`	`GET /nft/{collectionAddress}/assets`
`getNftCollectionAssetByTokenid()`	`GET /nft/{collectionAddress}/asset/{tokenId}`
`btcDominance()`	`GET /insights/btc-dominance`
`fearAndGreed()`	`GET /insights/fear-and-greed`
`fearAndGreedChart()`	`GET /insights/fear-and-greed/chart`
`rainbowChart()`	`GET /insights/rainbow-chart/{coinId}`
`getCreditUsage()`	`GET /usage/credits`
`getApiStatus()`	`GET /status`

`coinstats.user`

Use these methods for portfolio connections, portfolio reads, portfolio sync, deletion, and CoinStats user share-token flows. sharetoken and passcode are sent as headers internally.

Function	Endpoint
`connectPortfolioWallet()`	`POST /portfolio/wallet`
`connectPortfolioExchange()`	`POST /portfolio/exchange`
`getPortfolioList()`	`GET /portfolio/list`
`getPortfolioValue()`	`GET /portfolio/value`
`getPortfolioCoins()`	`GET /portfolio/coins`
`getPortfolioChart()`	`GET /portfolio/chart`
`getPortfolioTransactions()`	`GET /portfolio/transactions`
`addPortfolioTransaction()`	`POST /portfolio/transaction`
`getPortfolioDefi()`	`GET /portfolio/defi`
`getPortfolioSnapshotItems()`	`GET /portfolio/snapshot/items`
`getPortfolioSyncStatus()`	`GET /portfolio/status`
`syncPortfolio()`	`PATCH /portfolio/sync`
`deletePortfolio()`	`DELETE /portfolio/{portfolioId}`

Raw Requests

Use client.request<T>() for new endpoints before the SDK is regenerated:

const data = await coinstats.request<{ status: string }>({
  method: "GET",
  path: "/status"
});

Path parameters are encoded safely:

await coinstats.request({
  method: "GET",
  path: "/coins/{coinId}",
  pathParams: { coinId: "bitcoin" },
  query: { currency: "USD" }
});

Array query values are serialized as comma-separated values, matching the CoinStats API style:

await coinstats.api.getCoins({
  coinIds: "bitcoin,ethereum,solana"
});

await coinstats.request({
  method: "GET",
  path: "/coins",
  query: { coinIds: ["bitcoin", "ethereum", "solana"] }
});

Error Handling

Non-2xx responses throw CoinStatsApiError.

import { CoinStatsApiError } from "@coinstats/open-api";

try {
  await coinstats.api.getCoins();
} catch (error) {
  if (error instanceof CoinStatsApiError) {
    console.error(error.status);
    console.error(error.message);
    console.error(error.requestId);
    console.error(error.path);
    console.error(error.body);
  }
}

The error object includes:

Property	Description
`status`	HTTP status code, or `0` for network/timeout failures.
`message`	API error message when available.
`requestId`	CoinStats request ID when returned by the API.
`path`	API path associated with the failure.
`body`	Parsed JSON error body, text body, or `undefined`.

TypeScript Types

OpenAPI-generated types are exported for advanced usage:

import type { components, operations, paths } from "@coinstats/open-api";

type Coin = components["schemas"]["CoinListResponseItemDto"];
type GetCoinsOperation = operations["get-coins"];
type ApiPaths = paths;

Development

npm install
npm run generate:types
npm test
npm run typecheck
npm run build
npm run check:openapi
npm run smoke

npm run check:openapi fails if openapi/openapi.json contains an operation that is not present in the SDK operation definitions.

Release Notes

0.1.0

Initial public SDK package.
Node 20+ support.
API-key authentication via X-API-KEY.
56 public CoinStats Public API operations exposed under client.api.
client.request<T>() raw escape hatch.
CoinStatsApiError structured error model.

License

MIT