# @spectrumnodes/sdk

[![npm version](https://img.shields.io/npm/v/@spectrumnodes/sdk.svg)](https://www.npmjs.com/package/@spectrumnodes/sdk)

The official TypeScript SDK for the [Spectrum Nodes](https://spectrumnodes.com) API can be found at [NPM](https://www.npmjs.com/package/@spectrumnodes/sdk).

Provides typed access to blockchain data, DeFi protocols, token prices, NFTs, and more across Spectrum-supported chains.

## What This SDK Is

This is a standard API SDK: a typed TypeScript client on top of the Spectrum Nodes JSON-RPC API.

The SDK talks to Spectrum's `POST` JSON-RPC 2.0 surface and exposes that transport through a higher-level, namespace-based TypeScript API.

It gives you:

- A single `Spectrum` client with 15 namespaces plus raw `jsonRpc()` access
- Typed request and response shapes
- Built-in retries, timeout handling, and caching
- Typed error classes and request lifecycle hooks
- ESM, CommonJS, and TypeScript declaration output

## Install

```bash
npm install @spectrumnodes/sdk
```

Requires Node.js 20+.

## Quick Start

```typescript
import { Spectrum } from '@spectrumnodes/sdk';

const spectrum = new Spectrum({
  api: 'https://spectrum-02.simplystaking.xyz/<tenant-token>/spectrumapi/v1/',
});

// Get block height
const block = await spectrum.core.getBlockHeight('ethereum');
console.log(block.height); // 19432156

// Get native balance
const balance = await spectrum.tokens.getBalance('ethereum', '0xd8dA6BF...');
console.log(balance.balance); // "1.5"

// Historical read when supported by the API
const historicalBalance = await spectrum.tokens.getBalance('ethereum', '0xd8dA6BF...', {
  blockHeight: 19834521,
});
console.log(historicalBalance.balance);

// Get best DeFi yields
const yields = await spectrum.yields.getBest({ token: 'USDC', limit: 5 });
yields.results.forEach((y) =>
  console.log(`#${y.rank} ${y.protocol} on ${y.chain}: ${y.apy.totalApy}%`),
);

// Get token price
const price = await spectrum.prices.getPrice('ETH');
console.log(price.priceUsd); // 3456.78

// Resolve ENS name
const ens = await spectrum.ens.resolve('vitalik.eth');
console.log(ens.address); // "0xd8dA6BF..."
```

## Why Use It

- Unified client for blockchain data, prices, yields, NFTs, ENS, contracts, JSON-RPC, and registry data
- Consistent method naming and trailing `RequestOptions` across namespaces
- Supports both direct per-call chain selection and a mutable default chain via `setChain()`
- Includes client-side parallel helpers, raw `jsonRpc()` access, and direct node RPC methods

## Documentation

Documentation files ship inside the installed package and are also browseable on the npm CDN. Use `@latest` for the current release or pin a version (`@1.0.2`).

Browse all docs → <https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/docs/>

- [Configuration](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/docs/configuration.md) — API credential, caching, retries, hooks
- [API Reference](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/docs/api-reference.md) — Public namespaces, raw JSON-RPC access, and method signatures
- [Examples Guide](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/docs/examples.md) — Where to find runnable usage examples by namespace
- [Error Handling](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/docs/error-handling.md) — Error types, retry behavior

After `npm install @spectrumnodes/sdk`, the same files are available locally at `node_modules/@spectrumnodes/sdk/docs/`.

## Examples

Each runnable example ships inside the installed package and is also browseable on the npm CDN. Pin a version (`@1.0.2`) for reproducibility or use `@latest` for the current release.

Browse the full directory → <https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/>

- [Getting Started](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/01-getting-started.ts)
- [Core Data](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/02-core.ts)
- [Tokens](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/03-tokens.ts)
- [Yields](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/04-yields.ts)
- [Prices](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/05-prices.ts)
- [DeFi](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/06-defi.ts)
- [NFTs](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/07-nfts.ts)
- [ENS](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/08-ens.ts)
- [Registry](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/09-registry.ts)
- [Raw JSON-RPC](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/10-json-rpc.ts)
- [RPC](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/11-rpc.ts)
- [Contracts](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/12-contracts.ts)
- [Solana](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/13-solana.ts)
- [Data](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/14-data.ts)
- [Cosmos](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/16-cosmos.ts)
- [Error Handling](https://cdn.jsdelivr.net/npm/@spectrumnodes/sdk@latest/examples/15-error-handling.ts)

After `npm install @spectrumnodes/sdk`, the same files are available locally at `node_modules/@spectrumnodes/sdk/examples/`.

## Namespaces

| Namespace            | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `spectrum.core`      | Block heights, gas fees, block details, gas estimation     |
| `spectrum.tokens`    | Native and ERC-20 balances, token metadata, allowances     |
| `spectrum.yields`    | Lending, vaults, staking, best-yield discovery             |
| `spectrum.prices`    | Token prices, history, top markets, search                 |
| `spectrum.defi`      | Swaps, positions, approvals, perps, funding rates          |
| `spectrum.nfts`      | NFT collections, balances, ownership, metadata             |
| `spectrum.ens`       | ENS resolution and reverse lookup                          |
| `spectrum.registry`  | Protocol registry, contract addresses, supported chains    |
| `spectrum.rpc`       | Direct JSON-RPC proxy to chain nodes                       |
| `spectrum.contracts` | Smart contract reads, multicall, simulation                |
| `spectrum.solana`    | Solana-specific convenience methods                        |
| `spectrum.cosmos`    | Cosmos SDK auth & staking (accounts, delegations, validators, rewards, supply) |
| `spectrum.data`      | Logs, transfers, receipts, portfolio, chain health, traces |
| `spectrum.utils`     | API health check                                           |

## Supported Chains

Pass any of these slugs as the `chain` argument. The full list is also available at runtime as `SUPPORTED_CHAIN_SLUGS`.

| Type | Chains |
| ---- | ------ |
| EVM | `ethereum`, `polygon`, `bsc`, `optimism`, `base`, `avalanche`, `arbitrum`, `gnosis`, `berachain`, `moonbeam`, `monad`, `linea`, `hyperliquid`, `scroll`, `plasma`, `xlayer` |
| Solana | `solana` |
| Bitcoin | `bitcoin` |
| Starknet | `starknet` |
| Cosmos | `cosmoshub`, `osmosis`, `axelar`, `noble`, `agoric` |

## Notes

- Most methods map closely to Spectrum JSON-RPC method names, with light validation and typed responses.
- All methods accept an optional trailing `RequestOptions` argument for per-call cache, retry, and abort behavior.
- Use `spectrum.parallel()` for client-side `Promise.all` convenience, or `spectrum.jsonRpc([...])` to send a raw JSON-RPC request array.

## License

MIT