JSON RPC API

This documentation is not yet completed. You can check the JSON-RPC server implementation for details on non-documented methods.

Contents

JSON RPC API
- remote.js Client
- JSON RPC API Reference
  - Common data types
    - Simple types
    - Complex data types
  - Methods

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 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.

`Account`

Details on an account.

id: String - Hex-encoded 20 byte address.
address: String - User friendly address (NQ-address).
balance: Integer - Balance of the account (in smallest unit).
type: Integer - The account type associated with the account (BASIC: 0, VESTING: 1, HTLC: 2).

Additional fields for vesting contracts (type = 1)

owner: String - Hex-encoded 20 byte address of the owner of the vesting contract.
ownerAddress: String - User friendly address (NQ-address) of the owner of the vesting contract.
vestingStart: Integer - The block that the vesting contracted commenced.
vestingStepBlocks: Integer - The number of blocks after which some part of the vested funds is released.
vestingStepAmount: Integer - The amount (in smallest unit) released every vestingStepBlocks blocks.
vestingTotalAmount: Integer - The total amount (in smallest unit) that was provided at the contract creation.

Additional fields for Hashed Time-Locked Contracts (type = 2)

sender: String - Hex-encoded 20 byte address of the sender of the HTLC.
senderAddress: String - User friendly address (NQ-address) of the sender of the HTLC.
recipient: String - Hex-encoded 20 byte address of the recipient of the HTLC.
recipientAddress: String - User friendly address (NQ-address) of the recipient of the HTLC.
hashRoot: String - Hex-encoded 32 byte hash root.
hashCount: Integer - Number of hashes this HTLC is split into
timeout: Integer - Block after which the contract can only be used by the original sender to recover funds.
totalAmount: Integer - The total amount (in smallest unit) that was provided at the contract creation.

`AddressObject`

Representation of a Nimiq address in two formats.

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

`Block`

Details on a block.

number: Integer - Height of the block.
hash: String - Hex-encoded 32-byte hash of the block.
pow: String - Hex-encoded 32-byte Proof-of-Work hash of the block.
parentHash: String - Hex-encoded 32-byte hash of the predecessor block.
nonce: Integer - The nonce of the block used to fulfill the Proof-of-Work.
bodyHash: String - Hex-encoded 32-byte hash of the block body Merkle root.
accountsHash: String - Hex-encoded 32-byte hash of the accounts tree root.
miner: String - Hex-encoded 20 byte address of the miner of the block.
minerAddress: String - User friendly address (NQ-address) of the miner of the block.
difficulty: String - Block difficulty, encoded as decimal number in string. (TODO)
extraData: String - Hex-encoded value of the extra data field, maximum of 255 bytes.
size: Integer - Block size in byte.
timestamp: Integer - UNIX timestamp of the block
transactions: Array - Array of transactions. Either represented by the transaction hash or a Transaction object.
confirmations: Integer (optional, default: 0) - Number of confirmations on the block.

`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 sent.

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.

`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.

`Peer`

Details on a peer.

id: String - peer id.
address: String - peer address.
addressState: Integer - peer address state (NEW: 1, ESTABLISHED: 2, TRIED: 3, FAILED: 4, BANNED: 5).
connectionState: Integer (optional) - peer connection state (NEW: 1, CONNECTING: 2, CONNECTED: 3, NEGOTIATING: 4, ESTABLISHED: 5, CLOSED: 6).
version: Integer (optional) - node version the peer is running.
timeOffset: Integer (optional) - time offset with the peer (in miliseconds).
headHash: String (optional) - hash of the head block of the peer.
latency: Integer (optional) - latency to the peer.
rx: Integer (optional) - received bytes.
tx: Integer (optional) - sent bytes.

Methods

accounts

Returns a list of addresses owned by client.

Parameters

none

Returns

Account[], array of accounts 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": "ad25610feb43d75307763d3f010822a757027429",
      "address": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
      "balance": 1200000,  // 12 NIM
      "type": 0 // Basic
    }, {
      "id": "824aa01033c89595479bab9d8deb3fc3a3e65e2d",
      "address": "NQ44 G95A 041K R2AR AHUT MEEQ TSRY QEHX CPHD",
      "balance": 2400000, // 24 NIM
      "type": 0 // Basic
    }
  ]
}

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

Returns information on the current consensus state.

Parameters

none

Returns

String - String describing the consensus state. "established" is the value for a good state, other values indicate bad state.

Example

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

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

constant

Returns or overrides a constant value.

When no parameter is given, it returns the value of the constant. When giving a value as parameter, it sets the constant to the given value. To reset the constant to the default value, the parameter "reset" should be used.

Parameters

String - The class and name of the constant (format should be Class.CONSTANT).
Integer (optional) - The new value of the constant or "reset".

Returns

Integer- The value of the constant.

Example

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"constant","params":["BaseConsensus.MAX_ATTEMPTS_TO_FETCH", 10],"id":83}'

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

createAccount

Creates a new account and stores its private key in the client store.

Parameters

none

Returns

Wallet - Information on the wallet that was created using the command.

Example

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

// Result
{
  "id":83,
  "jsonrpc": "2.0",
  "result": {
    "id": "c2260ff07885654f8111e71f72967d397ec8c3c0",
    "address": "NQ30 Q8K0 YU3Q GMJL Y08H UUFP 55KV 75YC HGX0",
    "publicKey": "b7de7c978a6616d887fd16c62193402ba96c99005034833fbec0c0fe766fdf8b"
  }
}

createRawTransaction

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

Parameters

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

Returns details for the account of given address.

Parameters

Address - Address to get account details.

params: [
   'ad25610feb43d75307763d3f010822a757027429'
]

Returns

Account - Details about the account. Returns the default empty basic account for non-existing accounts.

Example

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

// Result
{
  "id":1,
  "jsonrpc": "2.0",
  "result": {
    "id": "ad25610feb43d75307763d3f010822a757027429",
    "address": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
    "balance": 1200000,  // 12 NIM
    "type": 0 // Basic
  }
}

getBalance

Returns the balance of the account of given address.

Parameters

Address - Address to check for balance.

params: [
   'ad25610feb43d75307763d3f010822a757027429'
]

Returns

Integer - The current balance at the specified address (in smalest unit).

Example

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

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

getBlockByHash

Returns information about a block by hash.

Parameters

Hash - Hash of the block to gather information on.
Boolean (optional, default false) - If true it returns the full transaction objects, if false only the hashes of the transactions.

params: [
  "14c91f6d6f3a0b62271e546bb09461231ab7e4d1ddc2c3e1b93de52d48a1da87",
  false
]

Returns

Block - A block object or null when no block was found.

Example

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getBlockByHash","params":["14c91f6d6f3a0b62271e546bb09461231ab7e4d1ddc2c3e1b93de52d48a1da87", false],"id":1}'

// Result
{
  "jsonrpc": "2.0",
  "result": {
    "number": 20,
    "hash": "14c91f6d6f3a0b62271e546bb09461231ab7e4d1ddc2c3e1b93de52d48a1da87",
    "pow": "000008df8cfee0a3b1dde716aec59df53fd3d984ae2220565b90d0aae5fa3153",
    "parentHash": "1a7306ecd1d1dff4d921c985e5cbc084275bfa6a8bed68549c3275d1c38614f6",
    "nonce": 67426,
    "bodyHash": "9c29ffd4da6ce51e1618cd0eb70731ff8e63c14ec2092424ac6e25f2983dd42f",
    "accountsHash": "27aa836a72b9eea1b5d890a0e20a9dfa5ada50d3a00e9788836144c0e85627d8",
    "miner": "0000000000000000000000000000000000000000",
    "minerAddress": "NQ07 0000 0000 0000 0000 0000 0000 0000 0000",
    "difficulty": "1.1886029345",
    "extraData": "4d696e65642077697468206c6f76652062792053696d6f6e",
    "size": 230,
    "timestamp": 1523727013,
    "transactions": []
  },
  "id": 1
}

getBlockByNumber

Returns information about a block by block number.

Parameters

Integer - The height of the block to gather information on.
Boolean (optional, default false) - If true it returns the full transaction objects, if false only the hashes of the transactions.

params: [
  76415,
  false
]

Returns

Block - A block object or null when no block was found.

Example

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

// Result
{
  "jsonrpc": "2.0",
  "result": {
    "number": 20,
    "hash": "14c91f6d6f3a0b62271e546bb09461231ab7e4d1ddc2c3e1b93de52d48a1da87",
    "pow": "000008df8cfee0a3b1dde716aec59df53fd3d984ae2220565b90d0aae5fa3153",
    "parentHash": "1a7306ecd1d1dff4d921c985e5cbc084275bfa6a8bed68549c3275d1c38614f6",
    "nonce": 67426,
    "bodyHash": "9c29ffd4da6ce51e1618cd0eb70731ff8e63c14ec2092424ac6e25f2983dd42f",
    "accountsHash": "27aa836a72b9eea1b5d890a0e20a9dfa5ada50d3a00e9788836144c0e85627d8",
    "miner": "0000000000000000000000000000000000000000",
    "minerAddress": "NQ07 0000 0000 0000 0000 0000 0000 0000 0000",
    "difficulty": "1.1886029345",
    "extraData": "4d696e65642077697468206c6f76652062792053696d6f6e",
    "size": 230,
    "timestamp": 1523727013,
    "transactions": []
  },
  "id": 1
}

getBlockTemplate

Returns a template to build the next block for mining. This will consider pool instructions when connected to a pool.

Parameters

Address - The address to use as a miner for this block. This overrides the address provided during startup or from the pool.
String - Hex-encoded value for the extra data field. This overrides the address provided during startup or from the pool.

Returns

Object - A block template object.

header: Object
- version: Integer - Version in block header.
- prevHash: String - 32-byte hex-encoded hash of the previous block.
- interlinkHash: String - 32-byte hex-encoded hash of the interlink.
- accountsHash: String - 32-byte hex-encoded hash of the accounts tree.
- nBits: Integer - Compact form of the hash target for this block.
- height: Integer - Height of the block in the block chain (also known as block number).
interlink: String - Hex-encoded interlink
body: Object
- hash: String - 32-byte hex-encoded hash of the block body.
- minerAddr: String - 20-byte hex-encoded miner address.
- extraData: String - Hex-encoded value of the extra data field.
- transactions: String[] - Array of hex-encoded transactions for this block.
- prunedAccounts: String[] - Array of hex-encoded pruned accounts for this block.
- merkleHashes: String[] - Array of hex-encoded hashes that verify the path of the miner address in the merkle tree. This can be used to change the miner address easily.
target: Integer - Compact form of the hash target to submit a block to this client.

getBlockTransactionCountByHash

Returns the number of transactions in a block from a block matching the given block hash.

Parameters

Hash - Hash of the block.

params: [
  "dfe7d166f2c86bd10fa4b1f29cd06c13228f893167ce9826137c85758645572f"
]

Returns

Integer - Number of transactions in the block found, or null, when no block was found.

Example

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

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

getBlockTransactionCountByNumber

Returns the number of transactions in a block matching the given block number.

Parameters

Integer - Height of the block.

params: [
  76415
]

Returns

Integer - Number of transactions in the block found, or null, when no block was found.

Example

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

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

getTransactionByBlockHashAndIndex

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

Parameters

Hash - Hash of the block containing the transaction
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":"getTransactionByBlockHashAndIndex","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

Integer - Height of the block containing the transaction
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":"getTransactionByBlockNumberAndIndex","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

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

Hash - 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

Returns the latest transactions successfully performed by or for an address.

Note That this information might change when blocks are rewinded on the local state due to forks.

Parameters

Address - Address of which transactions should be gathered.
Integer (optional, default 1000) - Number of transactions that shall be returned.

params: [
  "NQ69 9A4A MB83 HXDQ 4J46 BH5R 4JFF QMA9 C3GN"
]

Returns

Transaction[] - Array of transactions linked to the requested address.

Note The array will not contain more than the requested amount of transactions, but might contain less, even when more transactions happened. Any interpretation of the length of this array might result in wrong assumptions.

Example

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"getTransactionsByAddress","params":["NQ69 9A4A MB83 HXDQ 4J46 BH5R 4JFF QMA9 C3GN"],"id":1}'

// Result
{
  "id":1,
  "jsonrpc":"2.0",
  "result": [
    {
      "hash": "745e19018e785cd8f05219578cceb6620d32f9c500ea1e4e9c0e416216984fe7",
      "blockHash": "119657593bf6ac9e2b2a46ce28cd36a016ee0277f585235297c6a1e01b918a24",
      "blockNumber": 79569,
      "timestamp": 1528487555,
      "confirmations": 156156,
      "transactionIndex": 0,
      "from": "4a88aaad038f9b8248865c4b9249efc554960e16",
      "fromAddress": "NQ69 9A4A MB83 HXDQ 4J46 BH5R 4JFF QMA9 C3GN",
      "to": "ad25610feb43d75307763d3f010822a757027429",
      "toAddress": "NQ15 MLJN 23YB 8FBM 61TN 7LYG 2212 LVBG 4V19",
      "value": 8000000000000,
      "fee": 0,
      "data": null,
      "flags": 0
    },
    {...},
    {...},
    {...}
  ]
}

getWork

Returns instructions to mine the next block. This will consider pool instructions when connected to a pool.

Parameters

Address - The address to use as a miner for this block. This overrides the address provided during startup or from the pool.
String - Hex-encoded value for the extra data field. This overrides the address provided during startup or from the pool.

Returns

Object - Mining work instructions

data: String - Hex-encoded block header. This is what should be passed through the hash function. The last 4 bytes describe the nonce, the 4 bytes before are the current timestamp. Most implementations allow the miner to arbitrarily choose the nonce and to update the timestamp without requesting new work instructions.
suffix: String - Hex-encoded block without the header. When passing a mining result to submitBlock, append the suffix to the data string with selected nonce.
target: Integer - Compact form of the hash target to submit a block to this client.
algorithm String - Field to describe the algorithm used to mine the block. Always nimiq-argon2 for now.

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

Sets the log level of the node.

Parameters

String - Tag: If '*' the log level is set globally, otherwise the log level is applied only on this tag.
String - Minimum log level to display. (Valid options: trace, verbose, debug, info, warn, error, assert)

Example

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

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

mempool

Returns information on the current mempool situation. This will provide an overview of the number of transactions sorted into buckets based on their fee per byte (in smallest unit).

Parameters

none

Returns

Object - Mempool information

total: Integer - Total number of pending transactions in mempool.
buckets Integer[] - Array containing a subset of fee per byte buckets from [10000, 5000, 2000, 1000, 500, 200, 100, 50, 20, 10, 5, 2, 1, 0] that currently have more than one transaction.
any of the numbers present in buckets: Integer - Number of transaction in the bucket. A transaction is assigned to the highest bucket of a value lower than its fee per byte value.

Example

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

// Result
{
  "jsonrpc": "2.0",
  "result": {
    "0": 2,
    "2": 1,
    "total": 3,
    "buckets": [
      2,
      0
    ]
  },
  "id": "1"
}

mempoolContent

Returns transactions that are currently in the mempool.

Parameters

Boolean (optional, default is false) - if true includes full transactions, if false includes only transaction hashes

Returns

Transaction[] or String[] - Array of transactions (either represented by the transaction hash or a transaction object).

Example (default, hashes only)

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

// Result
{
    "jsonrpc": "2.0",
    "result": [
        "5bb722c2afe25c18ba33d453b3ac2c90ac278c595cc92f6188c8b699e8fb006a",
        "9cd9c1d0ffcaebfcfe86bc2ae73b4e82a488de99c8e3faef92b05432bb94519c"
    ],
    "id": 1
}

Example (with full transactions)

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

// Result
{
    "jsonrpc": "2.0",
    "result": [
        {
            "hash": "5bb722c2afe25c18ba33d453b3ac2c90ac278c595cc92f6188c8b699e8fb006a",
            "from": "f3a2a520967fb046deee40af0c68c3dc43ef3238",
            "fromAddress": "NQ04 XEHA A84N FXQ4 DPPE 82PG QS63 TH1X XCHQ",
            "to": "ca9e687c4e760e5d6dd4a789c577cefe1338ad2c",
            "toAddress": "NQ77 RAF6 GY2E EQ75 STEL LX4U AVXE YQ9K HB9C",
            "value": 9286543536,
            "fee": 1380,
            "data": null,
            "flags": 0
        },
        {
            "hash": "9cd9c1d0ffcaebfcfe86bc2ae73b4e82a488de99c8e3faef92b05432bb94519c",
            "from": "f3a2a520967fb046deee40af0c68c3dc43ef3238",
            "fromAddress": "NQ04 XEHA A84N FXQ4 DPPE 82PG QS63 TH1X XCHQ",
            "to": "d497b15fe0857394f3e485c87e00fa44270fcd4d",
            "toAddress": "NQ60 SJBT 2PY0 GMRR 9UY4 GP47 U07S 8GKG YKAD",
            "value": 1038143325,
            "fee": 1380,
            "data": null,
            "flags": 0
        }
    ],
    "id": 1
}

minerAddress

Returns the miner address.

Parameters

none

Returns

String - The miner address configured on the node.

Example

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

// Result
{
    "jsonrpc": "2.0",
    "result": "NQ39 NY67 X0F0 UTQE 0YER 4JEU B67L UPP8 G0FM",
    "id": 1
}

minerThreads

Returns or sets the number of CPU threads for the miner.

When no parameter is given, it returns the current number of miner threads. When a value is given as parameter, it sets the number of miner threads to that value.

Parameters

Integer (optional) - The number of threads to allocate for mining.

Returns

Integer - The current number of miner threads.

Example (getting the current number of threads)

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

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

Example (setting a new number of threads)

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

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

minFeePerByte

Returns or sets the minimum fee per byte.

When no parameter is given, it returns the current minimum fee per byte. When a value is given as parameter, it sets the minimum fee per byte to that value.

Parameters

Integer (optional) - The new minimum fee per byte.

Returns

Integer - The current minimum fee per byte.

Example (getting the current minimum fee per byte)

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

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

Example (setting a new minimum fee per byte)

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

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

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

Returns list of peers known to the client.

Parameters

none

Returns

Peer[] - The list of peers.

Example

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

// Result
{
    "jsonrpc": "2.0",
    "result": [
        {
            "id": "b99034c552e9c0fd34eb95c1cdf17f5e",
            "address": "wss://seed1.nimiq-testnet.com:8080/b99034c552e9c0fd34eb95c1cdf17f5e",
            "addressState": 2,
            "connectionState": 5,
            "version": 2,
            "timeOffset": -188,
            "headHash": "59da8ba57c1f0ffd444201ca2d9f48cef7e661262781be7937bb6ef0bdbe0e4d",
            "latency": 532,
            "rx": 2122,
            "tx": 1265
        },
        {
            "id": "e37dca72802c972d45b37735e9595cf0",
            "address": "wss://seed4.nimiq-testnet.com:8080/e37dca72802c972d45b37735e9595cf0",
            "addressState": 4
        }
    ],
    "id": 1
}

peerState

Returns the state of the peer.

Parameters

String - The address of the peer

Returns

Peer - The current state of the peer.

Example

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"peerState","params":["wss://seed1.nimiq-testnet.com:8080/b99034c552e9c0fd34eb95c1cdf17f5e"],"id":1}'

// Result
{
    "jsonrpc": "2.0",
    "result": {
        "id": "b99034c552e9c0fd34eb95c1cdf17f5e",
        "address": "wss://seed1.nimiq-testnet.com:8080/b99034c552e9c0fd34eb95c1cdf17f5e",
        "addressState": 2,
        "connectionState": 5,
        "version": 2,
        "timeOffset": 186,
        "headHash": "910a78e761034e0655bf01b13336793c809f598194a1b841269600ef8b84fe18",
        "latency": 550,
        "rx": 3440,
        "tx": 2696
    },
    "id": 1
}

pool

Returns or sets the mining pool.

When no parameter is given, it returns the current mining pool. When a value is given as parameter, it sets the mining pool to that value.

Parameters

String or Boolean (optional) - The mining pool connection string (url:port) or boolean to enable/disable pool mining.

Returns

String or null - The mining pool connection string, or null if not enabled.

Example (getting the current mining pool)

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

// Result
{
    "jsonrpc": "2.0",
    "result": "test-pool.nimiq.watch:8443",
    "id": 1
}

Example (setting a new mining pool)

// Request
curl -X POST --data '{"jsonrpc":"2.0","method":"pool","params":["us.sushipool.com:443"],"id":1}'

// Result
{
    "jsonrpc": "2.0",
    "result": "us.sushipool.com:443",
    "id": 1
}

poolConfirmedBalance

Returns the confirmed mining pool balance.

Parameters

none

Returns

Integer - The confirmed mining pool balance (in smallest unit).

Example

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

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

poolConnectionState

Returns the connection state to mining pool.

Parameters

none

Returns

Integer - The mining pool connection state (CONNECTED: 0, CONNECTING: 1, CLOSED: 2).

Example

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

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

sendRawTransaction

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

Parameters

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

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

submitBlock

Submits a block to the node. When the block is valid, the node will forward it to other nodes in the network.

Parameters

String - Hex-encoded full block (including header, interlink and body). When submitting work from getWork, remember to include the suffix.

Returns

nothing

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
}