# Configuration

## Authentication

All requests require an `api` value containing the full URL you were given.

In production behind Kong, users are given a full URL such as:

```text
https://spectrum-02.simplystaking.xyz/<tenant-token>/spectrumapi/v1/
```

Get your URL at [spectrumnodes.com](https://spectrumnodes.com).

## Full Configuration

```typescript
const spectrum = new Spectrum({
  api: 'https://spectrum-02.simplystaking.xyz/<tenant-token>/spectrumapi/v1/', // required — paste the URL you were given
  defaultChain: 'ethereum', // optional — default chain for all calls
  timeout: 30_000, // request timeout in ms (default: 30000)
  retries: 3, // max retries on transient failure (default: 3)
  cache: {
    enabled: true, // response caching (default: true)
    ttl: 5_000, // default cache TTL in ms (default: 5000)
    overrides: {
      // per-method TTL overrides — keyed by JSON-RPC
      // method name (or substring); the first match wins.
      getYieldsLending: 60_000,
      getProtocols: 300_000,
    },
  },
  logging: {
    level: 'warn', // 'debug' | 'info' | 'warn' | 'error' | 'silent'
  },
  hooks: {
    onRequest: (req) => console.log(`-> ${req.method} ${req.path}`),
    onResponse: (res) => console.log(`<- ${res.status} (${res.duration}ms)`),
    onError: (err) => console.error(`!! ${err.message}`),
  },
});
```

## Development vs Production Presets

**Development** — verbose logging, no caching, generous timeout:

```typescript
const spectrum = new Spectrum({
  api: 'http://localhost:3001/test/',
  cache: { enabled: false },
  logging: { level: 'debug' },
  timeout: 60_000,
});
```

**Production** — caching on, minimal logging, retries enabled:

```typescript
const spectrum = new Spectrum({
  api: process.env.SPECTRUM_API!,
  retries: 3,
  cache: { enabled: true, ttl: 15_000 }, // 15s default — override the 5s built-in
  logging: { level: 'error' },
});
```

## Default Chain

Set a default chain to avoid passing it on every call:

```typescript
const spectrum = new Spectrum({
  api: process.env.SPECTRUM_API!,
  defaultChain: 'ethereum',
});

// Uses default chain
const block = await spectrum.core.getBlockHeight();
const balance = await spectrum.tokens.getBalance(undefined, '0xAddress...');
```

If no chain is passed and no `defaultChain` is configured, methods that require a chain throw `ValidationError`.

## Cache

The SDK includes an in-memory TTL cache enabled by default.

- **Default TTL:** 5 seconds
- **Token metadata:** cached for 1 hour
- **Yields, NFTs:** cached for 60 seconds
- **Registry, protocols:** cached for 5 minutes
- **Health, blocks, gas, gas estimation, raw RPC proxy:** never cached
- **Per-method overrides:** set via `cache.overrides` (substring match against the JSON-RPC method name)
- **Disable globally:** `cache: { enabled: false }`
- **Disable per-request:** pass `{ cacheTtl: 0 }` as `RequestOptions`
- **Clear manually:** `spectrum.clearCache()`

## Rate Limiting

The SDK does not apply client-side throttling.

If the server returns HTTP 429, the SDK throws `RateLimitError`, and retry logic can use `Retry-After` when provided.

## Hooks / Observability

Use hooks for logging, metrics collection, or APM integration:

```typescript
const spectrum = new Spectrum({
  api: process.env.SPECTRUM_API!,
  hooks: {
    onRequest: (req) => console.log(`-> ${req.method} ${req.path}`),
    onResponse: (res) => myMetrics.recordLatency(res.path, res.duration),
    onError: (err) => myApm.captureError(err),
  },
});
```

## Request Options

All methods accept an optional trailing `RequestOptions` parameter:

```typescript
interface RequestOptions {
  cacheTtl?: number; // override cache TTL (0 to skip cache)
  noRetry?: boolean; // skip retries
  signal?: AbortSignal; // abort signal
}
```

## Response Format

All API responses are wrapped in a `{ data: ... }` envelope. The SDK unwraps this automatically — methods return the inner `data` value directly.

## Browser & Runtime Support

- **Node.js >= 20** — required
- **Browsers** — works in modern browsers with native `fetch`
- **Bun / Deno** — should work in any runtime with native `fetch`

The SDK ships as both ESM (`import`) and CJS (`require`).