near-api-js

# near-api-js Skill

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

## Quick Start

```typescript
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

```typescript
// 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.

```typescript
// 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

```typescript
// 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.

```typescript
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

```typescript
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)

```typescript
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: {