Skip to content

Interact with the NEAR blockchain using a simple REST API.

Notifications You must be signed in to change notification settings

near-examples/near-api-rest-server

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NEAR REST API SERVER

Interact with the NEAR blockchain using a simple REST API.

Live Demo:

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.
/keypair GET Generates Ed25519 key pair.
/explorer POST Run SELECT query in NEAR explorer database.
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


Setup

  1. Clone repository
git clone [email protected]:near-examples/near-api-server.git
  1. Install dependencies
npm install
  1. Configure near-api-server.config.json

Default settings:

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

Note: init_disabled determines if params can be changed via /init route.

  1. 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."
}

/sign_url

Generates a link to NEAR Wallet with provided transaction details. May be used to redirect user to the wallet and perform a transaction without generation application-specific keys and granting access.

Method: POST

Param Description
account_id Signer Account
receiver_id Recipient contract account, may be dApp contract or personal account
method Contract method to call. Use !transfer to transfer NEAR tokens
params Transaction arguments
deposit Attached deposit in NEAR
gas Attached gas in yoctoNEAR
meta Transaction meta. May be empty
callback_url URL to redirect user after the transaction. May be empty
network Your network: mainnet/testnet

Example:

{
	"account_id": "zavodil.testnet",
	"receiver_id": "inotel.pool.f863973.m0",
	"method": "ping",
	"params": {},
	"deposit": 0,
	"gas": 30000000000000,	
	"meta": "",
	"callback_url": "",
	"network": "testnet"
}

Example Response:

    https://wallet.testnet.near.org/sign?transactions=DwAAAHphdm9kaWwudGVzdG5ldADKei8CC%2BlhIM9GNPitr87eHXpqdnQsCdLD%2B0ADdTJbqwEAAAAAAAAAFgAAAGlub3RlbC5wb29sLmY4NjM5NzMubTCfZPsioMcZCQRg4Uy7rOu4ERg10QV9c415FuXE0VDRRAEAAAACBAAAAHBpbmcCAAAAe30A4FfrSBsAAAAAAAAAAAAAAAAAAAAAAAA%3D&callbackUrl=

Approving this url performed a transaction 143c9MNaqXFXuiobjUaQ8FPSBR2ukYbCMzGdPe6HqXEq

/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:https://localhost:3000/balance/name.testnet

Example Response:

199999959035075000000000000

/keypair

Generates Ed25519 key pair.

Method: GET

Example:

http:https://localhost:3000/keypair

Example Response:

{
  "public_key": "ed25519:3pNJK3fwP14UEbPjQqgDASwWR4XmbAEQBeNsyThhtNKY",
  "private_key": "3s9nVrCU4MER3w9cxXcJM58RGRzFNJnLzo9vgQiNrkuGW3Xp7Up6cYnY4JKQZ7Qp3GhmXckrApRyDPAfzo2oCm8a"
}

/explorer

Run SELECT query in NEAR explorer database.

Method: POST

Param Description
user Public account, public_readonly
host NEAR indexer host, testnet.db.explorer.indexer.near.dev
database Name of the database, testnet_explorer
password Password, nearprotocol
port Port, 5432
parameters Array of query parameters, []
query Query without tabs, linebreaks and special characters

Check indexer server credentials on a github.

Example:

{
  "user": "public_readonly",
  "host": "35.184.214.98",
  "database": "testnet_explorer",
  "password": "nearprotocol",
  "port": 5432,
  "parameters": ["testnet", 1],
  "query": "SELECT * FROM action_receipt_actions WHERE receipt_receiver_account_id = $1 LIMIT $2"
}
Example Response:

[
  {
    "receipt_id": "GZMyzjDWPJLjrCuQG82uHj3xRVHwdDnWHH1gCnSBejkR",
    "index_in_action_receipt": 0,
    "action_kind": "TRANSFER",
    "args": {
      "deposit": "1273665187500000000"
    },
    "receipt_predecessor_account_id": "system",
    "receipt_receiver_account_id": "testnet",
    "receipt_included_in_block_timestamp": "1619207391172257749"
  }
]


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:https://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}

Video Presentation

Live App Review 15 - NFT Server Side API

About

Interact with the NEAR blockchain using a simple REST API.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 90.2%
  • HTML 6.3%
  • CSS 3.5%