The MOTIV API

De MOTIV Wiki

1 Description

The MOTIV API allows interaction with MOTIV nodes using HTTP requests to port 37876. Most HTTP requests can use either the GET or POST methods, but some API calls accept only the POST method for security reasons. Responses are returned as JSON objects.

Each API call is documented below, with definitions given for HTTP request parameters and JSON response fields, followed by an example:

The JSON response fields are each followed by one of S for string, A for array, O for object, N for number or B for boolean.

In the examples, the MOTIV node is represented as localhost and requests and responses are formatted for easy reading; line breaks and spaces are not actually used except in some parameter values. All requests are in URL format which implies
the HTTP GET method. When GET is allowed, the URL can be entered into a browser URL field but proper URL encoding is usually required (e.g., spaces in a parameter value must be replaced by + or %20). Otherwise, the URL should
be used as a guide to preparing an HTTP POST request using cURL, for example.

3 General Notes

3.1 Genesis Block

Many API requests make reference to the genesis block. FYI, the genesis block's ID is 2680262203532249785. Sending
messages, selling aliases, and leasing balances to the Genesis account are no longer allowed since the Monetary System block.

3.2 Flexible Account IDs

All API requests that require an account ID accept either an account number or the corresponding Reed-Solomon address.

3.3 Quantity Units MOTIV, NQT and QNT

The MOTIV system has a currency MOTIV used to quantify value in the system. Like all currencies, MOTIV circulates in the system, moving from one user to another by payments and purchases. Also, a small fee is required for every transaction, including
those in which no MOTIV is transfered, such as simple messages. This fee goes to the owner of the node that forges (generates) the new block containing the transaction that is accepted onto the blockchain.

One billion MOTIV were created in the Genesis Block, and no new MOTIV will ever be created. As of block 134,000 MOTIV became divisible to eight decimal places. Yet internally, the currency
is still stored in integer form in units of NQT or MOTIVQuant, where 1 MOTIV = 108 NQT. All parameters and fields in the API involving a quantity of MOTIV are denominated in units of NQT, for example feeNQT. The only exception is
the field effectiveBalanceNXT, used in forging calculations.

The MOTIV system can be thought of as an asset owned by all who posses MOTIV. In this sense, MOTIV quantifies ownership of or stake in the system. Stakeholders are entitled to forge blocks and collect transaction fees in proportion to the amount of
MOTIV they possess.

Other assets can be created within MOTIV using Issue Asset. The issuer must specify the number of decimal places to use in quantifying the asset, and the amount of the asset to create
in generic units of QNT or Quant, distinct from NQT. Quantities of assets are stored internally as integers in units of QNT, and assets are priced in NQT per QNT.

For example, the mgwBTC (multi-gateway Bitcoin) asset is divisible to eight decimal places, like the original bitcoin (BTC) it is a proxy for. Therefore a QNT of mgwBTC is equivalent to a Satoshi (10-8 BTC). To place an order to sell
25,000,000 QNT of the mgwBTC asset at a price of 20,000 NQT per QNT, use the API Call Place Order with requestType=placeAskOrder, quantityQNT=25000000 and priceNQT=20000.
If the entire quantity is sold on the Asset Exchange, the seller will receive 500,000,000,000 NQT (quantityQNT * priceNQT) from the buyer(s). This trade corresponds to selling 0.25 mgwBTC for 5,000 MOTIV, which is how the trade appears
in the NRS client. In this case, the price of 20,000 in NQT per QNT is also the price in MOTIV per mgwBTC, since both mgwBTC and MOTIV are divisible to eight decimal places.

Currencies in the MOTIV Monetary System are a special kind of asset with properties and exchange methods suitable for currencies. With respect to quantities, exchange
rates and decimal places, the Monetary System API calls use MOTIV, NQT and QNT in exactly the same way as assets.

3.4 Creating Unsigned Transactions

All API requests that create a new transaction will accept either a secretPhrase or a publicKey parameter:

If secretPhrase is supplied, a transaction is created, signed at the server, and broadcast by the server as usual.

If only a publicKey parameter is supplied as a 64-digit (32-byte) hex string, the transaction will be prepared by the server and returned in the JSON response as transactionJSON without a signature. This JSON object along with
secretPhrase can then be supplied to Sign Transaction as unsignedTransactionJSON and the resulting signed transactionJSON can then be supplied to
Broadcast Transaction. This sequence allows for offline signing of transactions so that secretPhrase never needs to be exposed.

unsignedTransactionBytes may be used instead of unsigned transactionJSON when there is no encrypted message. Messages to be encrypted require the secretPhrase for encryption and so cannot be included in unsignedTransactionBytes.

3.5 Escrow Operations

All API requests that create a new transaction will accept an optional referencedTransactionFullHash parameter which creates a chained transaction, meaning that the new transaction cannot be confirmed unless the referenced transaction is
also confirmed. This feature allows a simple way of transaction escrow:

Alice prepares and signs a transaction A, but doesn't broadcast it by setting the broadcast parameter to false. She sends to Bob the unsignedTransactionBytes, the fullHash of the transaction, and the signatureHash.
All of those are included in the JSON returned by the API request. (Warning: make sure not to send the signed transactionBytes, or the signature itself, as then Bob can just broadcast transaction A himself).

Bob prepares, signs and broadcasts transaction B, setting the referencedTransactionFullHash parameter to the fullHash of A provided by Alice. He can verify that this hash indeed belongs to the transaction he expects from Alice,
by using Calculate Full Hash, which takes unsignedTransactionBytes and signatureHash (both of which Alice has also sent to Bob). He can also use Parse Transaction to decode the unsigned bytes and inspect all transaction fields.

Transaction B is accepted in the unconfirmed transaction pool, but as long as A is still missing, B will not be confirmed, i.e. will not be included in the blockchain. If A is never submitted, B will eventually expire -- so Bob should make sure
to set a long enough deadline, such as the maximum of 32767 minutes.

Once in the unconfirmed transactions pool, Bob has no way of recalling B back. So now Alice can safely submit her transaction A, by just broadcasting the signedTransactionBytes she got in the first step. Transaction A will get included
in the blockchain first, and in the next block Bob's transaction B will also be included.

Note that while the above scheme is good enough for a simple escrow, the blockchain does not enforce that if A is included, B will also be included. It may happen due to forks and blockchain reorganization, that B never gets a chance to be included
and expires unconfirmed, while A still remains in the blockchain. However, it is not practically possible for Bob to intentionally cause such chain of events and to prevent B from being confirmed.

3.6 Prunable Data

Prunable data can be removed from the blockchain without affecting the integrity of the blockchain. When a transaction containing prunable data is created, only the 32-byte sha256 hash of the prunable data is included in the transactionBytes,
not the prunable data itself. The non-prunable signed transactionBytes are used to verify the signature and to generate the transaction's fullHash and ID; when the prunable part of the transaction is removed at a later time, none
of these operations are affected.

Prunable data has a predetermined minimum lifetime of two weeks (24 hours on the Testnet) from the timestamp of the transaction. Transactions and blocks received from peer nodes are not accepted if prunable
data is missing before this time has elapsed. After this time has elapsed, prunable data is no longer included with transactions and blocks transmitted to peer nodes, and is no longer included in the transaction JSON returned by general-purpose
API calls such as Get Transaction; the only way to retrieve it, if still available, is through special-purpose API calls such as Get Prunable Message.

Expired prunable data remains stored in the blockchain until removed at the same time derived tables are trimmed, which occurs automatically every 1000 blocks by default. Use Trim Derived Tables to remove expired prunable data immediately.

Prunable data can be preserved on a node beyond the predetermined minimum lifetime by setting the nxt.maxPrunableLifetime property to a larger value than two weeks or to -1 to preserve it indefinitely. To force the node to include
such preserved prunable data when transactions and blocks are transmitted to peer nodes, set the nxt.includeExpiredPrunables property to true, thus making it an archival node.

Currently, there are two varieties of prunable data in the MOTIV system: prunable Arbitrary Messages and Tagged Data.
Both varities have a maximum prunable data length of 42 kilobytes.

3.7 Properties Files

The behavior of some API calls is affected by property settings loaded from files in the nxt/conf directory during MOTIV server intialization. This directory contains the nxt-default.properties and logging-default.properties files, both of which contain default property settings along with documentation. A few of the property settings can be obtained while the server is running through the Get Blockchain Status and Get State calls.

It is recommended not to modify default properties files because they can be overwritten during software updates. Instead, properties in the default files can be overridden by including them in optional nxt.properties and logging.properties files in the same directory. For example, a nxt.properties file can be created with the contents:

nxt.isTestnet=true

This causes the MOTIV server to connect to the Testnet instead of the Mainnet.

3.8 Admin Password

Some API functions take an adminPassword parameter, which must match the nxt.adminPassword property unless the nxt.disableAdminPassword property is set to true or the API server only listens on the localhost interface (when the nxt.apiServerHost
property is set to 127.0.0.1).

All Debug Operations require adminPassword since they require some kind of privilege. On some functions adminPassword is used so you can override maximum allowed value for lastIndex
parameter, which is set to 100 by default by the nxt.maxAPIRecords property. Giving you the option to retrieve more than objects per request.

3.9 Roaming and Light Client Modes

The remote node to use when in roaming and light client modes is selected randomly, but can be changed manually in the UI, or using the new set API Proxy Peer API, or forced
to a specific peer using the nxt.forceAPIProxyServerURL property.

Remote nodes can be blacklisted from the UI, or using the Blacklist API Proxy Peer API. This blacklisting is independent from peer blacklisting. The API proxy blacklisting
period can be set using the nxt.apiProxyBlacklistingPeriod property (default 1800000 milliseconds).

API requests that require sending the secret phrase, shared key, or admin password to the server, for features like forging, shuffling, or running a funding monitor, are disabled when in roaming or light client mode.

10 MOTIV for a Create Poll, including 20 options and total size of poll name plus poll description plus total option length not exceeding 320 chars. For each option above 20,
an additional fee of 1 MOTIV, and for each 32 chars after 320, an additional fee of 2 MOTIV.

[2, 21] MOTIV for a [basic, required-minimum-balance] Create Phasing Poll. 1 MOTIV will be added for each option (answer) beyond 20, and 1 MOTIV for each 32 bytes of hashedSecret
or linkedFullHash fields.

1 MOTIV for the first 32 bytes of a unencrypted non-prunable message, 1 MOTIV for each additional 32 bytes

2 MOTIV for the first 32 bytes of an encrypted non-prunable message, 1 MOTIV for each additional 32 bytes. The length is measured excluding the nonce and the 16 byte AES initialization
vector.

1 MOTIV for the first 1024 bytes of a prunable message, 0.1 MOTIV for each additional 1024 prunable bytes

1 MOTIV for Set Account Info, including 32 chars, with 2 MOTIV additional fee for each 32 chars

2 MOTIV for DGS Listing, including 32 chars of name plust description. With 2 MOTIV additional fee for each 32 chars.

5.12 Get Account Transaction Ids

Get the transaction IDs associated with an account in reverse block timestamp order. This call only returns non-phased transactions as of Version 1.5.7e and is deprecated, to be removed in version 1.6. Use Get Blockchain Transactions instead.

Request:

requestType is getAccountTransactionIds

account is the account ID

timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)

type is the type of transactions to retrieve (optional)

subtype is the subtype of transactions to retrieve (optional)

firstIndex is a zero-based index to the first transaction ID to retrieve (optional)

lastIndex is a zero-based index to the last transaction ID to retrieve (optional)

numberOfConfirmations is the required number of confirmations per transaction (optional)

withMessage is true to retrieve only only transactions having a message attachment, either non-encrypted or decryptable by the account (optional)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

5.13 Get Account Transactions

Get the transactions associated with an account in reverse block timestamp order. This call only returns non-phased transactions as of Version 1.5.7e and is depricated, to be removed in version 1.6. Use Get Blockchain Transactions instead.

Request:

requestType is getAccountTransactions

account is the account ID

timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)

type is the type of transactions to retrieve (optional)

subtype is the subtype of transactions to retrieve (optional)

firstIndex is a zero-based index to the first transaction to retrieve (optional)

lastIndex is a zero-based index to the last transaction to retrieve (optional)

numberOfConfirmations is the required number of confirmations per transaction (optional)

withMessage is true to retrieve only only transactions having a message attachment, either non-encrypted or decryptable by the account (optional)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

5.16 Get Guaranteed Balance

Get the balance of an account that is confirmed at least a specified number of times.

Request:

requestType is getGuaranteedBalance

account is an account ID

numberOfConfirmations is the minimum number of confirmations for a transaction to be included in the guaranteed balance (optional, if omitted or zero then minimally confirmed transactions are included)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

guaranteedBalanceNQT (S) is the balance (in NQT) of the account with at least numberOfConfirmations confirmations

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

messagePatternRegex is a regular expression pattern following the java.util.regex.Pattern specification; incoming transactions are only accepted if they contain a plain text message which matches this pattern (disabled indefinitely due
to a security issue)

messagePatternFlags is a bitmask of java.util.regex.Pattern flags, such as 2 (Pattern.CASE_INSENSITIVE)

5.23 Start Funding Monitor

Starts a funding monitor that will transfer MOTIV, ASSET or CURRENCY from the funding account to a recipient account when the amount held by the recipient account drops below the threshold. The transfer will not be done until the current block height
is greater than equal to the block height of the last transfer plus the interval. The funding account is identified by the secret phrase.

The recipient accounts are identified by the specified account property (see Set Account Property). Each account that has this property set by the funding account will be
monitored for changes. The property value can be omitted or it can consist of a JSON string containing one or more values in the format: {"amount":long,"threshold":long,"interval":integer} . POST only.

Request:

requestType is startFundingMonitor

property is the name of the account property

amount is the amount to fund the recipient account with (in NQT or QNT)

threshold is the threshold

interval is the the number of blocks to wait after before funding the recipient

secretPhrase is the secret phrase of the funding account

holdingType is a string representing the holding type (optional)

holding is the holding ID (optional)

Response:

started (B) is true if the monitor has been started

requestProcessingTime (N) is the API request processing time (in millisec)

5.24 Stop Funding Monitor

Stop a funding monitor. When the secret phrase is specified, a single monitor will be stopped. The monitor is identified by the secret phrase, holding and account property. The administrator password is not required and will be ignored.

When the administrator password is specified, a single monitor can be stopped by specifying the funding account, holding and account property. If no account is specified, all monitors will be stopped.

The holding type and account property name must be specified when the secret phrase or account is specified. Holding type codes are listed in getConstants. In addition, the holding identifier must be specified when the holding type is ASSET or
CURRENCY. POST only.

Request:

requestType is stopFundingMonitor

secretPhrase is the secret phrase of the funding account, used to stop a single monitor. (optional)

adminPassword is the admin password, used to stop a single monitor or all monitors (optional if secretPhrase is provided)

property is the name of the account property (optional)

holdingType is a string representing the holding type (optional)

holding is the holding ID (optional)

account is the account ID (optional)

Response:

stopped (N) is the number of the monitors that have been stopped

requestProcessingTime (N) is the API request processing time (in millisec)

8.2 Download Prunable Message

Downloadins a prunable message attachments directly as binary data. An optional secretPhrase parameter is supported, to allow decryption and downloading of the encrypted part of the message instead of the plain text part.

Request:

requestType is downloadPrunableMessage

transaction is the transaction ID

secretPhrase is the secret passphrase used to decrypt the encrypted part of the message (optional)

sharedKey is the shared key used to decrypt the message (optional) (see Get Shared Key)

retrieve is true to retrieve the message from achival node if needed (optional)

requireBlock is theblock ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

8.9 Send Message

recipientPublicKey is the public key of the receiving account (optional, enhances security of a new account)

message is either UTF-8 text or a string of hex digits (perhaps previously encoded using an arbitrary algorithm) to be converted into a bytecode with a maximum length of one kilobyte, 42 kilobytes if prunable (optional)

messageIsText is false if the message is a hex string, otherwise the message is text (optional)

messageIsPrunable is true if the message is prunable (optional)

messageToEncrypt is either UTF-8 text or a string of hex digits to be compressed (unless compressMessageToEncrypt is false) and converted into a bytecode with a maximum length of one kilobyte, 42 kilobytes if prunable, then
encrypted using AES (optional)

messageToEncryptIsText is false if the message to encrypt is a hex string, otherwise the message to encrypt is text (optional)

encryptedMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptedMessageData is provided)

encryptedMessageIsPrunable is true if the encrypted message is prunable (optional)

compressMessageToEncrypt is false to prevent gzip compression before encryption (optional)

messageToEncryptToSelf is either UTF-8 text or a string of hex digits to be compressed (unless compressMessageToEncryptToSelf is false) and converted into a one kilobyte maximum bytecode then encrypted with AES, then sent to the
sending account (optional)

messageToEncryptToSelfIsText is false if the message to self-encrypt is a hex string, otherwise the message to encrypt is text (optional)

encryptToSelfMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptToSelfMessageData is provided)

compressMessageToEncryptToSelf is false to prevent gzip compression before encryption (optional)

Note: Any combination (including none or all) of the three options plain message, messageToEncrypt, and messageToEncryptToSelf will be included in the transaction. However, one and only one prunable message may be included
in a single transaction if there is not already a message of the same type (either plain or encrypted).

Note: The encryptedMessageData-encryptedMessageNonce pair or the encryptToSelfMessageData-encryptToSelfMessageNonce pair can be the output of Encrypt To

8.10 Verify Prunable Message

Verify that a prunable message obtained from any source, when hashed, matches the hash of the original prunable message.

Request: Refer to Send Message for more details about the following request parameters.

requestType is verifyPrunableMessage

message is the plain message, if applicable (optional)

messageIsText is false if the provided plain message is a hex string (optional)

encryptedMessageData is the data part of the encrypted data-nonce pair (optional if message provided)

encryptedMessageNonce is the nonce part of the encrypted data-nonce pair (required if encryptedMessageData provided)

messageToEncryptIsText is false if the encrypted message was a hex string before encryption (optional)

compressMessageToEncrypt is false if the encrypted message was not compressed before encryption (optional)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: The hash is computed from the message itself plus its associated flag(s) isText and isCompressed (encrypted only); therefore the flag(s) must be provided for verification if different from the default(s). The original
encryptedMessageData-encryptedMessageNonce pair used to compute the original hash must be provided again to recompute the hash for verification of a prunable encrypted message.

Response:

version.PrunablePlainMessage or version.PrunableEncryptedMessage (N) is 1, the version number

verify (B) is true if the original hash matches the hash computed from the provided values

message (S) or encryptedMessage (O) is the prunable plain message or the prunable encrypted message object containing the fields:

data (S)

nonce (B)

isText (B)

isCompressed (B)

messageIsText (B) is true if the plain message is text, false if it is a hex string, if applicable

messageHash or encryptedMessageHash (S) is the hash

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millsec)

9.17 Get Asset Transfers

Get transfers associated with a given asset and/or account in reverse block height order (or in the expected order of execution for expected transfers).

Request:

requestType is either getAssetTransfers or getExpectedAssetTransfers, where expected transfers are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block

asset is the asset ID (optional)

account is the account ID (optional if asset provided)

timestamp is the earliest transfer (in seconds since the genesis block) to retrieve (optional, does not apply to expected transfers)

firstIndex is a zero-based index to the first transfer to retrieve (optional, does not apply to expected transfers)

lastIndex is a zero-based index to the last transfer to retrieve (optional, does not apply to expected transfers)

includeAssetInfo is true if the decimals and name fields are to be included (optional, does not apply to expected transfers)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

transfers (A) is an array of transfer objects with the following fields for each transfer:

quantityQNT (S) is the quantity (in QNT) of the asset traded

senderRS (S) is the Reed-Solomon address of the sender

assetTransfer (S) is the transaction ID of the asset transfer

sender (S) is the account number of the sender

recipientRS (S) is the Reed-Solomon address of the recipient

decimals (N) is the number of decimal places used by the asset (if includeAssetInfo is true)

recipient (S) is the account number of the recipient

name (S) is the name of the asset (if includeAssetInfo is true)

asset (S) is the asset ID

height (N) is the height of the transfer block

timestamp (N) is the timestamp (in seconds since the genesis block) of the transfer block, does not apply to an expected transfer

phased (B) is true if the transaction is phased, false otherwise, applies only to an expected transfer

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

9.22.1 Get Ask Order Ids

9.22.2 Get Bid Order Ids

9.23 Get Orders

Get bid/ask orders given an asset ID, in order of decreasing bid price or increasing ask price (if sortByPrice is true for expected orders, otherwise in the expected order of execution).

Request:

requestType is one of getBidOrders, getAskOrders, getExpectedBidOrders or getExpectedAskOrders, where expected orders are from the unconfirmed transactions pool or are phased transactions scheduled to finish
in the next block

asset is the asset ID

sortByPrice is true to sort by price (optional, applies only to expected orders, which are returned in expected order of execution by default)

showExpectedCancellations is true to include orders that are expected to be cancelled in the next block, based on the content of the unconfirmed transactions pool and the phased transactions expected to finish in the next block
(optional, does not apply to expected orders)

firstIndex is a zero-based index to the first order to retrieve (optional, does not apply to expected orders)

lastIndex is a zero-based index to the last order to retrieve (optional, does not apply to expected orders)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

bidOrders or askOrders (A) is an array of order objects (refer to Get Order for details) with the following additional field only for an expected order:

phased (B) is true if the order is phased, false otherwise

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

Note: The unencrypted message parameter is used for public feedback, but in addition or instead, an encrypted message can be used for private feedback to the seller and/or an encrypted message can be sent to self (buyer) although
the current NRS client does not recognize non-public feedback messages.

12 Forging Operations

12.1 Start / Stop / Get Forging

Start or stop forging with an account, or check to see if an account is forging. POST only.

Request:

requestType is either startForging, stopForging or getForging

secretPhrase is the secret passphrase of the account (optional for stopForging and getForging if password protected like the Debug Operations)

Response:

deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block (startForging and getForging only)

hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block (startForging and getForging only)

remaining (N) is the deadline less the elapsed time since the last block (getForging only)

foundAndStopped (B) is true if forging was stopped, false if forging was already stopped (stopForging only)

account (S) is the account number (getForging only)

accountRS (S) is the Reed-Solomon address of the account (getForging only)

requestProcessingTime (N) is the API request processing time (in millisec)

Note: A getForging request returns errorCode 5 if the account is not forging. If the account has a zero effectiveBalance, forging can be started but deadline, remainingTime and hitTime will be set
to zero.

12.3 Get Next Block Generators

Returns the next block generators ordered by hit time. The list of currently active forgers is first initialized using the block generators with at least 2 blocks generated within the previous 10,000 blocks, excluding accounts without a public
key. The list is updated as new blocks are processed. The results are not 100% correct since previously active generators may no longer be running and new generators won't be known until they generate a block.

Request:

requestType is getNextBlockGenerators

limit (N) is the number of next block generators to display.

Response:

activeCount (N) is the number of active forging accounts

lastBlock (S) is the last block ID on the blockchain

generators (A) is an array containing the number of next block generators requested

effectiveBalanceNXT (N) is the balance (in MOTIV) of the account available for forging: the unleased guaranteedBalance of this account plus the leased guaranteedBalance of all lessors to this account

accountRS (S) is the Reed-Solomon address of the account

deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block

account (S) is the account number

hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block

requestProcessingTime (N) is the API request processing time (in millisec)

timestamp (N) is the timestamp (in seconds since the genesis block) when the request was executed

13.2.1 Generate Hallmark

14 Monetary System Operations

General Monetary System documentation is available here. Documentation on the MintWorker tool for currency minting
is available here.

14.1 Can Delete Currency

Determine if a currency can be deleted.

Request:

requestType is canDeleteCurrency

account is the account ID

currency is the currency ID

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

canDelete (B) is true if the currency can be deleted, false otherwise

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

Note: a currency can be deleted only when all units of the currency are held by account. A reservable currency that has not yet been issued can be deleted by the issuer. A mintable currency that has not completed minting cannot be
deleted by a non-issuer.

Note: An exchange request is immediately executed once accepted onto the blockchain based only on currently available offers (refer to Publish Exchange Offer). The
request then expires, regardless of the amount of currency exchanged; the request may be completely filled, partially filled, or expire without any exchange if no matching offers are found.

amountPerUnitNQT is the additional amount (in NQT per QNT of reserveSupply) to reserve (refer to Issue Currency)

Note: An additional amountPerUnitNQT * reserveSupply NQT (beyond what has previously been reserved) will be locked until the issuanceHeight is reached. Upon issuance, if the currency is claimable the NQT will remain
locked until claimed; otherwise the NQT will transfer to the issuing account. Also upon issuance, a portion of the reserveSupply QNT will be transfered to each reserving account in proportion to the NQT that was contributed.

14.9 Get Account Exchange Requests

Get the exchange requests associated with a given account and/or currency in reverse chronological order (or in expected order of execution for expected requests).

Request:

requestType is either getAccountExchangeRequests or getExpectedExchangeRequests, where expected requests are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block

account is the account ID (optional for expected requests)

currency is the currency ID (optional for expected requests if account provided)

includeCurrencyInfo is true to include the response fields code, decimals, name, issuanceHeight, type, timestamp, issuerAccountRS and issuerAccount (optional, applies only
to expected requests)

firstIndex is a zero-based index to the first request to retrieve (optional, does not apply to expected requests)

lastIndex is a zero-based index to the last request to retrieve (optional, does not apply to expected requests)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

exchangeRequests (A) is an array of requests with the following fields for each request:

code (S) is a currency code

subtype (N) is 5 for buy and 6 for sell

decimals (N) is the number of decimal places

name (S) is the currency name

units (S) is the number of currency units to buy or sell (in QNT)

issuanceHeight (N) is the blockchain height of issuance for a reservable currency, zero otherwise

timestamp (N) is the timestamp (in seconds since the genesis block) of the block when the request was executed

rateNQT (S) is the exchange rate (in NQT per QNT)

issuerAccountRS (S) is the Reed-Solomon address of the issuer account

issuerAccount (S) is the issuer account ID

phased (B) is true if the transaction is phased (applies only to expected requests)

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

Notes: Even expired, unfilled requests will be retrieved. As of Nxt Software Version 1.5.13 phased exchange requests that have not yet finished,
or have not been approved, are now excluded if requestType is getAccountExchangeRequests.

14.13.1 Get Available To Sell

14.14 Get Buy / Sell Offers

Get currency buy or sell offers given a currency ID and/or an account ID in order of rate (if sortByRate is true for expected offers, otherwise in the expected order of execution).

Request:

requestType is one of getBuyOffers, getSellOffers, getExpectedBuyOffers or getExpectedSellOffers, where expected offers are from the unconfirmed transactions pool or are phased transactions scheduled to finish
in the next block

currency is the currency ID (optional)

account is the account ID (optional if currency provided)

availableOnly is true to include only offers with non-zero supply and limit, but is ignored when both currency and account are given (optional, does not apply to expected offers)

sortByRate is true to sort by rate (optional, applies only to expected offers, which are returned in expected order of execution by default)

firstIndex is a zero-based index to the first offer to retrieve (optional, does not apply to expected offers)

lastIndex is a zero-based index to the last offer to retrieve (optional, does not apply to expected offers)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

offers (A) is an array of buy or sell offer objects (refer to Get Offer for details) with the following additional field only for an expected offer:

phased (B) is true if the offer is phased, false otherwise

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

14.22 Get Currency Transfers

Get currency transfers given a currency ID and/or an account ID in reverse block height order (or in expected order of execution for expected transfers).

Request:

requestType is either getCurrencyTransfers or getExpectedCurrencyTransfers, where expected transfers are from the unconfirmed transactions pool or are phased transactions scheduled to finish in the next block

currency is the currency ID (optional)

account is the account ID (optional if currency provided)

timestamp is the earliest transfer (in seconds since the genesis block) to retrieve (optional, does not apply to expected transfers)

firstIndex is a zero-based index to the first transfer to retrieve (optional, does not apply to expected transfers)

lastIndex is a zero-based index to the last transfer to retrieve (optional, does not apply to expected transfers)

includeCurrencyInfo is true to include some currency fields (optional, does not apply to expected transfers)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

transfers (A) is an array of transfer objects with the following fields for each transfer:

code (S) is the currency code

units (S) is the amount (in QNT) of the transfer

issuanceHeight (N) is the blockchain height of the currency issuance for a reservable currency

type (N) is the currency type bitmask (refer to Get Currency for details)

issuerAccountRS (S) is the Reed-Solomon address of the issuer account

transfer (S) is the transfer ID

senderRS (S) is the Reed-Solomon address of the sender account

sender (S) is the account number of the sender account

recipientRS (S) is the Reed-Solomon address of the recipient account

decimals (N) is the number of decimal places used by the currency

recipient (S) is the account number of the recipient account

name (S) is the currency name

currency (S) is the currency ID

issuerAccount (S) is the issuer account ID

height (N) is the blockchain height of the transfer

timestamp (N) is the timestamp (in seconds since the genesis block) of the transfer block, does not apply to an expected transfer

phased (B) is true if the transaction is phased, false otherwise, applies only to an expected transfer

issuerAccountRS (S) is the Reed-Solomon address of the issuer account

issuerAccount (S) is the issuer account ID

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

difficulty (S) is the current difficulty, an estimate of the number of hashes needed to meet the target

targetBytes (S) is the 32-byte target (little endian), which must equal or exceed the computed hash of the nonce

currency (S) is the currency ID

counter (N) is the counter associated with the minting account, the value previously submitted to Currency Mint

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

Note: If a nonce is found such that its hash is less than the target, it can be submitted to the blockchain along with counter + 1 using Currency Mint, which
results in units NQT being credited to the minting account. difficulty is inversely related to the target, and so increases exponentially as maxSupply is approached because the target is defined as (2exp-1)/units,
where exp decreases linearly from 256-minDifficulty to 256-maxDifficulty. (Refer to Issue Currency for maxSupply, minDifficulty and maxDifficulty.)

Notes: Each time currency is bought in response to an exchange request to sell currency (refer to Currency Sell), totalBuyLimit is reduced and the supply of
currency offered to sell increases by the amount bought. When totalBuyLimit becomes zero, the buy offer is withdrawn. These same notes apply if buy and sell are interchanged. Only the most recent offer associated with an
account is valid, even if an earlier offer by that account has not yet expired or reached its limits.

16.2 Create Phasing Poll

Create a phased transaction with conditional deferred execution based on the result of a vote, on a list of linked transactions or on the revelation of a secret; or simply with unconditional deferred execution. POST only.

requestType is any type from the Create Transaction list which is phasing-safe, indicated with italics such as Send Money

phased is true to create a phased transaction (optional but required for all of the following parameters, which are all optional for unphased transactions)

phasingFinishHeight is the block height at which the poll will finish; the transaction will be executed at this block height only if all conditions (if any) have been met, otherwise the transaction will never be executed

phasingVotingModel is an integer code for the method of approval:

-1 for None

0 for Vote By Account

1 for Vote By Account Balance

2 for Vote By Asset Balance

3 for Vote By Currency Balance

4 for By Linked Transactions

5 for By Secret

phasingQuorum is the number of "votes" needed for transaction approval (required if phasingVotingModel >= 0, default 0):

phasingHolding is the asset or currency ID (required if phasingMinBalanceModel = 2 or 3)

phasingWhitelisted is the account ID of an account allowed to vote for the transaction; once used, only whitelisted accounts are allowed to vote (optional, may be used up to ten times per API request)

phasingLinkedFullHash is the full hash of a transaction that must be in the blockchain at the phasingFinishHeight; transactions already in the blockchain before the acceptance of the phased transaction can also be linked, as long
as they are not more than 60 days old, or themselves phased transactions (required only for voting model 4, may be used up to ten times per API request)

phasingHashedSecret is the hash of a secret phrase (up to 100 bytes long) required for approval (required only for voting model 5)

phasingHashedSecretAlgorithm is the hash function used: 2 for SHA256, 6 for RIPEMD160 and 62 for SHA256 followed by RIPEMD160, according to Get Constants (required for a phasingHashedSecret)

Note: When a balance affects the poll result, the result depends only on the balance (including pending outgoing phased transfers) computed just prior to the finish height.

16.7 Get Linked Phased Transactions

Gets the phased transactions with by-transaction voting model for a given linkedFullHash, regardless of their phasing status (pending, approved or rejected). Since the corresponding table is trimmed after finish height however, the result will
not include those transactions that finished before the last trimming height.

Request:

requestType is getLinkedPhasedTransactions

linkedFullHash is the full hash of the transaction transaction

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

transactions (A) is an array of transactions (refer to Get Transaction for details)

requestProcessingTime (N) is the API request processing time (in millisec)

transactionFullHash (S) is the full hash of the phasing poll transaction

finished (B) is true if the poll is finished, false otherwise (omitted if finished is false)

result (S) is the sum of the result of each account that approved (voted for) the transaction; an account's result is 1 if the voting model is 0, 4 or 5; it is the NQT, asset QNT or currency QNT
balance of the account if the voting model is 1, 2 or 3 respectively; however, the result is 0 if minBalance is not met

approved (B) is true if the poll was approved, false otherwise

minBalance (S) is the required minimum balance of voting accounts to be eligible to vote

17 Server Information Operations

17.1 Event Register

event is one of multiple server events from the following list of event names: (optional, default is all possible events)

Block.BLOCK_GENERATED

Block.BLOCK_POPPED

Block.BLOCK_PUSHED

Peer.ADD_INBOUND

Peer.ADDED_ACTIVE_PEER

Peer.BLACKLIST

Peer.CHANGED_ACTIVE_PEER

Peer.DEACTIVATE

Peer.NEW_PEER

Peer.REMOVE

Peer.REMOVE_INBOUND

Peer.UNBLACKLIST

Transaction.ADDED_CONFIRMED_TRANSACTIONS

Transaction.ADDED_UNCONFIRMED_TRANSACTIONS

Transaction.REJECT_PHASED_TRANSACTION

Transaction.RELEASE_PHASED_TRANSACTION

Transaction.REMOVE_UNCONFIRMED_TRANSACTIONS

event is one of multiple server events (optional)

⋮

add is true to add events to an existing listener (optional, omit if remove is true)

remove is true to remove events from an existing listener (optional, omit if add is true)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: To create a new event listener, omit both add and remove. To remove an existing event listener, set remove to true and omit event; all registered events will be removed, any outstanding Event Wait will be completed and the listener will be deactivated.

Note: An event listener is automatically deactivated whenever all registered events are removed or if Event Wait is not called frequently enough, according to the nxt.apiEventTimeout property. The timeout is not precise; the removal process runs every nxt.apiEventTimeout / 2 seconds, so that many extra seconds may elapse before removal; the first Event Wait call should be made immediately after registration to avoid deactivation.

Note: Each API user (with a unique address) can create only one event listener. When a new one is created, it will replace an existing one. The maximum number of unique users is controlled by the nxt.maxEventUsers property.

Response:

registered is true if the operation completed successfully

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

17.2 Event Wait

timeout is the amount of time (in seconds) to wait for an event before the call returns (optional, default and maximum is the nxt.apiEventTimeout property)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Notes: The call returns immediately if one or more events have occurred since the last call; multiple events are all returned together. If a new call is made before the last one returns, the timeout timer resets to the new value.
Event registration expires if wait calls are not made frequently enough, according to the nxt.apiEventTimeout property.

Response:

events (A) is an array of event objects each of which has the following fields:

name (S) is the name of the event (refer to Event Register for the list of event names)

ids (A) is an array of identifiers, depending on the type of event:

block string identifier (S) for a block event

peer network address (S) for a peer event

transaction string identifier (S) for a transaction event

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

17.3 Get Blockchain Status

numberOfBlocks (N) is the number of blocks in the blockchain (height + 1)

isTestnet (B) is true if the node is connected to testnet, false otherwise

includeExpiredPrunable (B) is the value of the nxt.includeExpiredPrunable property

requestProcessingTime (N) is the API request processing time (in millisec)

version (S) is the application version

maxRollback (N) is the value of the nxt.maxRollback property

lastBlock (S) is the last block ID on the blockchain

application (S) is application name, typically NRS

isScanning (B) is true if the blockchain is being scanned by the application, false otherwise

isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks
from a peer does not result in any new blocks

cumulativeDifficulty (S) is the cumulative difficulty

lastBlockchainFeederHeight (N) is the height of the last blockchain of greatest cumulative difficulty obtained from a peer

maxPrunableLifetime (N) is the maximum prunable lifetime (in seconds)

time (N) is the current timestamp (in seconds since the genesis block)

lastBlockchainFeeder (S) is the address or announced address of the peer providing the last blockchain of greatest cumulative difficulty

blockchainState (S) Current state of this node's blockchain (UP_TO_DATE or DOWNLOADING)

17.6 Get State

includeCounts is true if the fields beginning with numberOf... are to be included (optional); password protected like the Debug Operations if true.

Response:

numberOfPeers (N) is the number of known peers on the network

numberOfGoods (N) is the number of DGS goods in the blockchain

numberOfPolls (N) is the number of polls in the blockchain

numberOfUnlockedAccounts (N) is the number of unlocked accounts on this node

numberOfTransfers (N) is the number of AE transfers in the blockchain

includeExpiredPrunable (B) is the value of the nxt.includeExpiredPrunable property

numberOfOrders (N) is the number of AE orders in the blockchain

numberOfTransactions (N) is the number of transactions in the blockchain

maxMemory (N) is the maximum amount of memory the node may use (in Bytes)

maxRollback (N) is the value of the nxt.maxRollback property

numberOfOffers (N) is the number of buy currency offers in the blockchain

isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks
from a peer does not result in any new blocks

isScanning (B) is true if this node is scanning the blockchain, false otherwise

cumulativeDifficulty (S) is the current cumulative forging difficulty

numberOfCurrencies (N) is the number of currencies in the blockchain

numberOfAssets (N) is the number of AE assets in the blockchain

numberOfPrunableMessages (N) is the number of prunable messages in the blockchain

freeMemory (N) is the amount of free memory on this node (in Bytes)

peerPort (N) is the port used for connecting to peers

numberOfVotes (N) is the number of votes in the blockchain

availableProcessors (N) is the number of processors on this node

numberOfTaggedData (N) is the number of tagged data in the blockchain

numberOfActiveAccountLeases (N) is the number of active account leases in the blockchain

numberOfAccountLeases (N) is the total number of account leases including scheduled leases (first scheduled lease only) in the blockchain

numberOfAccounts (N) is the number of accounts in the blockchain

numberOfDataTags (N) is the number of data tags in the blockchain

needsAdminPassword (B) is true if the nxt.disableAdminPassword property is false

currentMinRollbackHeight (N) is the current minimum rollback height

numberOfBlocks (N) is the number of blocks (height + 1) in the blockchain

isTestnet (B) is true if the node is connected to testnet, false otherwise

numberOfCurrencyTransfers (N) is the number of currency transfers in the blockchain

requestProcessingTime (N) is the API request processing time (in millisec)

numberOfPhasedTransactions (N) is the number of phased transactions in the blockchain

version (S) is the software version on this node

numberOfBidOrders (N) is the number of AE bid orders in the blockchain

lastBlock (S) is the last block address

totalMemory (N) is the amount of memory this node is using (in Bytes)

application (S) is the name of the software running on this node (typically NRS)

numberOfAliases (N) is the number of aliases in the blockchain

numberOfActivePeers (N) is the number of active peers on the network

lastBlockchainFeederHeight (N) is the height of the last blockchain feeder

maxPrunableLifetime (N) is the maximum prunable lifetime (in seconds)

numberOfExchanges (N) is the number of currency exchanges in the blockchain

numberOfTrades (N) is the number of AE trades in the blockchain

numberOfPurchases (N) is the number of DGS purchases in the blockchain

numberOfTags (N) is the number of DGS tags in the blockchain

time (N) is the current node time (in seconds since the genesis block)

numberOfAskOrders (N) is the number of AE ask orders in the blockchain

lastBlockchainFeeder (S) is the announced name of the feeder of the last blockchain

isOffline (B) is true if this node is connected to other peers, false otherwise

18 Shuffling Operations

Coin shuffling can be used to perform mixing of MOTIV, MS currencies (unless created as non-shuffleable), or AE assets. Any account can create a new shuffling, specifying the holding to be shuffled, the shuffle amount, number of participants required,
and registration deadline.

18.1 Get Account Shufflings

Retrieves info about shufflings for a specific account.

Request:

requestType is getAccountShufflings

account is the account ID

includeFinished is true to include completed shufflings (optional)

includeHoldingInfo is true to include holding info (optional)

firstIndex is a zero-based index to the first tagged data to retrieve (optional)

lastIndex is a zero-based index to the last tagged data to retrieve (optional)

adminPassword is a string with the admin password (optional)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)

shufflings (A) is an array containing the shuffling object (refer to Get Shuffling)

18.13 Start Shuffler

Starts a automated Shuffler. Once started, the Shuffler monitors the blockchain state for transactions relevant to the specified shuffle, and automatically submits the required transactions on behalf of the user, performing shuffle processing,
verification, or cancellation as needed.

Request:

requestType is startShuffler

secretPhrase is the secret phrase of the account entering the shuffling

shufflingFullHash the full hash of the shuffling

recipientSecretPhrase the secret phrase of the recipient account (optional if recipientPublicKey is present)

recipientPublicKey the public key of the recipient account (optional if recipientSecretPhrase is present)

Response

shuffling (S) is the shuffling ID

shufflingFullHash (S) is the full hash of the shuffling

account (S) is the account ID

accountRS (S) is the account Reed Solomong address

recipient (S) is the account ID of the recipient account

recipientRS (S) is the account Reed Solomon address of the recipient account

requestProcessingTime (N) is the API request processing time (in millisec)

19.2 Extend Tagged Data

file is the pathname of a data file to upload (optional if data provided)

filename

name

description

tags

type

channel

isText

Note: The data and metadata (filename, name, description, tags, type, channel and isText) parameters can be omitted if the tagged data has not yet expired; otherwise, the tagged data
can be restored to the blockchain only if these fields have exactly the same values as when the data was uploaded (refer to Upload Tagged Data).

Note: Anyone can submit an extension, not only the original uploader. Each extend transaction increases the expiration deadline by two weeks (24 hours on Testnet). Extending an existing tagged data from another account does not change the
original submitter account ID by which it is indexed and searchable.

Note: The maximum length of data plus all associated metadata is 42 kilobytes. The maximum length of description is 1000 bytes. The maximum length of the other metadata (name, tags, type, channel and filename) is 100 bytes each.

20.4 Generate Token

website is a web site URL for which authorization should be granted, or general text to be digitally signed

Note:website is typically a URL (with the leading http:// unnecessary) that an account owner signs with his secretPhrase (private key) to bind the account to the URL, but website can be any text that the owner wishes
to sign.

Response:

token (S) is a 160 character string representing the 100-byte token which consists of a 32-byte public key, a 4-byte timestamp, and a 64-byte signature

account (S) is the account number corresponding to secretPhrase

accountRS (S) is the Reed-Solomon address of the account

timestamp (N) is the time (in seconds since the genesis block) that the token was generated

valid (B) is true if token is valid, false otherwise

requestProcessingTime (N) is the API request processing time (in millisec)

Note: Since token contains the token generator's public key and signature, the website can be validated as authorized by the owner of the public key using Decode Token.

21 Transaction Operations

21.1 Broadcast Transaction

transactionJSON is the transaction object (optional if transactionBytes provided)

prunableAttachmentJSON is the attachment object embedded in transactionJSON containing a prunable message (required if transactionJSON not provided because transactionBytes never includes prunable data)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)

21.9 Send Transaction

It broadcasts a transaction to the network without validating it, without re-broadcasting it and without adding it locally as unconfirmed transaction. Specially intended for roaming or light clients to send transactions to remote peers. POST only.

Request:

requestType is sendTransaction

transactionBytes is the bytecode of a signed transaction (optional)

transactionJSON is the transaction object (optional if transactionBytes provided)

prunableAttachmentJSON is the attachment object embedded in transactionJSON containing a prunable message (required if transactionJSON not provided because transactionBytes never includes prunable data)

adminPassword is a string with the admin password (optional)

Response:

requestProcessingTime (N) is the API request processing time (in millisec)

21.10 Sign Transaction

Calculates the full hash, signature hash, and transaction ID of an unsigned transaction.

Request:

requestType is signTransaction

unsignedTransactionJSON is the transactionJSON field of the transaction, without a signature subfield

unsignedTransactionBytes is the unsignedTransactionBytes field of the transaction (optional, if unsignedTransactionJSON provided)

prunableAttachmentJSON is a prunable attachment JSON object, if applicable, because unsignedTransactionBytes never includes prunable data (optional if the transaction has already been broadcast and the prunable message can still
be retrieved from the database)

secretPhrase is the secret passphrase of the signing account

validate is false to skip validation of the transaction bytes being signed (useful on nodes where the full blockchain is not downloaded)

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Response:

signatureHash (S) is a SHA-256 hash of the transaction signature, used in escrow transactions

verify (B) is true the signature is verified, false if not

transactionJSON (O) is the signed transaction JSON object

transactionBytes (S) are the signed transaction bytes

fullHash (S) is the full hash of the signed transaction

prunableAttachmentJSON (O) is the prunable attachment JSON object, if applicable, because transactionBytes never includes prunable data

transaction (S) is the transaction ID, derived from the fullHash

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

22 Voting System Operations

22.1 Cast Vote

vote00 is an integer within the allowed range to vote for option (answer) 0 (optional if minNumberOfOptions met, default is -128)

vote01 is an integer within the allowed range to vote for option (answer) 1 (optional if minNumberOfOptions met, default is -128)

vote02 is an integer within the allowed range to vote for option (answer) 2 (optional if minNumberOfOptions met, default is -128)

⋮

Note: The allowed vote values are integers between minRangeValue and maxRangeValue, inclusive. This range, along with the minimum and maximum number of options that can and must be voted on are specified when the poll is created.
Refer to Create Poll.

Notes: Up to 100 options (answers) can be specified, but there is an extra fee for each option beyond 20. Unlike the API, the NRS client treats a vote of 0 as
a nonvote not contributing to the number answers (options) chosen. The NRS client uses checkboxes for selecting answers when minRangeValue = 0 and maxRangeValue = 1; otherwise sliding controls are used to select answers from the
allowed range.

Note: When a balance affects the poll result, the result depends only on the balance (including pending outgoing phased transfers) computed just prior to the finish height.

requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)

requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)

Note: The votingModel, holding, minBalance and minBalanceModel parameters are optional and default to the original values specified when the poll was created (refer to Create Poll). The original values can only be overridden while the votes are still stored in the database, until 1441 blocks after the poll is completed. If votingModel is specified, holding, minBalance and minBalanceModel or the defaults specified above apply, otherwise they are ignored.

Response:

poll (S) is the poll ID

votingModel (N) is the votingModel used to calculate results (refer to Note above)

minBalanceModel (N) is the minBalanceModel used to calculate results (refer to Note above)

minBalance (S) is the minBalance used to calculate results (refer to Note above)

holding (S) is the asset or currency ID if the voting model uses an asset or currency balance to determine weight, if applicable (refer to Note above)

decimals (N) is the number decimal places used by the asset or currency, if applicable

finished (B) is true if the poll is complete, false otherwise

options (A) is the array of options (answers) of the poll

results (A) is an array of result objects with the following fields for each result:

weight (S) is the sum of the weight of each account that voted for the corresponding option (answer); an account's weight is 1 if the voting model is 0, otherwise it is the NQT, asset QNT or currency QNT
balance of the account if the voting model is 1, 2 or 3 respectively; however, the weight is 0 if minBalance is not met

result (S) is the sum over each account that voted for the corresponding option (answer) of: the product of the account's weight and the rangeValue selected when the vote was cast.

lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)

requestProcessingTime (N) is the API request processing time (in millisec)

23.5 Hash

Calculates the hash of a secret for use in phased transactions with voting model 5 (Vote By Secret).

Request:

requestType is hash

hashAlgorithm is the hash function used: 2 for SHA256, 3 for SHA3, 5 for SCRYPT, 6 for RIPEMD160, 25 for Keccack25 and 62 for SHA256 followed by RIPEMD160, according to Get Constants

secret is a secret phrase in text form or hex string form

secretIsText is true if secret is text, false if it is a hex string (optional)

Note:secret is converted from a hex string to a byte array, which is what the hash algorithm expects, unless secretIsText is true, in which case secret is first converted from text to a UTF-8 hex string as by
Hex Convert.

Response:

hash (S) is the hash of the secret, in the form of a hex string

requestProcessingTime (N) is the API request processing time (in millisec)

24.10 Rebroadcast Unconfirmed Transactions

Rebroadcast transactions in the unconfirmed pool to peers, until received back or found in the blockchain. Rebroadcasting can be disabled by setting the nxt.enableTransactionRebroadcasting property to false. POST only.

Request:

requestType is RebroadcastUnconfirmedTransactions

Response:

done (B) is true if the operation completed successfully

requestProcessingTime (N) is the API request processing time (in millisec)

24.13 Scan

numBlocks is the number of blocks to scan at the top of the blockchain (optional)

height is the height above which blockchain is to be scanned (optional if numBlocks provided)

validate is true if signatures are to be re-verified and blocks and transactions re-validated (optional)

Note: The derived object tables are rolled back and rebuilt by rescanning the existing blockchain. A request to rescan more than 1440 blocks when table trimming is enabled will do a full rescan starting from height 0. Rescan status is saved
in the database, so that if a rescan is interrupted or fails it will resume on restart.

Response:

scanTime (N) is the scan time

done (B) is true if the operation completed successfully

requestProcessingTime (N) is the API request processing time (in millisec)