Skip to main content

NEAR-API-JS Quick Reference

Here is a collection of the most commonly used methods within near-api-js. For more in-depth look into this library, please reference the TypeDocs.

Setup

Install

npm i near-api-js

Import

import * as nearAPI from "near-api-js";

Key Store

// creates keyStore using private key in local storage
// *** REQUIRES SignIn using walletConnection.requestSignIn() ***

const { keyStores } = nearAPI;
const keyStore = new keyStores.BrowserLocalStorageKeyStore();

Note: Key store is not required if you are not signing transactions (using view call methods on a contract)

Connect

const { connect } = nearAPI;

const config = {
networkId: "testnet",
keyStore,
nodeUrl: "https://rpc.testnet.near.org",
walletUrl: "https://wallet.testnet.near.org",
helperUrl: "https://helper.testnet.near.org",
explorerUrl: "https://explorer.testnet.near.org",
};
const near = await connect(config);

keyStore setup

Wallet

Connection

const { connect, keyStores, WalletConnection } = nearAPI;

const config = {
networkId: "testnet",
keyStore: new keyStores.BrowserLocalStorageKeyStore(),
nodeUrl: "https://rpc.testnet.near.org",
walletUrl: "https://wallet.testnet.near.org",
helperUrl: "https://helper.testnet.near.org",
explorerUrl: "https://explorer.testnet.near.org",
};

// connect to NEAR
const near = await connect(config);

// create wallet connection
const wallet = new WalletConnection(near);

Sign In

// redirects user to wallet to authorize your dApp
// this creates an access key that will be stored in the browser's local storage
// access key can then be used to connect to NEAR and sign transactions via keyStore

const signIn = () => {
wallet.requestSignIn(
"example-contract.testnet", // contract requesting access
"Example App", // optional
"http://YOUR-URL.com/success", // optional
"http://YOUR-URL.com/failure" // optional
);
};

Note: Sign In is not required if you are using an alternative key store to local storage or you are not signing transactions (using view call methods on a contract)

Sign Out

const signOut = () => {
wallet.signOut();
};

Check if Signed In

if(wallet.isSignedIn()) {
doSomething();
}

Get Authorized Account Id

// returns account Id as string
const walletAccountId = wallet.getAccountId();

Get Authorized Account Object

// returns account object for transaction signing
const walletAccountObj = wallet.account();

Account

Load Account

const near = await connect(config);
const account = await near.account("example-account.testnet");

config setup

Create Account

// creates a new account using funds from the account used to create it
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.createAccount(
"example-account2.testnet", // new account name
"8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for new account
"10000000000000000000" // initial balance for new account in yoctoNEAR
);

config setup

Delete Account

// deletes account found in the `account` object
// transfers remaining account balance to the accountId passed as an argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.deleteAccount("beneficiary-account.testnet");

config setup

Get Account Balance

// gets account balance
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccountBalance();

config setup

Get Account details

// gets account details in terms of authorized apps and transactions
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccountDetails();

config setup

Deploy a Contract

const near = await connect(config);
const account = await near.account("example-account.testnet");
const response = await account.deployContract(fs.readFileSync('./wasm_files/status_message.wasm'));
console.log(response);

config setup

Send Tokens

// sends NEAR tokens
const near = await connect(config);
const account = await near.account("sender-account.testnet");
await account.sendMoney(
"receiver-account.testnet", // receiver account
"1000000000000000000000000" // amount in yoctoNEAR
);

config setup

State

// gets the state of the account
const near = await connect(config);
const account = await near.account("example-account.testnet");
const response = await account.state();
console.log(response);

config setup

Contract

Load Contract

const contract = new nearAPI.Contract(
account, // the account object that is connecting
"example-contract.testnet",
{
// name of contract you're connecting to
viewMethods: ["getMessages"], // view methods do not change state but usually return a value
changeMethods: ["addMessage"], // change methods modify state
sender: account, // account object to initialize and sign transactions.
}
);

config setup

Call Contract

await contract.method_name(
{
arg_name: "value", // argument name and value - pass empty object if no args required
},
"300000000000000", // attached GAS (optional)
"1000000000000000000000000" // attached deposit in yoctoNEAR (optional)
);

Access Keys

Add Full Access Key

// takes public key as string for argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.addKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc");

config setup

Add Function Access Key

// adds function access key
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.addKey(
"8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for new account
"example-account.testnet", // contract this key is allowed to call (optional)
"example_method", // methods this key is allowed to call (optional)
"2500000000000" // allowance key can use to call methods (optional)
);

config setup

Get All Access Keys

// returns all access keys associated with an account
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccessKeys();

config setup

Delete Access Key

// takes public key as string for argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.deleteKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc");

config setup

Utils

NEAR => yoctoNEAR

// converts NEAR amount into yoctoNEAR (10^-24)

const { utils } = nearAPI;
const amountInYocto = utils.format.parseNearAmount("1");

YoctoNEAR => NEAR

// converts yoctoNEAR (10^-24) amount into NEAR

const { utils } = nearAPI;
const amountInNEAR = utils.format.formatNearAmount("1000000000000000000000000");