> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vectrade.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install and use the official VecTrade TypeScript/Node.js SDK

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @vectrade/sdk
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @vectrade/sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @vectrade/sdk
    ```
  </Tab>
</Tabs>

## Runtime Support

| Runtime            | Version | Status         |
| ------------------ | ------- | -------------- |
| Node.js            | 18+     | ✅ Full support |
| Deno               | 1.28+   | ✅ Full support |
| Bun                | 1.0+    | ✅ Full support |
| Cloudflare Workers | —       | ✅ Full support |

**Zero runtime dependencies** — uses native `fetch` and Web Crypto APIs.

## Quick Start

```typescript theme={null}
import { VecTrade } from "@vectrade/sdk";

const client = new VecTrade(); // reads VECTRADE_API_KEY env var

const quote = await client.quotes.get("AAPL");
console.log(`${quote.ticker}: $${quote.price}`);
```

## Configuration

```typescript theme={null}
const client = new VecTrade({
  apiKey: "vq_...",        // or VECTRADE_API_KEY env var
  baseURL: "https://...",  // custom endpoint
  timeout: 30000,          // request timeout (ms)
  maxRetries: 2,           // automatic retries on 429/5xx
});
```

## Resources

All 12 resource groups available:

| Resource              | Methods                                                        |
| --------------------- | -------------------------------------------------------------- |
| `client.quotes`       | `get(symbol)`, `batch(symbols)`                                |
| `client.fundamentals` | `get(symbol)`, `statements(symbol)`                            |
| `client.technicals`   | `get(symbol)`                                                  |
| `client.news`         | `list(symbol)`                                                 |
| `client.options`      | `chain(symbol)`                                                |
| `client.analyst`      | `consensus(symbol)`, `priceTargets(symbol)`, `ratings(symbol)` |
| `client.earnings`     | `history(symbol)`                                              |
| `client.insider`      | `transactions(symbol)`                                         |
| `client.profile`      | `get(symbol)`                                                  |
| `client.sentiment`    | `get(symbol)`                                                  |
| `client.historical`   | `get(symbol, { period })`                                      |
| `client.etf`          | `get(symbol)`                                                  |

## Usage Examples

### Batch Quotes

```typescript theme={null}
const quotes = await client.quotes.batch(["AAPL", "MSFT", "GOOGL"]);
for (const q of quotes) {
  console.log(`${q.ticker}: $${q.price.toFixed(2)} (${q.change_percent}%)`);
}
```

### Technical Analysis

```typescript theme={null}
const tech = await client.technicals.get("AAPL");
console.log(`Score: ${tech.technical_score}/100`);
console.log(`RSI: ${tech.indicators?.rsi?.value} (${tech.indicators?.rsi?.signal})`);
console.log(`Trend: ${tech.summary?.trend}`);
```

### Analyst Consensus

```typescript theme={null}
const analyst = await client.analyst.consensus("AAPL");
console.log(`${analyst.consensus} | Signal: ${analyst.signal}`);
```

## Error Handling

```typescript theme={null}
import { RateLimitError, NotFoundError } from "@vectrade/sdk";

try {
  const quote = await client.quotes.get("INVALID");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log(`Not found (request_id: ${err.requestId})`);
  } else if (err instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${err.retryAfter}s`);
  }
}
```

## Vercel AI SDK Integration

```typescript theme={null}
import { createVecTrade } from "@vectrade/ai-provider";
import { generateText } from "ai";

const vt = createVecTrade();
const result = await generateText({
  model: yourModel,
  tools: vt.tools(),
  prompt: "What's AAPL trading at?",
});
```

## Security

* API key is **non-enumerable** — hidden from `console.log` and `JSON.stringify`
* Webhook verification uses **constant-time comparison** (double-HMAC)
* Replay protection via **timestamp tolerance window**

<Card title="GitHub" icon="github" href="https://github.com/VecTrade-io/vectrade-node">
  Source code, issues, and contributions
</Card>