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 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: String - 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 merkel root.
  • accountHash: 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.
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.
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.

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

(TODO)

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

Returns details for the account of given address.

Parameters
  1. Address - Address to check for balance.
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":"getBalance","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
  1. 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

(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