Migrating from near-api-js

If you are coming from near-api-js, you will find near-kit to be more concise and less prone to “unit arithmetic” errors.

Core Philosophy Shifts

No Account Object

Use the central Near instance and pass signer IDs as arguments

Strings, not BigInts

No more utils.format or counting zeros

Fluent Builder

Chain readable methods instead of config objects

Side-by-Side Comparisons

1. Connecting & Keys

near-api-js
near-kit

You have to manually assemble the Account, JsonRpcProvider, and KeyPairSigner.

import { Account } from "@near-js/accounts"
import { JsonRpcProvider } from "@near-js/providers"
import { KeyPairSigner } from "@near-js/signers"

const provider = new JsonRpcProvider({
  url: "https://test.rpc.fastnear.com",
})
const signer = KeyPairSigner.fromSecretKey("ed25519:...")
const account = new Account("alice.testnet", provider, signer)

Configuration is flattened. The KeyStore is optional for simple cases.

const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...", // Automatically sets up an InMemoryKeyStore
  defaultSignerId: "alice.testnet",
})

2. Handling Units

near-api-js
near-kit

Requires manual conversion, often leading to BN (BigNumber) headaches.

import { parseNearAmount } from "@near-js/utils"

const amount = parseNearAmount("10.5") // "1050000..."
const gas = "30000000000000" // Hope you counted the zeros right!

Parses human-readable strings automatically.

const amount = "10.5 NEAR"
const gas = "30 Tgas"

3. Calling Contracts

near-api-js
near-kit

Arguments are passed inside a configuration object.

const account = new Account("alice.testnet", provider, signer)

await account.callFunction({
  contractId: "market.near",
  methodName: "buy",
  args: { id: "1" },
  gas: "50000000000000",
  deposit: parseNearAmount("1")!,
})

Uses a fluent chain.

await near
  .transaction("alice.testnet")
  .functionCall(
    "market.near",
    "buy",
    { id: "1" },
    { gas: "50 Tgas", attachedDeposit: "1 NEAR" }
  )
  .send()

4. Error Handling

near-api-js
near-kit

Often throws raw RPC errors or generic “TypedErrors” that are hard to parse.

try {
  // ...
} catch (e) {
  // You have to inspect e.type or e.message string matching
  if (e.type === 'FunctionCallError') { ... }
}

Throws distinct, standard JavaScript Error subclasses.

import { FunctionCallError } from "near-kit"

try {
  // ...
} catch (e) {
  if (e instanceof FunctionCallError) {
    console.log(e.panic) // Access the panic message directly
  }
}

5. Access Keys

near-api-js
near-kit

await account.addFunctionCallAccessKey({
  publicKey,
  contractId: "market.near",
  methodNames: ["buy"],
  allowance: parseNearAmount("0.25")!,
})

Explicitly typed permissions object.

await near
  .transaction("alice.testnet")
  .addKey(publicKey, {
    type: "functionCall",
    receiverId: "market.near",
    methodNames: ["buy"],
    allowance: "0.25 NEAR",
  })
  .send()

Getting Started

Essentials

React

Building dApps

Advanced

Reference

Migrating from near-api-js

Core Philosophy Shifts

No Account Object

Strings, not BigInts

Fluent Builder

Side-by-Side Comparisons

1. Connecting & Keys

2. Handling Units

3. Calling Contracts

4. Error Handling

5. Access Keys

​Core Philosophy Shifts

No Account Object

Strings, not BigInts

Fluent Builder

​Side-by-Side Comparisons

​1. Connecting & Keys

​2. Handling Units

​3. Calling Contracts

​4. Error Handling

​5. Access Keys

Core Philosophy Shifts

Side-by-Side Comparisons

1. Connecting & Keys

2. Handling Units

3. Calling Contracts

4. Error Handling

5. Access Keys