# @nostr-dev-kit/ndk

> NDK - Nostr Development Kit. Includes AI Guardrails to catch common mistakes during development.

Latest version **3.0.3** (published 2026-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @nostr-dev-kit/ndk
pnpm add @nostr-dev-kit/ndk
yarn add @nostr-dev-kit/ndk
bun add @nostr-dev-kit/ndk
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2026-02-23 |
| First published | 2023-04-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16 |
| Dependencies | 10 |
| Unpacked size | 3.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 453 |
| Author | pablof7z |
| Maintainers | jinglescode, pablof7z |
| Keywords | nostr |

## Links

- npm: https://www.npmjs.com/package/@nostr-dev-kit/ndk
- Repository: https://github.com/nostr-dev-kit/ndk
- Homepage: https://ndk.fyi
- Issues: https://github.com/nostr-dev-kit/ndk/issues
- npm.io page: https://npm.io/package/@nostr-dev-kit/ndk

## Dependencies (10)

- [debug](https://npm.io/package/debug.md) ^4.3.7
- [shiki](https://npm.io/package/shiki.md) ^3.13.0
- [tseep](https://npm.io/package/tseep.md) ^1.3.1
- [@scure/base](https://npm.io/package/@scure/base.md) ^1.1.9
- [@noble/curves](https://npm.io/package/@noble/curves.md) ^1.6.0
- [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^1.5.0
- [@noble/secp256k1](https://npm.io/package/@noble/secp256k1.md) ^2.1.0
- [light-bolt11-decoder](https://npm.io/package/light-bolt11-decoder.md) ^3.2.0
- [typescript-lru-cache](https://npm.io/package/typescript-lru-cache.md) ^2.0.0
- [@codesandbox/sandpack-client](https://npm.io/package/@codesandbox/sandpack-client.md) ^2.19.8

## Recent versions

- 3.0.3 (latest) — 2026-02-23
- 3.0.0-beta.71 (beta) — 2026-01-30
- 2.13.0-rc1.0 (rc1) — 2025-03-19
- 3.0.2 — 2026-02-23
- 3.0.1 — 2026-02-23
- 3.0.0 — 2026-02-10
- 3.0.0-beta.70 — 2026-01-08
- 3.0.0-beta.69 — 2026-01-05
- 3.0.0-beta.66 — 2025-12-17
- 3.0.0-beta.64 — 2025-12-17
- 3.0.0-beta.62 — 2025-12-01
- 3.0.0-beta.61 — 2025-12-01
- 3.0.0-beta.59 — 2025-12-01
- 3.0.0-beta.58 — 2025-12-01
- 3.0.0-beta.57 — 2025-12-01
- … 318 more at https://npm.io/package/@nostr-dev-kit/ndk/versions

## README

# @nostr-dev-kit/ndk

[![npm version](https://img.shields.io/npm/v/@nostr-dev-kit/ndk.svg)](https://www.npmjs.com/package/@nostr-dev-kit/ndk)
[![Build Status](https://github.com/nostr-dev-kit/ndk/actions/workflows/deploy.yml/badge.svg)](https://github.com/nostr-dev-kit/ndk/actions)
[![AI Guardrails Included](https://img.shields.io/badge/AI%20Guardrails-Included-brightgreen)](https://github.com/nostr-dev-kit/ndk/tree/master/ndk/src/ai-guardrails)

> NDK (Nostr Development Kit) is a TypeScript/JavaScript library that simplifies building Nostr clients, relays, and related applications.

## ⚠️ Important: Enable AI Guardrails

**If you're new to NDK or using an AI assistant, enable AI Guardrails:**

```typescript
const ndk = new NDK({ aiGuardrails: true });
```

This prevents 90% of common mistakes (bech32 in filters, missing fields, invalid formats) with clear error messages. Disable in production.

## 🤖 For AI Assistants & New Developers

NDK includes **AI Guardrails** - runtime validation that catches common mistakes:

- Using npub/note1 in filters (must be hex)
- Missing required fields on events
- Invalid tag formats
- Performance anti-patterns

**Enable with `aiGuardrails: true`** - see Quick Start below.

## Features

- Outbox model support
- Relay connection pool with automatic reconnection and failover
- Flexible subscription API with caching, batching, and auto-closing
- Event creation, validation, and wrappers for major NIPs (e.g., NIP-01, NIP-04, NIP-07, NIP-18, NIP-49, NIP-57, NIP-60, NIP-61)
- Signer adapters: private key, encrypted keys (NIP-49), browser extension (NIP-07), remote signing (NIP-46)
- Pluggable cache adapters (Redis, Dexie, SQLite, etc.)
- Data Vending Machine support (NIP-90)
- Zap utilities (NIP-57, NIP-61)
- Threading, event kinds, and utility functions (URL normalization, metadata tags, filters)
- Modular design with many pluggable packages for different frameworks (Mobile, Svelte 4 and 5, React)

## Installation

```bash
npm install @nostr-dev-kit/ndk
# or
yarn add @nostr-dev-kit/ndk
# or
bun add @nostr-dev-kit/ndk
```

## Quick Start

```typescript
import NDK, { NDKEvent, NDKPrivateKeySigner } from '@nostr-dev-kit/ndk';

async function main() {
  const signer = NDKPrivateKeySigner.generate();
  const ndk = new NDK({
    explicitRelayUrls: ['wss://relay.primal.net'],
    signer,

    // ⚠️ STRONGLY RECOMMENDED: Enable during development
    // Catches common mistakes before they cause silent failures
    aiGuardrails: true
  });

  // Connect to relays
  await ndk.connect();

  // Publish a simple text note
  const event = new NDKEvent(ndk, {
    kind: 1,
    content: 'Hello Nostr via NDK!',
  })
  await event.sign();
  event.publish();

 // subscribe to all event interactions
  ndk.subscribe(event.filter(), { closeOnEose: false }, {
   onEvent: (replyEvent: NDKEvent) => console.log(replyEvent.author.npub, "interacted with our hello world with a kind", replyEvent.kind);
  })

  // Subscribe to incoming text notes
  const subscription = ndk.subscribe(
    { kinds: [1] },
    { closeOnEose: true },
    {
      onEvent: (evt) => console.log('Received event:', evt),
      onEose: () => console.log('End of stream'),
    }
  );
}

main().catch(console.error);
```

## Documentation

Full API reference and guides are available at [https://nostr-dev-kit.github.io/ndk](https://nostr-dev-kit.github.io/ndk).

## License

MIT

---
_Source: https://npm.io/package/@nostr-dev-kit/ndk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._