name: near-api-js
description: >-
Guide for developing with near-api-js v7 - the JavaScript/TypeScript library for NEAR blockchain interaction.
Use when: (1) building apps that interact with NEAR blockchain, (2) creating/signing transactions,
(3) calling smart contracts, (4) managing accounts and keys, (5) working with NEAR RPC API,
(6) handling FT/NFT tokens on NEAR, (7) using NEAR cryptographic operations (KeyPair, signing),
(8) converting between NEAR units (yocto, gas), (9) gasless/meta transactions with relayers,
(10) wallet integration and session management, (11) NEP-413 message signing for authentication,
(12) storage deposit management for FT contracts. Triggers on any NEAR blockchain development tasks.

near-api-js Skill

JavaScript/TypeScript library for NEAR blockchain interaction. Works in browser and Node.js.

Quick Start

import { Account, JsonRpcProvider, KeyPair } from "near-api-js"
import { NEAR } from "near-api-js/tokens"

// Connect to testnet
const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" })

// Create account with signer
const account = new Account("my-account.testnet", provider, "ed25519:...")

Import Cheatsheet

// Core
import { Account, actions, JsonRpcProvider, FailoverRpcProvider } from "near-api-js"
import { KeyPair, PublicKey, KeyType } from "near-api-js"

// Tokens
import { NEAR, FungibleToken, NFTContract } from "near-api-js/tokens"
import { USDC, wNEAR } from "near-api-js/tokens/mainnet"

// Seed phrases
import { generateSeedPhrase, parseSeedPhrase } from "near-api-js/seed-phrase"

// Signers
import { KeyPairSigner, MultiKeySigner, Signer } from "near-api-js"

// Units
import { nearToYocto, yoctoToNear, teraToGas, gigaToGas } from "near-api-js"

// Transactions
import { createTransaction, signTransaction } from "near-api-js"

// Error handling
import { TypedError, parseTransactionExecutionError } from "near-api-js"

Core Modules

Account

Main class for account operations.

const account = new Account(accountId, provider, privateKey)

// Get state
const state = await account.getState()  // { balance: { total, available, locked }, storageUsage }

// Transfer NEAR
await account.transfer({ receiverId: "bob.testnet", amount: NEAR.toUnits("1"), token: NEAR })

// Call contract
await account.callFunction({
  contractId: "contract.testnet",
  methodName: "set_greeting",
  args: { message: "Hello" },
  deposit: 0n,
  gas: 30_000_000_000_000n
})

// Sign and send transaction
await account.signAndSendTransaction({
  receiverId: "contract.testnet",
  actions: [
    actions.functionCall("method", { arg: "value" }, 30_000_000_000_000n, 0n),
    actions.transfer(1_000_000_000_000_000_000_000_000n)
  ]
})

Provider

RPC client for querying blockchain.

const provider = new JsonRpcProvider({ url: "https://rpc.mainnet.near.org" })

// Failover provider
const failover = new FailoverRpcProvider([
  new JsonRpcProvider({ url: "https://rpc.mainnet.near.org" }),
  new JsonRpcProvider({ url: "https://rpc.mainnet.pagoda.co" })
])

// Query methods
await provider.viewAccount({ accountId: "alice.near" })
await provider.viewAccessKey({ accountId, publicKey })
await provider.callFunction({ contractId, method: "get_greeting", args: {} })
await provider.viewBlock({ finality: "final" })
await provider.sendTransaction(signedTx)

Crypto

Key management and cryptographic operations.

import { KeyPair, PublicKey } from "near-api-js"

// Generate random keypair
const keyPair = KeyPair.fromRandom("ed25519")

// From string
const keyPair = KeyPair.fromString("ed25519:5Fg2...")

// Sign and verify
const { signature, publicKey } = keyPair.sign(data)
const verified = keyPair.verify(message, signature)

Tokens

FT and NFT support.

import { NEAR, FungibleToken } from "near-api-js/tokens"
import { USDC } from "near-api-js/tokens/mainnet"

// Unit conversion
NEAR.toUnits("1.5")  // 1500000000000000000000000n
NEAR.toDecimal(amount)  // "1.5"

// Transfer FT
await account.transfer({ receiverId: "bob.near", amount: USDC.toUnits("50"), token: USDC })

// Custom FT
const token = new FungibleToken("usdt.tether-token.near", { decimals: 6, name: "USDT", symbol: "USDT" })

Actions

All transaction actions.

import { actions } from "near-api-js"

actions.transfer(amount)
actions.functionCall(methodName, args, gas, deposit)
actions.createAccount()
actions.deployContract(wasmBytes)
actions.addFullAccessKey(publicKey)
actions.addFunctionAccessKey(publicKey, contractId, methodNames, allowance)
actions.deleteKey(publicKey)
actions.deleteAccount(beneficiaryId)
actions.stake(amount, publicKey)
actions.signedDelegate(signedDelegateAction)  // Meta transactions

RPC Endpoints

Common Patterns

View Contract State

const result = await provider.callFunction({
  contractId: "contract.near",
  method: "get_data",
  args: { key: "value" }
})

Change Contract State

await account.callFunction({
  contractId: "contract.near",
  methodName: "set_data",
  args: { key: "new_value" },
  gas: 30_000_000_000_000n,
  deposit: 0n
})

Batch Transactions

await account.signAndSendTransactions({
  transactions: [
    { receiverId: "bob.near", actions: [actions.transfer(NEAR.toUnits("1"))] },
    { receiverId: "alice.near", actions: [actions.transfer(NEAR.toUnits("2"))] }
  ]
})

Meta Transactions (Gasless)

// Create signed meta tx (user side)
const signedDelegate = await account.createSignedMetaTransaction({
  receiverId: "contract.near",
  actions: [actions.functionCall("method", {}, 30_000_000_000_000n, 0n)]
})

// Submit via relayer
await relayerAccount.signAndSendTransaction({
  receiverId: signedDelegate.delegateAction.senderId,
  actions: [actions.signedDelegate(signedDelegate)]
})

Contract Interface

import { Contract } from "near-api-js"

const contract = new Contract(account, "contract.near", {
  viewMethods: ["get_status"],
  changeMethods: ["set_status"]
})

const status = await contract.get_status()
await contract.set_status({ message: "Hello" })

Error Handling

import { parseTransactionExecutionError, TypedError, InvalidNonceError } from "near-api-js"

try {
  await account.signAndSendTransaction({ ... })
} catch (error) {
  if (error instanceof TypedError) {
    console.log(error.type, error.message)
  }
  if (error instanceof InvalidNonceError) {
    // Retry with fresh nonce
  }
}

Reference Documentation

For detailed patterns and advanced usage, see:

• API Patterns Reference - Complete Account/Provider method reference, type definitions
• Tokens Guide - FT/NFT operations, storage deposits, pre-defined tokens
• Key Management - KeyPair types, seed phrases, signers, access keys
• Meta Transactions - Gasless transactions, relayer integration
• Wallet Integration - Browser patterns, NEP-413 signing, sessions