Skip to content
This repository has been archived by the owner on Jan 24, 2025. It is now read-only.

JSON RPC API

Jump to bottom
Marvin W edited this page Sep 24, 2018 · 47 revisions

This documentation is not yet completed. The Nimiq JSON-RPC interface is inspired by Ethereum, so some elements of their documentation apply as well.

Contents

JSON-RPC API

JSON is a lightweight data-interchange format.

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

remote.js Client

Note that the remote.js client is only intended for direct user interaction and thus requires all inputs to be made in NIM instead of the smallest unit. The docs below only apply to the underlying API that can be programatically used by any program.

JSON-RPC API Reference

Common data types

The Nimiq JSON-RPC API makes use of several simple and complex data types, that are described here.

Simple types

  • Integer - A JSON integer of up to 64 bits. Integers are unsigned by default if not specified otherwise.
  • Float - A JSON 64-bit floating point number, either as a decimal or using scientific notation.
  • String - A JSON string of arbitrary length, if not specified otherwise
  • Hash: String - A 32-byte hash, using Base64- or Hex-encoding
  • Address: String - A Nimiq account address, represented in user-friendly address format (NQ-address) or by its underlying 20 bytes, using Base64- or Hex-encoding

Complex data types

Complex data types are structured as a JSON-object with varioues fields.

AddressObject

Representation of a Nimiq address in two formats.

  • id: String - Hex-encoded 20 byte address.
  • address: String - User friendly address (NQ-address).
Wallet

Details on a wallet.

  • id: String - Hex-encoded 20 byte address.
  • address: String - User friendly address (NQ-address).
  • publicKey: String - Hex-encoded 32 byte Ed25519 public key.
  • privateKey: String (optional) - Hex-encoded 32 byte Ed25519 private key.
Transaction

Details on a transaction.

  • hash: String - Hex-encoded hash of the transaction.
  • blockHash: String (optional) - Hex-encoded hash of the block containing the transaction.
  • blockNumber: Integer (optional) - Height of the block containing the transaction.
  • timestamp: Integer (optional) - UNIX timestamp of the block containing the transaction.
  • confirmations: Integer (optional, default: 0) - Number of confirmations of the block containing the transaction.
  • transactionIndex: Integer (optional) - Index of the transaction in the block.
  • from: String - Hex-encoded address of the sending account.
  • fromAddress: String - Nimiq user friendly address (NQ-address) of the sending account.
  • to: String - Hex-encoded address of the recipient account.
  • toAddress: String - Nimiq user friendly address (NQ-address) of the recipient account.
  • value: Integer - Integer of the value (in smallest unit) sent with this transaction.
  • fee: Integer - Integer of the fee (in smallest unit) for this transaction.
  • data: String - (optional, default: null) Hex-encoded contract parameters or a message.
  • flags: Integer - Bit-encoded transaction flags.
OutgoingTransaction

Details on a transaction that is not yet send.

  • from: Address - The address the transaction is send from.
  • fromType: Integer - (optional, default: 0, Account.Type.BASIC) The account type at the given address (BASIC: 0, VESTING: 1, HTLC: 2).
  • to: Address - The address the transaction is directed to.
  • toType: Integer - (optional, default: 0, Account.Type.BASIC) The account type at the given address (BASIC: 0, VESTING: 1, HTLC: 2).
  • value: Integer - Integer of the value (in smallest unit) sent with this transaction.
  • fee: Integer - Integer of the fee (in smallest unit) for this transaction.
  • data: String - (optional, default: null) Hex-encoded contract parameters or a message.

Methods

accounts (TODO)

Returns a list of addresses owned by client.

Parameters

none

Returns

Array of ADDRESS, 20 Bytes - addresses owned by the client.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"accounts","params":[],"id":1}'

// Result
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [{id: "0x407d73d8a49eeb85d32cf465507dd71d507100c1", address: ""}]
}

blockNumber

Returns the height of most recent block.

Parameters

none

Returns

Integer - The current block height the client is on.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"blockNumber","params":[],"id":83}'

// Result
{
  "id":83,
  "jsonrpc": "2.0",
  "result": 1207
}

consensus

(TODO)

constant

(TODO)

createAccount

(TODO)

createRawTransaction

Creates and signs a transaction without sending it. The transaction can then be send via sendRawTransaction without accidentally replaying it.

Parameters
  1. OutgoingTransaction - The transaction object
params: [{
  "from": "NQ94 VESA PKTA 9YQ0 XKGC HVH0 Q9DF VSFU STSP",
  "to": "NQ16 61ET MB3M 2JG6 TBLK BR0D B6EA X6XQ L91U",
  "value": 100000, // 1 NIM
  "fee": 0 // 0 NIM
}]
Returns

String - the Hex-encoded transaction.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"createRawTransaction","params":[{see above}],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": "010000...abcdef"
}

getAccount

(TODO)

getBalance (TODO)

Returns the balance of the account of given address.

Parameters
  1. DATA, 20 Bytes - address to check for balance.
params: [
   '0x407d73d8a49eeb85d32cf465507dd71d507100c1'
]
Returns

QUANTITY - integer of the current balance in smalest unit.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBalance","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1"],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": 1589724902
}

getBlockByHash

(TODO)

getBlockByNumber

(TODO)

getBlockTransactionCountByHash

(TODO)

getBlockTransactionCountByNumber

(TODO)

getTransactionByBlockHashAndIndex

Returns information about a transaction by block hash and transaction index position.

Parameters
  1. Hash - Hash of the block containing the transaction
  2. Integer - Index of the transaction in the block
params: [{
  "dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f",
  20
}]
Returns

Transaction - A transaction object or null when no transaction was found.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendTransaction","params":["dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f", 20],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    "hash": "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554",
    "blockHash": "dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f",
    "blockNumber": 76415,
    "timestamp": 1528297445,
    "confirmations": 151281,
    "transactionIndex": 20,
    "from": "ad25610feb43d75307763d3f010822a757027429",
    "fromAddress": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
    "to": "824aa01033c89595479bab9d8deb3fc3a3e65e2d",
    "toAddress": "NQ44 G95A 041K R2AR AHUT MEEQ TSRY QEHX CPHD",
    "value": 418585560,
    "fee": 138,
    "data": null,
    "flags": 0
  }
}

getTransactionByBlockNumberAndIndex

Returns information about a transaction by block number and transaction index position.

Parameters
  1. Integer - Height of the block containing the transaction
  2. Integer - Index of the transaction in the block
params: [
  76415,
  20
]
Returns

Transaction - A transaction object or null when no transaction was found.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendTransaction","params":[76415,20],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    "hash": "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554",
    "blockHash": "dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f",
    "blockNumber": 76415,
    "timestamp": 1528297445,
    "confirmations": 151281,
    "transactionIndex": 20,
    "from": "ad25610feb43d75307763d3f010822a757027429",
    "fromAddress": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
    "to": "824aa01033c89595479bab9d8deb3fc3a3e65e2d",
    "toAddress": "NQ44 G95A 041K R2AR AHUT MEEQ TSRY QEHX CPHD",
    "value": 418585560,
    "fee": 138,
    "data": null,
    "flags": 0
  }
}

getTransactionByHash

Returns the information about a transaction requested by transaction hash.

Parameters
  1. Hash - Hash of a transaction
params: [
  "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"
]
Returns

Transaction - A transaction object or null when no transaction was found.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionByHash","params":["465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    "hash": "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554",
    "blockHash": "dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f",
    "blockNumber": 76415,
    "timestamp": 1528297445,
    "confirmations": 151281,
    "transactionIndex": 20,
    "from": "ad25610feb43d75307763d3f010822a757027429",
    "fromAddress": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
    "to": "824aa01033c89595479bab9d8deb3fc3a3e65e2d",
    "toAddress": "NQ44 G95A 041K R2AR AHUT MEEQ TSRY QEHX CPHD",
    "value": 418585560,
    "fee": 138,
    "data": null,
    "flags": 0
  }
}

getTransactionReceipt

Returns the receipt of a transaction by transaction hash.

Note That the receipt is not available for pending transactions.

Parameters
  1. String - Hex-encoded hash of a transaction
params: [
  "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"
]
Returns

Object - A transaction receipt object, or null when no receipt was found:

  • transactionHash : String - Hex-encoded hash of the transaction.
  • transactionIndex: Integer - Integer of the transactions index position in the block.
  • blockHash: String - Hex-encoded hash of the block where this transaction was in.
  • blockNumber: Integer - Block number where this transaction was in.
  • confirmations: Integer - Number of confirmations for this transaction (number of blocks on top of the block where this transaction was in).
  • timestamp: Integer - Timestamp of the block where this transaction was in.
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionReceipt","params":["465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"],"id":1}'

// Result
{
"id":1,
"jsonrpc":"2.0",
"result": {
    transactionHash: '465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554',
    transactionIndex:  1,
    blockNumber: 11,
    blockHash: 'c6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b',
    confirmations: 5,
    timestamp: 1529327401
  }
}

getTransactionsByAddress

(TODO)

hashrate

Returns the number of hashes per second that the node is mining with.

Parameters

none

Returns

Float - number of hashes per second.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"hashrate","params":[],"id":1}'

// Result
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": 52982.2731
}

log

(TODO)

mempool

(TODO)

mempoolContent

(TODO)

minerAddress

(TODO)

minerThreads

(TODO)

minFeePerByte

(TODO)

mining

Returns true if client is actively mining new blocks.

Parameters

none

Returns

Boolean - returns true of the client is mining, otherwise false.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"mining","params":[],"id":1}'

// Result
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": true
}

peerCount

Returns number of peers currently connected to the client.

Parameters

none

Returns

Number - integer of the number of connected peers.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"peerCount","params":[],"id":1}'

// Result
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": 12
}

peerList

(TODO)

peerState

(TODO)

pool

(TODO)

poolConfirmedBalance

(TODO)

poolConnectionState

(TODO)

sendRawTransaction

Sends a signed message call transaction or a contract creation, if the data field contains code.

Parameters
  1. String - The hex encoded signed transaction
params: [
  "010000...abcdef"
]
Returns

String - the Hex-encoded transaction hash.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendRawTransaction","params":[{see above}],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"
}

sendTransaction

Creates new message call transaction or a contract creation, if the data field contains code.

Parameters
  1. OutgoingTransaction - The transaction object
params: [{
  "from": "NQ94 VESA PKTA 9YQ0 XKGC HVH0 Q9DF VSFU STSP",
  "to": "NQ16 61ET MB3M 2JG6 TBLK BR0D B6EA X6XQ L91U",
  "value": 100000, // 1 NIM
  "fee": 0 // 0 NIM
}]
Returns

String - the Hex-encoded transaction hash.

Use getTransactionReceipt to get the transaction receipt after the transaction was mined.

Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"sendTransaction","params":[{see above}],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": "465a63b73aa0b9b54b777be9a585ea00b367a17898ad520e1f22cb2c986ff554"
}

syncing

Returns an object with data about the sync status or false.

Parameters

none

Returns

Object|Boolean, An object with sync status data or false, when not syncing:

  • startingBlock: Integer - The block at which the import started (will only be reset, after the sync reached his head)
  • currentBlock: Integer - The current block, same as blockNumber
  • highestBlock: Integer - The estimated highest block
Example
// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"syncing","params":[],"id":1}'

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    "startingBlock": 1,
    "currentBlock": 12345,
    "highestBlock": 23456
  }
}
// Or when not syncing
{
  "id":1,
  "jsonrpc": "2.0",
  "result": false
}
Clone this wiki locally