near-kit

A TypeScript library for NEAR Protocol with an intuitive, fetch-like API.

Quick Start

import { Near } from "near-kit"

// Read-only (no key needed) const near = new Near({ network: "testnet" }) const data = await near.view("contract.near", "get_data", { key: "value" })

// With signing capability const near = new Near({ network: "testnet", privateKey: "ed25519:...", defaultSignerId: "alice.testnet", }) await near.call("contract.near", "method", { arg: "value" }) await near.send("bob.testnet", "1 NEAR")

Core Operations

View Methods (Read-Only, Free)

const result = await near.view("contract.near", "get_data", { key: "value" }) const balance = await near.getBalance("alice.near") const exists = await near.accountExists("alice.near")

Call Methods (Requires Signing)

await near.call( "contract.near", "method", { arg: "value" }, { gas: "30 Tgas", attachedDeposit: "1 NEAR" } )

Send NEAR Tokens

await near.send("bob.near", "5 NEAR")

Type-Safe Contracts

import type { Contract } from "near-kit"

type MyContract = Contract<{ view: { get_balance: (args: { account_id: string }) => Promise<string> } call: { transfer: (args: { to: string; amount: string }) => Promise<void> } }>

const contract = near.contract<MyContract>("token.near") await contract.view.get_balance({ account_id: "alice.near" }) await contract.call.transfer({ to: "bob.near", amount: "10" }, { attachedDeposit: "1 yocto" })

Transaction Builder

Chain multiple actions in a single atomic transaction:

await near .transaction("alice.near") .transfer("bob.near", "1 NEAR") .functionCall("contract.near", "method", { arg: "value" }, { gas: "30 Tgas" }) .send()

For all transaction actions and meta-transactions, see references/transactions.md

Configuration

Backend/Scripts

// Direct private key const near = new Near({ network: "testnet", privateKey: "ed25519:...", defaultSignerId: "alice.testnet", })

// File-based keystore import { FileKeyStore } from "near-kit/keys/file" const near = new Near({ network: "testnet", keyStore: new FileKeyStore("~/.near-credentials"), })

// High-throughput with rotating keys import { RotatingKeyStore } from "near-kit" const near = new Near({ network: "mainnet", keyStore: new RotatingKeyStore({ "bot.near": ["ed25519:key1...", "ed25519:key2...", "ed25519:key3..."], }), })

For all key stores and utilities, see references/keys-and-testing.md

Browser Wallets

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

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

connector.on("wallet:signIn", async (event) => { const near = new Near({ network: "mainnet", wallet: fromHotConnect(connector), })

await near.call("contract.near", "method", { arg: "value" }) })

connector.connect()

For HOT Connect and Wallet Selector integration, see references/wallets.md

Testing with Sandbox

import { Sandbox } from "near-kit/sandbox"

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

const testAccount = test-${Date.now()}.${sandbox.rootAccount.id} await near .transaction(sandbox.rootAccount.id) .createAccount(testAccount) .transfer(testAccount, "10 NEAR") .send()

await sandbox.stop()

For sandbox patterns and Vitest integration, see references/keys-and-testing.md

Error Handling

import { InsufficientBalanceError, FunctionCallError, NetworkError, TimeoutError, } from "near-kit"

try { await near.call("contract.near", "method", {}) } catch (error) { if (error instanceof InsufficientBalanceError) { console.log(Need ${error.required}, have ${error.available}) } else if (error instanceof FunctionCallError) { console.log(Panic: ${error.panic}, Logs: ${error.logs}) } }

Unit Formatting

All amounts accept human-readable formats:

"10 NEAR" // 10 NEAR "10" // 10 NEAR 10 // 10 NEAR "30 Tgas" // 30 trillion gas units

Key Utilities

import { generateKey, parseKey, generateSeedPhrase, parseSeedPhrase, isValidAccountId, Amount, Gas, } from "near-kit"

const { publicKey, privateKey } = generateKey() const { seedPhrase, publicKey, privateKey } = generateSeedPhrase() const restored = parseSeedPhrase("word1 word2 ... word12")

isValidAccountId("alice.near") // true Amount.parse("5 NEAR") // bigint in yoctoNEAR Gas.parse("30 Tgas") // bigint in gas units

References

For detailed documentation on specific topics:

• Wallet Integration - HOT Connect, Wallet Selector, universal patterns

• Transaction Builder - All actions, meta-transactions (NEP-366)

• Keys and Testing - Key stores, utilities, sandbox, NEP-413 signing