# near-kit

> A simple, intuitive TypeScript library for interacting with NEAR Protocol

Latest version **0.20.2** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install near-kit
pnpm add near-kit
yarn add near-kit
bun add near-kit
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.20.2 |
| Published | 2026-09-24 |
| First published | 2025-11-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 10 |
| Unpacked size | 1.1 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 11 |
| Maintainers | ricky-is |
| Keywords | near, near-protocol, blockchain, typescript, web3 |

## Links

- npm: https://www.npmjs.com/package/near-kit
- Repository: https://github.com/r-near/near-kit
- Homepage: https://github.com/r-near/near-kit#readme
- Issues: https://github.com/r-near/near-kit/issues
- npm.io page: https://npm.io/package/near-kit

## Dependencies (10)

- [tar](https://npm.io/package/tar.md) ^7.5.20
- [zod](https://npm.io/package/zod.md) ^4.4.3
- [@scure/base](https://npm.io/package/@scure/base.md) ^2.2.0
- [@scure/bip32](https://npm.io/package/@scure/bip32.md) ^2.2.0
- [@scure/bip39](https://npm.io/package/@scure/bip39.md) ^2.2.0
- [@zorsh/zorsh](https://npm.io/package/@zorsh/zorsh.md) ^0.5.1
- [@noble/curves](https://npm.io/package/@noble/curves.md) ^2.2.0
- [@noble/hashes](https://npm.io/package/@noble/hashes.md) ^2.0.1
- [@napi-rs/keyring](https://npm.io/package/@napi-rs/keyring.md) ^1.3.0
- [@noble/post-quantum](https://npm.io/package/@noble/post-quantum.md) ^0.6.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.20.2 (latest) — 2026-09-24
- 0.20.1 — 2026-09-14
- 0.20.0 — 2026-09-10
- 0.19.0 — 2026-07-22
- 0.18.0 — 2026-07-13
- 0.17.0 — 2026-07-10
- 0.16.0 — 2026-07-07
- 0.15.0 — 2026-07-02
- 0.14.0 — 2026-05-05
- 0.13.1 — 2026-04-30
- 0.12.0 — 2026-03-05
- 0.11.0 — 2026-02-07
- 0.10.0 — 2026-01-24
- 0.9.0 — 2026-01-24
- 0.8.3 — 2026-01-24
- … 25 more at https://npm.io/package/near-kit/versions

## README

# near-kit

[![codecov](https://codecov.io/gh/r-near/near-kit/graph/badge.svg?token=F52NQ1DYG1)](https://codecov.io/gh/r-near/near-kit)
[![npm version](https://img.shields.io/npm/v/near-kit.svg)](https://www.npmjs.com/package/near-kit)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)

A simple, intuitive TypeScript library for interacting with NEAR Protocol. Designed to feel like a modern fetch library - easy for beginners, powerful for advanced users.

**[📚 Full Documentation](https://kit.near.tools)**

## Features

- **Simple things should be simple** - One-line commands for common operations
- **Type safety everywhere** - Full TypeScript support with IDE autocomplete
- **Progressive complexity** - Basic API for simple needs, advanced features when required
- **Powerful transaction builder** - Fluent, human-readable API for transactions
- **Wallet-ready** - Full support for [NEAR Connect](https://github.com/azbang/near-connect), drop-in integration

## Installation

```bash
npm install near-kit
# or
bun install near-kit
```

## Quick Start

```typescript
import { Near } from "near-kit"

// Initialize for backend/scripts
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
  defaultSignerId: "alice.testnet",
})

// View methods (read-only, no gas)
const balance = await near.view("example.testnet", "get_balance", {
  account_id: "alice.testnet",
})

// Call methods (requires signature, costs gas)
await near.call(
  "example.testnet",
  "increment",
  {},
  { attachedDeposit: "0.1 NEAR" }
)

// Send NEAR tokens
await near.send("bob.testnet", "5 NEAR")
```

## Getting Started

near-kit provides a unified API that works across different environments. Configuration varies by environment, but the API for calling contracts, sending transactions, and building transactions remains identical.

### Backend & Scripts

For local testing, use the sandbox (no network or key configuration needed):

```typescript
import { Sandbox } from "near-kit"

const sandbox = await Sandbox.start()
const near = new Near({ network: sandbox })

// Test with automatically provisioned accounts
await near.call("contract.test.near", "method", {})

await sandbox.stop()
```

For testnet/mainnet development, pass a private key directly:

```typescript
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
  defaultSignerId: "alice.testnet",
})
```

For production applications, use a keyStore:

```typescript
import { FileKeyStore } from "near-kit"

const near = new Near({
  network: "testnet",
  keyStore: new FileKeyStore("~/.near-credentials"),
})
```

### Frontend & Wallets

In the browser, connect to user wallets. The same `near.call()`, `near.send()`, and `near.transaction()` methods work seamlessly:

```typescript
import { Near, fromHotConnect } from "near-kit"
import { NearConnector } from "@hot-labs/near-connect"

const connector = new NearConnector({ network: "testnet" })

const near = new Near({
  network: "testnet",
  wallet: fromHotConnect(connector),
})

// Same API as backend
await near.call("contract.near", "method", { arg: "value" })
```

This works through a signer abstraction - whether you pass `privateKey`, `keyStore`, `wallet`, or `sandbox`, they all implement the same signing interface internally.

## Core API

### Initialization

```typescript
// Simple - defaults to mainnet
const near = new Near()

// With network selection
const near = new Near({ network: "testnet" })

// With custom configuration
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
})
```

### Basic Operations

```typescript
// View methods (free, no signature required)
const result = await near.view("contract.near", "get_data", { key: "value" })

// Check account balance
const balance = await near.getBalance("alice.near")

// Check if account exists
const exists = await near.accountExists("alice.near")

// Get network status
const status = await near.getStatus()
```

### Type-Safe Contracts

```typescript
import type { Contract } from "near-kit"

// Define contract interface using Contract<> helper
type MyContract = Contract<{
  view: {
    get_balance: (args: { account_id: string }) => Promise<string>
    get_info: () => Promise<{ name: string; version: string }>
  }
  call: {
    // Just define args - options parameter automatically added!
    transfer: (args: { to: string; amount: string }) => Promise<void>
  }
}>

// Create type-safe contract
const contract = near.contract<MyContract>("example.near")

// Fully typed method calls
const balance = await contract.view.get_balance({ account_id: "alice.near" })
const info = await contract.view.get_info()

// Call methods automatically get options parameter
await contract.call.transfer(
  { to: "bob.near", amount: "10" },
  { attachedDeposit: "1 NEAR" }
)
```

### Transaction Builder

```typescript
// Alice builds a transaction with multiple actions
// 'alice.near' is the signer - the account that signs and pays for this transaction
const receipt = await near
  .transaction("alice.near") // Alice signs
  .transfer("bob.near", "10 NEAR") // Alice sends Bob 10 NEAR
  .functionCall(
    "market.near",
    "buy",
    { id: "123" },
    { attachedDeposit: "5 NEAR" } // Alice attaches 5 NEAR to the call
  )
  .send()
```

### Batch Operations

```typescript
// Run multiple operations in parallel
const [balance, status, exists] = await near.batch(
  near.getBalance("alice.near"),
  near.getStatus(),
  near.accountExists("bob.near")
)
```

## Local Testing with Sandbox

```typescript
import { Sandbox } from "near-kit"

const sandbox = await Sandbox.start()
const near = new Near({ network: sandbox })
// ... run tests
await sandbox.stop()
```

**With test framework:**

```typescript
let sandbox: Sandbox
beforeAll(async () => {
  sandbox = await Sandbox.start()
})
afterAll(async () => {
  await sandbox.stop()
})
```

**State manipulation** — patch state directly, fast-forward blocks, and take snapshots:

```typescript
import { EMPTY_CODE_HASH } from "near-kit/sandbox"

// Patch blockchain state without transactions
await sandbox.patchState([{
  Account: {
    account_id: "alice.test.near",
    account: { amount: "5000000000000000000000000", locked: "0", code_hash: EMPTY_CODE_HASH, storage_usage: 100 }
  }
}])

// Fast-forward blocks for time-dependent logic
await sandbox.fastForward(100)

// Snapshot & restore state between tests
const snapshot = await sandbox.dumpState()
// ... run test that modifies state ...
await sandbox.restoreState(snapshot)

// Restart with clean genesis (optionally baking in a snapshot)
await sandbox.restart(snapshot)
```

## Key Management

```typescript
import { InMemoryKeyStore, FileKeyStore, RotatingKeyStore } from "near-kit"

// In-memory (runtime only)
const near = new Near({
  keyStore: new InMemoryKeyStore({
    "alice.near": "ed25519:...",
  }),
})

// File-based (persistent)
const near = new Near({
  keyStore: new FileKeyStore("~/.near-credentials"),
})

// Rotating keys for high-throughput concurrent transactions
const near = new Near({
  keyStore: new RotatingKeyStore({
    "alice.near": ["ed25519:key1...", "ed25519:key2...", "ed25519:key3..."],
  }),
})
```

## Wallet Integration

near-kit integrates with [NEAR Connect](https://github.com/azbang/near-connect) through a signer abstraction. The wallet adapter is converted to a signer via `fromHotConnect()`, allowing the same API to work across backend and frontend without separate client implementations.

```typescript
import { Near, fromHotConnect } from "near-kit"
import { NearConnector } from "@hot-labs/near-connect"

// Create connector
const connector = new NearConnector({ network: "testnet" })

// Wait for user to connect
connector.on("wallet:signIn", async () => {
  const near = new Near({
    network: "testnet",
    wallet: fromHotConnect(connector),
  })

  // All operations now use the wallet for signing
  await near.call("contract.near", "method", { arg: "value" })
  await near.send("bob.near", "10 NEAR")
})

// Trigger wallet connection
await connector.signIn()
```

## Error Handling

Errors are organized by category and include detailed context for debugging. Use `instanceof` checks to handle specific error types.

#### Network Errors

```typescript
import { NetworkError, TimeoutError } from "near-kit"

try {
  await near.call("contract.near", "method", {})
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log("Request timed out - already retried automatically")
  } else if (error instanceof NetworkError) {
    // Handle other network issues
  }
}
```

#### Transaction Errors

```typescript
import { InsufficientBalanceError, InvalidNonceError } from "near-kit"

try {
  await near.send("bob.near", "1000000 NEAR")
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need ${error.required}, have ${error.available}`)
  } else if (error instanceof InvalidNonceError) {
    // Already retried automatically - only thrown if retries exhausted
  }
}
```

#### Contract Errors

```typescript
import { FunctionCallError } from "near-kit"

try {
  await near.call("contract.near", "method", {})
} catch (error) {
  if (error instanceof FunctionCallError) {
    console.log(`Contract panicked: ${error.panic}`)
    console.log(`Logs:`, error.logs)
  }
}
```

## Advanced Features

### Batch Actions (Multi-Action Transactions)

Deploy and initialize a contract in a single transaction:

```typescript
const contractWasm = await fs.readFile("./contract.wasm")

await near
  .transaction("alice.near")
  .createAccount("contract.alice.near")
  .transfer("contract.alice.near", "10 NEAR")
  .deployContract("contract.alice.near", contractWasm)
  .functionCall("contract.alice.near", "init", { owner: "alice.near" })
  .send()
```

### NEP-413 Message Signing

Authenticate users without gas fees:

```typescript
import { hex } from "@scure/base"
import { generateNonce, Near } from "near-kit"

const nonce = generateNonce()
const signedMessage = await near.signMessage({
  message: "Login to MyApp",
  recipient: "myapp.near",
  nonce,
})

// Send to backend for verification
await fetch("/api/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    signedMessage,
    message: "Login to MyApp",
    recipient: "myapp.near",
    nonce: hex.encode(nonce), // hex-encode for JSON transport
  }),
})
```

### Delegate Actions (NEP-366)

Enable meta-transactions and sponsored transactions where a relayer pays the gas:

```typescript
import { decodeSignedDelegateAction, Near } from "near-kit"

// User creates and signs a delegate action (no gas cost to user)
const userNear = new Near({
  network: "testnet",
  privateKey: "ed25519:...", // User's key
})

const { signedDelegateAction, payload } = await userNear
  .transaction("user.near")
  .transfer("recipient.near", "1 NEAR")
  .delegate({ blockHeightOffset: 100 })

// Relayer submits the transaction (pays the gas)
const relayerNear = new Near({
  network: "testnet",
  privateKey: "ed25519:...", // Relayer's key
})

await relayerNear
  .transaction("relayer.near")
  .signedDelegateAction(decodeSignedDelegateAction(payload))
  .send()
```

### Automatic Nonce Management

No more nonce conflicts - the library handles nonce tracking and retries automatically:

```typescript
// Safe to run multiple transactions concurrently
await Promise.all([
  near.send("bob.near", "1 NEAR"),
  near.send("charlie.near", "1 NEAR"),
  near.send("dave.near", "1 NEAR"),
])
// Nonces are automatically managed and conflicts are retried
```

For high-throughput scenarios (trading bots, faucets, relayers), use `RotatingKeyStore` with multiple access keys per account:

```typescript
import { RotatingKeyStore } from "near-kit"

const keyStore = new RotatingKeyStore({
  "bot.near": ["ed25519:key1...", "ed25519:key2...", "ed25519:key3..."],
})

const near = new Near({ keyStore })

// Send 20 concurrent transactions - each key handles its own nonce
await Promise.all(
  Array(20)
    .fill(0)
    .map(() => near.send("recipient.near", "0.1 NEAR"))
)
```

### Smart Retry Logic

Automatic retries for network errors with exponential backoff:

```typescript
try {
  await near.call("contract.near", "method", {})
} catch (error) {
  if (error instanceof TimeoutError && error.retryable) {
    // Already retried automatically
  }
}
```

## Development

```bash
# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Run examples
bun run examples/quickstart.ts
```

## License

MIT

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