Skip to main content

NEAR API

The NEAR API is a set of libraries that allow you to interact with the NEAR blockchain. You can use it to in frontend and backend applications to:

  • Call functions on a deployed contract
  • Query information about an account
  • Create NEAR accounts
  • Send Tokens such as NEAR, FTs, and NFTs
  • Create, Add and Delete Account Keys
  • Deploy a contract

Our API is available in multiple languages, including:

Wallet Integration

To allow users to login into your web application using a wallet you will need the wallet-selector. Read more in our Web Frontend integration article

Install​

Include near-api-js as a dependency in your package.

npm i near-api-js
Static HTML

If you are building a site without using npm, you can include the library directly in your HTML file through a CDN.

<script src="https://cdn.jsdelivr.net/npm/near-api-js/dist/near-api-js.min.js"></script>

Import​

You can use the API library in the browser, or in Node.js runtime.

Using the API in Node.js

All these examples are written for the browser, to use these examples in Node.js you should convert the project to an ES module. To do this, add the following to your package.json:

Connecting to NEAR​

The object returned from connect is your entry-point for all commands in the API. To transactions you'll need a KeyStore.

Mainnet/Localnet connection
// Mainnet config example
const connectionConfig = {
  networkId: "mainnet",
  keyStore: myKeyStore,
  nodeUrl: "https://rpc.mainnet.near.org",
};

// Localnet config example
const connectionConfig = {
  networkId: "local",
  nodeUrl: "http://localhost:3030",
};

Key Handlers: Stores & Signers​

To sign transactions you'll need to a KeyStore with valid keypairs.

BrowserLocalStorageKeyStore can only be used in the browser, it uses the browser's local storage to store the keys.

// Creates keyStore using private key in local storage

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

RPC Failover​

RPC providers can experience intermittent downtime, connectivity issues, or rate limits that cause client transactions to fail. This can be prevented by using the FailoverRpcProvider that supports multiple RPC providers.

Account​

Instantiate Account​

This will return an Account object for you to interact with.

Get Balance​

Gets the available and staked balance of an account in yoctoNEAR.

Get State​

Get basic account information, such as its code hash and storage usage.

Get Details​

Returns the authorized apps of an account. This is a list of contracts that the account has function call access keys for.

Create an Account​

In order to create .near or .testnet accounts, you need to make a function call to the top-level-domain account (i.e. near or testnet), calling create_account. In this example we generate a new public key for the account by generating a random private key.

The deposit determines the initial balance of the account.

Creating an account from a seed phrase

You can also create an account with a public key that is derived from a randomly generated seed phrase.

Create a Sub-Account​

Accounts can create sub-accounts of themselves, which are useful for creating separate accounts for different purposes. It is important to remark that the parent account has no control over any of its sub-accounts.

The deposit determines the initial balance of the account.

Delete Account​

When deleting an account, you need to specify a beneficiary account id. This is the account that will receive the remaining NEAR balance of the account being deleted.

warning

Only NEAR tokens will be transferred to the beneficiary, so you should transfer all your FTs, NFTs, etc. to another account before deleting.

danger

If the beneficiary account does not exist, the NEAR tokens will be burned

Transactions​

Send Tokens​

Transfer NEAR tokens between accounts.

Call Function​

A call function changes the contract's state and requires a signer/keypair.

Batch Actions​

You can send multiple actions in a batch to a single receiver. If one action fails then the entire batch of actions will be reverted.

Simultaneous Transactions​

Transactions can be sent in parallel to the network, so you don't have to wait for one transaction to complete before sending the next one. Note that these one transaction could be successful and the other one could fail.

Deploy a Contract​

You can deploy a contract from a compiled WASM file.

View Function​

View functions are read-only functions that don't change the state of the contract. We can call these functions without a signer / keypair or any gas.

Keys​

Get All Access Keys​

List all the access keys for an account.

Add Full Access Key​

Add a new full access key to an account. Here we generate a random keypair, alternatively you can use a keypair from a seed phrase.

Add Function Call Key​

Add a new function call key to an account. When adding the key you should specify the contract id the key can call, an array of methods the key is allowed to call, and the allowance in gas for the key.

Delete Access Key​

When deleting an access key, you need to specify the public key of the key you want to delete.

Validate Message Signatures​

Users can sign messages using the wallet-selector signMessage method, which returns a signature. This signature can be verified using the following code:

Utilities​

NEAR to yoctoNEAR​

Convert an amount in NEAR to an amount in yoctoNEAR.

Format Amount​

Format an amount in yoctoNEAR to an amount in NEAR.

Additional resources​

Was this page helpful?
Need some help? Chat with us or check our Dev Resources!
Twitter
Telegram
Discord
Zulip
Edit this page
Last updated on by Guillermo Alejandro Gallardo Diez