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
Network URL
Mainnet https://rpc.mainnet.near.org
Mainnet (Pagoda) https://rpc.mainnet.pagoda.co
Mainnet (FastNEAR) https://free.rpc.fastnear.com
Testnet https://rpc.testnet.near.org
Testnet (FastNEAR) https://test.rpc.fastnear.com
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