Interact with the NEAR blockchain using a simple REST API.
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. |
- NEAR Account (with access to private key or seed phrase)
- Node.js
- npm or Yarn
- API request tool such as Postman
- Clone repository
git clone [email protected]: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",
"init_disabled": true
}
Note: init_disabled
determines if params can be changed via /init
route.
- Start server
node app
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": ""
}
}
}
]
}
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
}
]
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": ""
}
}
}
]
}
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."
}
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
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"
}
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"
}
Displays account balance in yoctoNEAR (10^-24 NEAR).
Method: GET
Example:
http://localhost:3000/balance/name.testnet
Example Response:
199999959035075000000000000
Generates Ed25519 key pair.
Method: GET
Example:
http://localhost:3000/keypair
Example Response:
{
"public_key": "ed25519:3pNJK3fwP14UEbPjQqgDASwWR4XmbAEQBeNsyThhtNKY",
"private_key": "3s9nVrCU4MER3w9cxXcJM58RGRzFNJnLzo9vgQiNrkuGW3Xp7Up6cYnY4JKQZ7Qp3GhmXckrApRyDPAfzo2oCm8a"
}
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"
}
]
Mints a new NFT on a specified contract.
Method: POST
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",
}
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)
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)
Transfers ownership of NFT from specified contract on behalf of provided
enforce_owner_id
signed withowner_private_key
.
Method: POST
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)
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)
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": []
}
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": []
}
Use the following tags below to use random data for testing purposes.
{username}
{number}
{word}
{words}
{image}
{color}