---

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) NEP-413 message signing for authentication, (11) 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, KeyPairString } 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:..." as KeyPairString,
);

// View call (read-only, via provider)
const data = await provider.callFunction({
  contractId: "guestbook.near-examples.testnet",
  method: "get_messages",
  args: {},
});

// Change call (requires account)
await account.callFunction({
  contractId: "guestbook.near-examples.testnet",
  methodName: "add_message",
  args: { text: "Hello!" },
  gas: teraToGas("30"),
  deposit: nearToYocto("0.1"),
});

Import Cheatsheet

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

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

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

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

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

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

// Contract with ABI
import { Contract } from "near-api-js";

// Transform key into implicit account ID
import { keyToImplicitAddress } from "near-api-js";

// NEP-413 signing & verification
import { verifyMessage, signMessage } from "near-api-js/nep413";

import {
  RpcError,
  RpcMethodNotFoundError,
  RpcRequestParseError,
  ContractMethodNotFoundError,
  AccountDoesNotExistError,
  // and many more
} from "near-api-js/rpc-errors";

Core Modules

Account

Main class for account operations.

// With signer (can sign transactions)
const account = new Account(accountId, provider, privateKey);

// Without signer (read-only, can add signer later)
const account = new Account(accountId, provider);

// Add signer later
const signer = KeyPairSigner.fromSecretKey(privateKey);
account.setSigner(signer);

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

// Get balance (with optional token parameter)
const balance = await account.getBalance(); // NEAR balance
const balance = await account.getBalance(USDC); // FT balance

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

// Transfer USDC
await account.transfer({
  receiverId: "bob.testnet",
  amount: USDC.toUnits("0.1"),
  token: USDC,
});

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

// Sign and send transaction with multiple actions
await account.signAndSendTransaction({
  receiverId: "contract.testnet",
  actions: [
    actions.functionCall(
      "method",
      { arg: "value" },
      teraToGas("30"),
      nearToYocto("0"),
    ),
    actions.transfer(nearToYocto("1")),
  ],
});

Account Management

// Add full access key
await account.addFullAccessKey(
  keyPair.getPublicKey(), // or string "ed25519:2ASWc..."
);

// Add function call access key
await account.addFunctionCallAccessKey({
  publicKey: keyPair.getPublicKey(), // or string "ed25519:2ASWc..."
  contractId: "contract.testnet",
  methodNames: ["example_method"],
  allowance: nearToYocto("0.25"), // use "0" for unlimited
});

// Delete key
await account.deleteKey(keyPair.getPublicKey()); // or string "ed25519:2ASWc..."

// Delete account and transfer remaining NEAR tokens to beneficiary (FTs and NFTs must be transferred manually before deleting account)
await account.deleteAccount("beneficiary.testnet");

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://free.rpc.fastnear.com" }),
  new JsonRpcProvider({ url: "https://rpc.mainnet.near.org" }),
]);

// Query methods
await provider.viewAccount({ accountId: "alice.near" });
await provider.viewAccessKey({
  accountId: "alice.near",
  publicKey: keyPair.getPublicKey(), // or string "ed25519:2ASWc..."
});
await provider.viewAccessKeyList({ accountId: "alice.near" });
// read-only call to contract method
await provider.callFunction({
  contractId: "contract.testnet",
  method: "get_greeting",
  args: {},
});
await provider.viewBlock({ finality: "final" });
await provider.sendTransaction(signedTx);

Signers

import { KeyPairSigner, MultiKeySigner } from "near-api-js";

// signer shouldn't be used directly for most use cases, instead it's used internally by Account class
const signer = KeyPairSigner.fromSecretKey(privateKey); // or "new KeyPairSigner(keyPair)"

const account = new Account(accountId, provider, signer);

Contract (with ABI)

import { Contract, AbiRoot } from "near-api-js";

// ABI definition requires "as const" (const assertions), otherwise types won't be inferred correctly
const abi = {
  schema_version: "0.4.0",
  metadata: {},
  body: {
    functions: [
      {
        name: "add_message",
        kind: "call",
        modifiers: ["payable"],
        params: {
          serialization_type: "json",
          args: [
            {
              name: "text",
              type_schema: {
                type: "string",
              },
            },
          ],
        },
      },
      {
        name: "total_messages",
        kind: "view",
        result: {
          serialization_type: "json",
          type_schema: {
            type: "integer",
            format: "uint32",
            minimum: 0.0,
          },
        },
      },
    ],
    root_schema: {},
  },
} as const satisfies AbiRoot;

const contract = new Contract({
  contractId: "guestbook.near-examples.testnet",
  provider: provider,
  abi: abi,
});

// the interface of view and call methods are fully inferred from the ABI, including argument and return types
const total = await contract.view.total_messages();
await contract.call.add_message({
  account: account,
  args: { text: "Hello, NEAR!" },
  deposit: nearToYocto("0.1"),
});

Contract (without ABI)

import { Contract, AbiRoot } from "near-api-js";

const contract = new Contract({
  contractId: "guestbook.near-examples.testnet",
  provider: provider,
});

// the interface of view and call methods are generic and not inferred without ABI, so you need to specify argument and return types manually using generics
const total = await contract.view.total_messages<number>({ args: {} });
await contract.call.add_message<void>({
  account: account,
  args: { text: "Hello, NEAR!" },
  deposit: nearToYocto("0.1"),
});

Seed Phrases

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

const { seedPhrase, keyPair } = generateSeedPhrase();

const keyPair = parseSeedPhrase("word1 word2 ... word12");

// Use with Account
const account = new Account(accountId, provider, new KeyPairSigner(keyPair));

Tokens

import { NEAR, FungibleToken } from "near-api-js/tokens";
import { USDT } from "near-api-js/tokens/testnet";

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

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

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

// Transfer custom Fungible Token
const REF = new FungibleToken("ref.fakes.testnet", {
  decimals: 18,
  symbol: "REF",
  name: "REF Token",
});
await account.transfer({
  token: REF,
  amount: REF.toUnits("1"),
  receiverId: "bob.testnet",
});

// NEP-141 requires the receiver to be registered before receiving tokens, usually it's the receiver's responsibility to register their account, but in some cases the sender might want to cover the registration cost for the receiver
await USDT.registerAccount({
  accountIdToRegister: "bob.testnet",
  fundingAccount: account,
});

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);

RPC Endpoints

| Network | URL | | ------------------ | ------------------------------- | | Mainnet | https://rpc.mainnet.near.org | | Mainnet (FastNEAR) | https://free.rpc.fastnear.com | | Testnet | https://rpc.testnet.near.org | | Testnet (FastNEAR) | https://test.rpc.fastnear.com |

Common Patterns

Batch Actions

await account.signAndSendTransaction({
  receiverId: account.accountId,
  actions: [
    actions.addFullAccessKey(key1.getPublicKey()),
    actions.addFullAccessKey(key2.getPublicKey()),
  ],
});

Meta Transactions

// Create and sign meta tx (user side)
const metaTx = await userAccount.createSignedMetaTransaction({
  receiverId: "contract.near",
  actions: [
    actions.functionCall("method", {}, teraToGas(10), nearToYocto("0")),
  ],
});

// Relay via funded account
const result = await relayerAccount.relayMetaTransaction(metaTx.signedDelegate);

Implicit Accounts

// keep in mind that implicit accounts don't actually exist on-chain until they receive at least 1 yoctoNEAR
const account = new Account(
  keyToImplicitAddress(keyPair.getPublicKey()), // implicit account ID derived from public key
  provider,
  new KeyPairSigner(keyPair),
);

NEP-413

import { signMessage, verifyMessage } from "near-api-js/nep413";

const account = new Account("bob.near", provider, new KeyPairSigner(keyPair));

const signedMessage = await signMessage({
  signerAccount: account, // requires signer to be set on account
  payload: {
    message: "Hello, world!",
    recipient: "alice.near",
    nonce: new Uint8Array(new Array(32)), // random 32 bytes
  },
});

// throws an Error if verification fails
await verifyMessage({
  signerAccountId: account.accountId,
  signerPublicKey: keyPair.getPublicKey(),
  signature: signedMessage.signature,
  payload: {
    message: "Hello, world!",
    recipient: