NEAR REST API SERVER

Interact with the NEAR blockchain using a simple REST API.

Overview

Click on a route for more information and examples

Route	Method	Description
CONTRACTS
`/deploy`	POST	Deploys a smart contract on NEAR.
`/view`	POST	Performs a smart contract view call with no gas burnt.
`/call`	POST	Performs a smart contract change call that burns gas.

UTILS
`/init`	POST	Initializes the master account and updates `near-api-server-config.json`
`/create_user`	POST	Creates a NEAR sub-account and stores credentials in `/storage`.
`/parse_seed_phrase`	POST	Displays public and private key pair from a given seed phrase.
`/balance`	GET	Displays account balance.

NFT EXAMPLE
`/mint_nft`	POST	Mints an NFT for a given contract.
`/transfer_nft`	POST	Transfers NFT ownership to a specified account.
`/view_nft`	POST	Returns owner, metadata, and approved account IDs for a given token ID.

Requirements

NEAR Account (with access to private key or seed phrase)
Node.js
npm or Yarn
API request tool such as Postman

Setup

Clone repository

git clone git@github.com:near-examples/near-api-server.git

Install dependencies

npm install

Configure near-api-server.config.json

Default settings:

{
  "server_host": "localhost",
  "server_port": 3000,
  "rpc_node": "https://rpc.testnet.near.org",
  "allow_rpc_update": false
}

Note: allow_rpc_update determines if this param can be changed via /init route.

Start server

node app

Contracts

`/deploy`

Deploys a smart contract to the NEAR blockchain based on the wasm file located in /contracts folder.

Method: POST

Param	Description
`account_id`	Account id that you will be deploying the contract to.
`seed_phrase` OR `private_key`	Seed phrase OR private key of the account id above.
`contract`	wasm file of compiled contract located in the `/contracts` folder of this project.

Note: Use near login to save your key pair to your local machine.

Example:

{
  "account_id": "example.testnet",
  "seed_phrase": "witch collapse practice feed shame open despair creek road again ice least",
  "contract": "nft_simple.wasm"
}

Example Response:

{
  "status": {
    "SuccessValue": ""
  },
  "transaction": {
    "signer_id": "example.testnet",
    "public_key": "ed25519:Cgg4i7ciid8uG4K5Vnjzy5N4PXLst5aeH9ApRAUA3y8U",
    "nonce": 5,
    "receiver_id": "example.testnet",
    "actions": [
      {
        "DeployContract": {
          "code": "hT9saWV3aok50F8JundSIWAW+lxOcBOns1zenB2fB4E="
        }
      }
    ],
    "signature": "ed25519:3VrppDV8zMMRXErdBJVU9MMbbKZ4SK1pBZqXoyw3oSSiXTeyR2W7upNhhZPdFJ1tNBr9h9SnsTVeBm5W9Bhaemis",
    "hash": "HbokHoCGcjGQZrz8yU8QDqBeAm5BN8iPjaSMXu7Yp2KY"
  },
  "transaction_outcome": {
    "proof": [
      {
        "hash": "Dfjn2ro1dXrPqgzd5zU7eJpCMKnATm295ceocX73Qiqn",
        "direction": "Right"
      },
      {
        "hash": "9raAgMrEmLpL6uiynMAi9rykJrXPEZN4WSxLJUJXbipY",
        "direction": "Right"
      }
    ],
    "block_hash": "B64cQPDNkwiCcN3SGXU2U5Jz5M9EKF1hC6uDi4S15Fb3",
    "id": "HbokHoCGcjGQZrz8yU8QDqBeAm5BN8iPjaSMXu7Yp2KY",
    "outcome": {
      "logs": [],
      "receipt_ids": ["D94GcZVXE2WgPGuaJPJq8MdeEUidrN1FPkuU75NXWm7X"],
      "gas_burnt": 1733951676474,
      "tokens_burnt": "173395167647400000000",
      "executor_id": "example.testnet",
      "status": {
        "SuccessReceiptId": "D94GcZVXE2WgPGuaJPJq8MdeEUidrN1FPkuU75NXWm7X"
      }
    }
  },
  "receipts_outcome": [
    {
      "proof": [
        {
          "hash": "3HLkv7KrQ9LPptX658QiwkFagv8NwjcxF6ti15Een4uh",
          "direction": "Left"
        },
        {
          "hash": "9raAgMrEmLpL6uiynMAi9rykJrXPEZN4WSxLJUJXbipY",
          "direction": "Right"
        }
      ],
      "block_hash": "B64cQPDNkwiCcN3SGXU2U5Jz5M9EKF1hC6uDi4S15Fb3",
      "id": "D94GcZVXE2WgPGuaJPJq8MdeEUidrN1FPkuU75NXWm7X",
      "outcome": {
        "logs": [],
        "receipt_ids": [],
        "gas_burnt": 1733951676474,
        "tokens_burnt": "173395167647400000000",
        "executor_id": "example.testnet",
        "status": {
          "SuccessValue": ""
        }
      }
    }
  ]
}

`/view`

Performs a smart contract view call that is free of charge (no gas burnt).

Method: POST

Param	Description
`contract`	Account id of the smart contract you are calling.
`method`	Name of the public method on the contract you are calling.
`params`	Arguments the method of the contract takes. Pass an empty object if no args are needed.

Example:

{
  "contract": "inotel.pool.f863973.m0",
  "method": "get_accounts",
  "params": { "from_index": 0, "limit": 5 }
}

Example Response:

[
  {
    "account_id": "ino.lockup.m0",
    "unstaked_balance": "0",
    "staked_balance": "2719843984800963837328608365424",
    "can_withdraw": true
  },
  {
    "account_id": "ino.testnet",
    "unstaked_balance": "2",
    "staked_balance": "3044983795632859169857527919579",
    "can_withdraw": true
  },
  {
    "account_id": "ino.stakewars.testnet",
    "unstaked_balance": "2",
    "staked_balance": "21704174266817478470830456026",
    "can_withdraw": true
  },
  {
    "account_id": "ds4.testnet",
    "unstaked_balance": "3",
    "staked_balance": "10891355794195012441764921",
    "can_withdraw": true
  },
  {
    "account_id": "32oijafsiodjfas.testnet",
    "unstaked_balance": "3",
    "staked_balance": "383757424103247547511904666",
    "can_withdraw": true
  }
]

`/call`

Performs a smart contract call that changes state and burns gas.

Method: POST

Param	Description
`account_id`	Account id that will be performing the call and will be charged for gas and attached tokens / deposit.
`seed_phrase` OR `private_key`	Seed phrase OR private key of the account id above.
`contract`	Account id of the smart contract you will be calling.
`method`	Public method on the smart contract that you will be calling.
`params`	Arguments the method of the contract takes. Pass an empty object if no args are needed.
`attached_gas`	Amount of gas you will be attaching to the call in TGas.
`attached_tokens`	Amount of tokens to be sent to the contract you are calling in yoctoNEAR (10^-24 NEAR).

Note: Use near login to save your key pair to your local machine.

Example:

{
  "account_id": "example.testnet",
  "private_key": "2Kh6PJjxH5PTTsVnYqtgnnwXHeafvVGczDXoCb33ws8reyq8J4oBYix1KP2ugRQ7q9NQUyPcVFTtbSG3ARVKETfK",
  "contract": "guest-book.testnet",
  "method": "addMessage",
  "params": { "text": "Hello World" },
  "attached_gas": "100000000000000",
  "attached_tokens": "0"
}

Example Response:

{
  "status": {
    "SuccessValue": ""
  },
  "transaction": {
    "signer_id": "example.testnet",
    "public_key": "ed25519:ASZEids5Qa8XMHX2S7LRL4bQRczi4YuMWXSM7S1HE5b",
    "nonce": 4,
    "receiver_id": "guest-book.testnet",
    "actions": [
      {
        "FunctionCall": {
          "method_name": "addMessage",
          "args": "eyJ0ZXh0IjoiSGVsbG8gV29ybGQifQ==",
          "gas": 100000000000000,
          "deposit": "0"
        }
      }
    ],
    "signature": "ed25519:4T9FqsjYBxcitjd5GgHrv3i3hcdcJSNcwwG3jBUgs7zZCZ3uShAK44Hi3oYFefhr8e5UW3LLD49ofRpGXKwGqqot",
    "hash": "CniHtfQVzcyVWJaUrQibJyGdhLi5axsjsoSRvvFbJ1jv"
  },
  "transaction_outcome": {
    "proof": [
      {
        "hash": "EkzDGbbBHSAuJcCPmhKSqbnBKyLrMgXkrTEZZZQudHeH",
        "direction": "Right"
      },
      {
        "hash": "36j4PK6fsLChiVTBQnXS1ywVSgJgHo7FtWzd5y5jkK1B",
        "direction": "Right"
      }
    ],
    "block_hash": "CUAu2deED8UX4vkerCbsTMR7YkeKt8RQXknYMNrVvM7C",
    "id": "CniHtfQVzcyVWJaUrQibJyGdhLi5axsjsoSRvvFbJ1jv",
    "outcome": {
      "logs": [],
      "receipt_ids": ["B7xAYoga5vrKERK7wY7EHa2Z74LaRJwqPsh4esLrKeQF"],
      "gas_burnt": 2427992549888,
      "tokens_burnt": "242799254988800000000",
      "executor_id": "example.testnet",
      "status": {
        "SuccessReceiptId": "B7xAYoga5vrKERK7wY7EHa2Z74LaRJwqPsh4esLrKeQF"
      }
    }
  },
  "receipts_outcome": [
    {
      "proof": [
        {
          "hash": "6Uo6BajpAxiraJEv69RwhjYnC86u56cw29vRDB1SV4dv",
          "direction": "Right"
        }
      ],
      "block_hash": "Ecq6pK74uiJFKxPTaasYuQcsEznnQjdzMAfsyrBpDo2u",
      "id": "B7xAYoga5vrKERK7wY7EHa2Z74LaRJwqPsh4esLrKeQF",
      "outcome": {
        "logs": [],
        "receipt_ids": ["6S6m1TYuVPYovLu9FHGV5oLRnDXeNQ8NhXxYjcr91xAN"],
        "gas_burnt": 3766420707221,
        "tokens_burnt": "376642070722100000000",
        "executor_id": "guest-book.testnet",
        "status": {
          "SuccessValue": ""
        }
      }
    },
    {
      "proof": [
        {
          "hash": "2za2YKUhyMfWbeEL7UKZxZcQbAqEmSPgPoYh9QDdeJQi",
          "direction": "Left"
        },
        {
          "hash": "61aHEiTBBbPU8UEXgSQh42TujFkHXQQMSuTh13PLPwbG",
          "direction": "Right"
        }
      ],
      "block_hash": "6LfpzvCBkqq7h5uG9VjAHMwSpC3HMMBSAGNGhbrAJzKP",
      "id": "6S6m1TYuVPYovLu9FHGV5oLRnDXeNQ8NhXxYjcr91xAN",
      "outcome": {
        "logs": [],
        "receipt_ids": [],
        "gas_burnt": 0,
        "tokens_burnt": "0",
        "executor_id": "example.testnet",
        "status": {
          "SuccessValue": ""
        }
      }
    }
  ]
}

Utils

`/init`

Configures near-api-server.config.json and creates a master account that stores credentials in this file. This allows for "simple methods" to be called where you won't have to pass as many parameters, primarily the master account id and private key or seed phrase.

ATTN: SERVER MUST BE RESTARTED AFTER CALLING THIS ENDPOINT

Method: POST

Param	Description
`master_account_id`	Master account that has full access to the NFT contract below
`seed_phrase` OR `private_key`	Seed phrase OR private key of the account id above.
`nft_contract`	Contract account that has NFT contract deployed to it
`server_host`	Public IP address for your API server (localhost is default)
`server_port`	(Port your API server will listen on)
`rpc_node`	Network your server will be running on (testnet, mainnet, or betanet)

Note: Use near login to save your key pair to your local machine.

Example:

{
  "master_account_id": "example.testnet",
  "seed_phrase": "seed phrase for master_account_id goes here",
  "nft_contract": "nft-contract.example.testnet",
  "server_host": "localhost",
  "server_port": 3000,
  "rpc_node": "https://rpc.testnet.near.org"
}

Example Response:

{
  "text": "Settings updated."
}

`/create_user`

Creates a NEAR sub-account using initialized master account and saves credentials to /storage directory. Requires /init configuration with master account.

Note: Only letters, digits, and - or _ separators are allowed.

Method: POST

Example:

{
    "name" : "satoshi"
}

Example Response:

{
  "text": "Account satoshi.example.testnet created. Public key: ed25519:HW4koiHqLi5WdVHWy9fqBWHbLRrzfmvCiRAUVhMa14T2"
}

`/parse_seed_phrase`

Converts seed phrase into public / private key pair.

Method: POST

Example:

{
    "seed_phrase" : "witch collapse practice feed shame open despair creek road again ice least"
}

Example Response:

{
    "seedPhrase": "witch collapse practice feed shame open despair creek road again ice least",
    "secretKey": "ed25519:41oHMLtYygTsgwDzaMdjWRq48Sy9xJsitJGmMxgA9A7nvd65aT8vQwAvRdHi1nruPP47B6pNhW5T5TK8SsqCZmjn",
    "publicKey": "ed25519:Cgg4i7ciid8uG4K5Vnjzy5N4PXLst5aeH9ApRAUA3y8U"
}

`/balance`

Displays account balance in yoctoNEAR (10^-24 NEAR).

Method: GET

Example:

http://localhost:3000/balance/name.testnet

Example Response:

199999959035075000000000000

NFTs

`/mint_nft`

Mints a new NFT on a specified contract.

Method: POST

Standard NFT Minting

Param	Description
`token_id`	ID for new token you are minting
`metadata`	Metadata for the new token as a string.
`account_id`	Account ID for the new token owner.
`seed_phrase` OR `private_key`	Seed phrase OR private key for the NFT contract.
`nft_contract`	Account ID for the NFT contract your are minting on.

Note: Use near login to save your key pair to your local machine.

Example:

{
    "token_id": "EXAMPLE-TOKEN",
    "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
    "account_id": "example.testnet",
    "private_key": "41oHMLtYygTsgwDzaMdjWRq48Sy9xJsitJGmMxgA9A7nvd65aT8vQwAvRdHi1nruPP47B6pNhW5T5TK8SsqCZmjn",
    "contract": "nft.example.near",
}

Simple NFT Minting

Requires /init configuration with master account.

Example:

{
  "token_id": "EXAMPLE_TOKEN",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu"
}

Example Response:

[
  {
    "token": {
      "owner_id": "example.testnet",
      "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
      "approved_account_ids": [],
      "token_id": "EXAMPLE_TOKEN"
    },
    "tx": "Be7tV1h2dvhg53S2rartojeSUbNfQTB7ypuprmb6xRhw"
  }
]

(tx is the transaction hash that can be queried in NEAR Explorer)

Batch NFT minting (simple)

Requires /init configuration with master account.

Example:

{
  "token_id": "EXAMPLE_TOKEN_{inc}",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
  "min": 31,
  "max": 33
}

(This creates EXAMPLE_TOKEN_31, EXAMPLE_TOKEN_32, & EXAMPLE_TOKEN_33)

Example Response:

[
  {
    "tx": "mAL92gb6g6hhubZBRewJk5vSwmmzm2SXmwdAfYqfWcG"
  },
  {
    "tx": "Dv9h8nWJLujkKpmw58ZR4QwAgPVprb4j5QarDUumoGEX"
  },
  {
    "tx": "J48F3vALJBbbUguKXp6e16g5vKVwzC2LtVBpsfEVFpYa"
  }
]

(Above response are transaction hashes that can be queried in NEAR Explorer)

`/transfer_nft`

Transfers ownership of NFT from specified contract on behalf of provided enforce_owner_id signed with owner_private_key.

Method: POST

Standard Transfer NFT

Param	Description
`token_id`	Token ID of the token being transferred
`receiver_id`	Account ID taking ownership of the NFT
`enforce_owner_id`	Account ID for the account that currently owns the NFT.
`memo`	Optional message to the new token holder.
`owner_private_key`	Private key of the `enforce_owner_id`.
`nft_contract`	NFT contract that the token being transferred is on.

Note: Use near login to save your key pair to your local machine.

Example:

{
  "token_id": "EXAMPLE-TOKEN",
  "receiver_id": "receiver.testnet",
  "enforce_owner_id": "example.testnet",
  "memo": "Here's a token I thought you might like! :)",
  "owner_private_key": "YOUR_PRIVATE_KEY",
  "contract": "nft.example.near"
}

Example Response:

{
  "owner_id": "receiver.testnet",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
  "approved_account_ids": [],
  "tx": "5WdNgmNeA5UNpSMDRXemwJc95MB6J22LcvAaimuN5YzF"
}

(tx is the transaction hash that can be queried in NEAR Explorer)

Simple Transfer NFTs

Requires /init configuration with master account.

Param	Description
`token_id`	Token ID of the token being transferred
`receiver_id`	Account ID taking ownership of the NFT
`enforce_owner_id`	Account ID for the account that currently owns the NFT.
`memo`	Optional message to new token holder.

Example:

{
  "token_id": "EXAMPLE-TOKEN",
  "receiver_id": "receiver.testnet",
  "enforce_owner_id": "example.testnet",
  "memo": "Here's a token I thought you might like! :)"
}

Example Response:

{
  "owner_id": "receiver.testnet",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
  "approved_account_ids": [],
  "tx": "5WdNgmNeA5UNpSMDRXemwJc95MB6J22LcvAaimuN5YzF"
}

(tx is the transaction hash that can be queried in NEAR Explorer)

`view_nft`

Standard View NFT

Returns owner, metadata, and approved account IDs for a given token ID.

Method: POST

Example:

{
  "token_id": "EXAMPLE-TOKEN",
  "contract": "nft.example.testnet"
}

Example response:

{
  "owner_id": "example.testnet",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
  "approved_account_ids": []
}

Simple View NFT

Receive detailed information about NFT using URL params. Requires /init configuration with master account.

Method: GET

Example:

http://localhost:3000/view_nft/EXAMPLE-TOKEN

Example Response:

{
  "owner_id": "example.testnet",
  "metadata": "https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu",
  "approved_account_ids": []
}

Faker data

Use the following tags below to use random data for testing purposes.

{username}
{number}
{word}
{words}
{image}
{color}

zavodil/near-api-server

NEAR REST API SERVER

Overview

Requirements

Setup

Contracts

`/deploy`

`/view`

`/call`

Utils

`/init`

`/create_user`

`/parse_seed_phrase`

`/balance`

NFTs

`/mint_nft`

Standard NFT Minting

Simple NFT Minting

Batch NFT minting (simple)

`/transfer_nft`

Standard Transfer NFT

Simple Transfer NFTs

`view_nft`

Standard View NFT

Simple View NFT

Faker data

Video Presentation