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