The PRIZM API

Go to table of contents

1 Description

The PRIZM API allows interaction with PRIZM nodes using HTTP requests to port 9976. 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 PRIZM 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.

All API calls can be viewed and tested at http://localhost:9976/test while the local server node is running. For specific API calls, use http://localhost:9976/test?requestType=specificRequestType.

2 Table Of Contents

3 General Notes

3.1 Genesis Block

Many API requests make reference to the genesis block. FYI, the genesis block's ID is 7024118705028086222.

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 PRIZM and NQT

The PRIZM system has a currency PRIZM used to quantify value in the system. Like all currencies, PRIZM 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 PRIZM 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.

Internally, the currency is still stored in integer form in units of NQT, where 1 PRIZM = 100 NQT. All parameters and fields in the API involving a quantity of PRIZM are denominated in units of NQT, for example feeNQT. The only exception is the field effectiveBalancePrizm, used in forging calculations.

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

3.4 Creating Unsigned Transactions

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

3.5 Escrow Operations

(disabled)

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 PRIZM.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 PRIZM.includeExpiredPrunables property to true, thus making it an archival node.

Currently, there is one variety of prunable data in the PRIZM system: prunable Arbitrary Messages. It has 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 prizm-dist/conf directory during PRIZM server intialization. This directory contains the prizm.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 prizm.properties and logging.properties files in the same directory. For example, a prizm.properties file can be created with the contents:

prizm.savePeers=true

3.8 Admin Password

Some API functions take an adminPassword parameter, which must match the PRIZM.adminPassword property unless the PRIZM.disableAdminPassword property is set to true or the API server only listens on the localhost interface (when the PRIZM.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 PRIZM.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 PRIZM.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 PRIZM.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.

4 Create Transaction

The following API calls create PRIZM transactions using HTTP POST requests. Follow the links for examples and HTTP POST request parameters specific to each call. Refer to the sections below for HTTP POST request parameters and JSON response fields common to all calls that create transactions.

4.1 Create Transaction Request

The following HTTP POST parameters are common to all API calls that create transactions:

Note: An optional arbitrary message can be appended to any transaction by adding message-related parameters as in Send Message.

4.2 Create Transaction Response

The following JSON response fields are common to all API calls that create transactions:

5 Account Operations

5.2 Get Account

Get account information given an account ID.

Request:

Response:

Example: Refer to Get Account example.

5.3 Get Account Block Count

Get the number of blocks forged by an account.

Request:

Response:

Example: Refer to Get Account Block Count example.

5.4 Get Account Block Ids

Get the block IDs of all blocks forged (generated) by an account in reverse block height order.

Request:

Response:

Example: Refer to Get Account Block Ids example.

5.5 Get Account Blocks

Get all blocks forged (generated) by an account in reverse block height order.

Request:

Response:

Example: Refer to Get Account Blocks example.

5.6 Get Account Id

Get an account ID given a secret passphrase or public key. POST only.

Request:

Response:

Example: Refer to Get Account Id example.

5.7 Get Account Ledger

Get multiple account ledger entries.

Request:

Response:

Example: Refer to Get Account Ledger example.

5.8 Get Account Ledger Entry

Get a specific account ledger entry.

Request:

Response:

Example: Refer to Get Account Ledger Entry example.

5.11 Get Account Public Key

Get the public key associated with an account ID.

Request:

Response:

Example: Refer to Get Account Public Key example.

5.12 Get Account Transaction Ids

(Removed. Use Get Blockchain Transactions instead.)

5.13 Get Account Transactions

(Removed. Use Get Blockchain Transactions instead.)

5.14 Get Balance

Get the balance of an account.

Request:

Response:

Example: Refer to Get Balance example.

5.15 Get Blockchain Transactions

Get the transactions associated with an account in reverse block timestamp order.


Request:

Note: Refer to Get Constants for definitions of types and subtypes

Response:

Example: Refer to Get Blockchain Transactions example.

5.16 Get Guaranteed Balance

Get the guaranteed balance of an account. This is the minimum balance the account had in the interval

(currentHeight - numberOfConfirmations, currentHeight]

Amounts in unconfirmed transactions are not deduced from the result (or included to the result).

Request:

Response:

Example: Refer to Get Guaranteed Balance example.

5.17 Get Unconfirmed Transaction Ids

Get a list of unconfirmed transaction IDs associated with an account.

Request:

Response:

Example: Refer to Get Unconfirmed Transaction Ids example.

5.18 Get Unconfirmed Transactions

Get a list of unconfirmed transactions associated with an account.

Request:

Response:

Example: Refer to Get Unconfirmed Transactions example.

5.19 Search Accounts

Get accounts having a name or description that match a given query in reverse relevance order.

Request:

Response:

Example: Refer to Search Accounts example.

5.20 Send Money

Send PRIZM to an account. POST only.

Request: Refer to Create Transaction Request for common parameters.

Response: Refer to Create Transaction Response.

Example: Refer to Send Money example.

5.21 Set Account Info

Set account information. POST only.

Request: Refer to Create Transaction Request for common parameters.

Response: Refer to Create Transaction Response.

Example: Refer to Set Account Info example.

8 Arbitrary Message System Operations

8.1 Decrypt From

Decrypt an AES-encrypted message.

Request:

Response:

Example: Refer to Decrypt From example.

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:

Response: The prunable data as a binary file.

Example: Refer to Download Prunable Message example.

8.3 Encrypt To

Encrypt a message using AES without sending it.

Request:

Response:

Example: Refer to Encrypt To example.

8.4 Get All Prunable Messages

Get all available prunable messages in reverse block timestamp order.

Request:

Response:

Example: Refer to Get All Prunable Messages example.

8.5 Get Prunable Message

Get the prunable message given a transaction ID, optionally decrypting it if encrypted and if a secretPhrase is provided, if it is still available.

Request:

Response:

Example: Refer to Get Prunable Message example.

8.6 Get Prunable Messages

Get all still-available prunable messages given an account id, optionally limiting to only those with another account as recipient or sender, in reverse chronological order.

Request:

Response:

Example: Refer to Get Prunable Messages example.

8.7 Get Shared Key

Get the one-time shared key used for encryption of messages.

Request:

Response:

Example: Refer to Get Shared Key example.

8.8 Read Message

Get a message given a transaction ID.

Request:

Response:

Example: Refer to Read Message example.

8.9 Send Message

Create an Arbitrary Message transaction. POST only.

Request: Refer to Create Transaction Request for common parameters.

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

Response: Refer to Create Transaction Response.

Example: Refer to Send Message example.

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.

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:

Example: Refer to Verify Prunable Message example.

10 Block Operations

10.1 Get Block

Get a block object given a block ID or block height.

Request:

Note: block overrides height which overrides timestamp.

Response:

Example: Refer to Get Block example.

10.2 Get Block Id

Get a block ID given a block height.

Request:

Response:

Example: Refer to Get Block Id example.

10.3 Get Blocks

Get blocks from the blockchain in reverse block height order.

Request:

Response:

Example: Refer to Get Blocks example.

10.4 Get EC Block

Get Economic Cluster block data.

Request:

Note: If timestamp is more than 15 seconds before the timestamp of the last block on the blockchain, errorCode 4 is returned.

Response:

Example: Refer to Get EC Block example.

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:

Response:

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.

Example: Refer to Start / Stop / Get Forging example.

12.1.1 Get Forging

Refer to Start / Stop / Get Forging.

12.1.2 Start Forging

Refer to Start / Stop / Get Forging.

12.1.3 Stop Forging

Refer to Start / Stop / Get Forging.

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:

Response:

Example: Refer to Get Next Block Generators example.

13 Hallmark Operations

13.1 Decode Hallmark

Decode a node hallmark.

Request:

Response:

Example: Refer to Decode Hallmark example.

13.2 Mark Host

Generates a node hallmark. POST only.

Request:

Note: Refer to Create Hallmark for details.

Response:

Note: Refer to Create Hallmark for instructions for applying the hallmark to a public node.

Example: Refer to Mark Host example.

13.2.1 Generate Hallmark

Refer to Mark Host.

15 Networking Operations

15.1 Add Peer

Add a peer to the list of known peers and attempt to connect to it. Password protected like the Debug Operations. POST only.

Request:

Response: refer to Get Peer

Example: Refer to Add Peer example.

15.2 Blacklist API Proxy Peer

Blacklist a remote node from the UI, so it won't be used when in roaming and light client modes. POST only.

Request:

Response:

Example: Refer to Blacklist API Proxy Peer example.

15.3 Blacklist Peer

Blacklist a peer for the default blacklisting period. Password protected like the Debug Operations. POST only.

Request:

Response:

Example: Refer to Blacklist Peer example.

15.4 Get Inbound Peers

Get all peers that have sent a request to this peer in the last 30 minutes.

Request:

Response:

Example: Refer to Get Inbound Peers example.

15.5 Get My Info

Get hostname and address of the requesting node.

Request:

Response:

Example: Refer to Get My Info example.

15.6 Get Peer

Get information about a given peer.

Request:

Response:

Example: Refer to Get Peer example.

15.7 Get Peers

Get a list of peer IP addresses.

Request:

Note: If neither active nor state is specified, all known peers are retrieved.

Response:

Example: Refer to Get Peers example.

15.8 Set API Proxy Peer

Set the remote node to use when in roaming and light client modes. POST only.

Request:

Response:

Example: Refer to Set API Proxy Peer example.

17 Server Information Operations

17.1 Event Register

Create, modify or remove an event listener which can report server events via Event Wait. POST only.

Request:

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 PRIZM.apiEventTimeout property. The timeout is not precise; the removal process runs every PRIZM.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 PRIZM.maxEventUsers property.

Response:

Example: Refer to Event Register example.

17.2 Event Wait

Wait for events registered with Event Register. POST only.

Request:

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 PRIZM.apiEventTimeout property.

Response:

Example: Refer to Event Wait example.

17.3 Get Blockchain Status

Get the blockchain status.

Request:

Response:

Example: Refer to Get Blockchain Status example.

17.4 Get Constants

Get all defined constants.

Request:

Response:

Example: Refer to Get Constants example.

17.5 Get Plugins

Get a list of all installed plugins on the server.

Request:

Response:

Example: Refer to Get Plugins example.

17.6 Get State

Get the state of the server node and network.

Request:

Response:

Example: Refer to Get State example.

17.7 Get Time

Get the current time.

Request:

Response:

Example: Refer to Get Time example.

20 Token Operations

20.1 Decode File Token

Validate a file token without requiring the transmission of a secret passphrase. POST only.

Request:

Response:

Note: Since token contains the token generator's public key and digital signature, file can be validated as signed by the owner of the public key, and the public key determines the account ID.

Example: Refer to Decode File Token example.

20.2 Decode Token

Validate a token without requiring the transmission of a secret passphrase.

Request:

Response:

Note: Since token contains the token generator's public key and digital signature, website can be validated as authorized by the owner of the public key, and the public key determines the account ID.

Example: Refer to Decode Token example.

20.3 Generate File Token

Generate a file token. POST only.

Request:

Response:

Note: Since token contains the token generator's public key and digital signature, the file can be validated as digitally signed by the owner of the public key using Decode File Token.

Example: Refer to Generate File Token example.

20.4 Generate Token

Generate a token. POST only.

Request:

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:

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.

Example: Refer to Generate Token example.

21 Transaction Operations

21.1 Broadcast Transaction

Broadcast a transaction to the network. POST only.

Request:

Response:

Example: Refer to Broadcast Transaction example.

21.2 Calculate Full Hash

Calculate the full hash of a transaction.

Request:

Response:

Example: Refer to Calculate Full Hash example.

21.3 Get Expected Transactions

Returns the non-phased unconfirmed transactions expected to be included in the next block (only).

Request:

Response:

Example: Refer to Get Expected Transactions example.

21.4 Get Referencing Transactions

Gets the transactions referencing a given transaction id.

Request:

Response:

Example: Refer to Get Referencing Transactions example.

21.5 Get Transaction

Get a transaction object given a transaction ID.

Request:

Response:

Note: The block, blockTimestamp and confirmations fields are omitted for unconfirmed transactions. Double-spending transactions are not retrieved.

Example: Refer to Get Transaction example.

21.6 Get Transaction Bytes

Get the bytecode of a transaction.

Request:

Response:

Example: Refer to Get Transaction Bytes example.

21.7 Parse Transaction

Get a transaction object given a (signed or unsigned) transaction bytecode, or re-parse a transaction object. Verify the signature.

Request:

Response: Refer to Get Transaction for additional fields.

Example: Refer to Parse Transaction example.

21.8 Retrieve Pruned Transaction

Force retrieval of the prunable data for a given transaction, even if past the configured PRIZM.maxPrunableLifetime.

Request:

Response: Refer to Get Transaction for fields.

Example: Refer to Retrieve Pruned Transaction example.

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:

Response:

Example: Refer to Send Transaction example.

21.10 Sign Transaction

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

Request:

Response:

Example: Refer to Sign Transaction example.

23 Utilities

23.1 Decode QR Code

Decodes a base64-encoded jpeg to a UTF-8 string. POST only.

Request:

Response

Example: Refer to Decode QR Code example.

23.2 Detect Mime Type

Gets the mime type of uploaded file or data.

Request:

Response

Example: Refer to Detect Mime Type example.

23.3 Encode QR Code

Encodes a UTF-8 string to a base64-encoded jpeg. POST only.

Request:

Response

Example: Refer to Encode QR Code example.

23.4 Full Hash To Id

Converts a full hash to an ID.

Request:

Response:

Example: Refer to Full Hash To Id example.

23.5 Hash

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

Request:

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:

Example: Refer to Hash example.

23.6 Hex Convert

Converts a text string into a UTF-8 hex string and if the text input is already a hex string, also into text.

Request:

Response:

Example: Refer to Hex Convert example.

23.7 Long Convert

Converts an ID to the signed long integer representation used internally.

Request:

Response:

Note: Java does not support unsigned integers, so any unsigned ID (such as a block ID) visible in the NRS client is represented internally as a signed integer.

Example: Refer to Long Convert example.

23.8 RS Convert

Get both the Reed-Solomon account address and the account number given an account ID.

Request:

Response:

Example: Refer to RS Convert example.

24 Debug Operations

All debug utilities require an adminPassword request parameter. See Admin Password for more info.

24.1 Clear Unconfirmed Transactions

Empties the unconfirmed transaction pool. POST only.

Request:

Response:

Example: Refer to Clear Unconfirmed Transactions example.

24.2 Dump Peers

Get all active peers, optionally of a certain version or a minimum weight.

Request:

Response:

Example: Refer to Dump Peers example.

24.3 Full Reset

Deletes the entire blockchain. POST only.

Request:

Response:

Note: After successful completion of the reset, a new blockchain will automatically begin downloading.

Example: Refer to Full Reset example.

24.4 Get All Broadcasted Transactions

Get unconfirmed transactions broadcasted from this node but not yet received back from a peer, if transaction rebroadcasting is enabled.

Request:

Response:

Example: Refer to Get All Broadcasted Transactions example.

24.5 Get All Waiting Transactions

Get unconfirmed transactions temporarily kept in memory during transaction processing.

Request:

Response:

Example: Refer to Get All Waiting Transactions example.

24.6 Get Log

Get up to 100 of the most recent log messages from a memory buffer.

Request:

Response:

Example: Refer to Get Log example.

24.7 Get Stack Traces

Get the stack traces of the currently running threads in reverse id order.

Request:

Response:

Example: Refer to Get Stack Traces example.

24.8 Lucene Reindex

Forces a rebuild of the Lucene search index. POST only.

Request:

Response:

Example: Refer to Lucene Reindex example.

24.9 Pop Off

Removes specified number of blocks (and associated transactions) from the top of the blockchain. POST only.

Request:

Note: If table trimming is enabled (default), at most 1440 blocks can be popped off without triggering a full rescan.

Response:

Example: Refer to Pop Off example.

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 PRIZM.enableTransactionRebroadcasting property to false. POST only.

Request:

Response:

Example: Refer to Rebroadcast Unconfirmed Transactions example.

24.11 Requeue Unconfirmed Transactions

Requeue unconfirmed transactions. POST only.

Request:

Response:

Example: Refer to Requeue Unconfirmed Transactions example.

24.12 Retrieve Pruned Data

Initiates a task of requesting and restoring missing prunable data. POST only.

Request:

Response:

Example: Refer to Retrieve Pruned Data example.

24.13 Scan

Scans the top of the blockchain. POST only.

Request:

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:

Example: Refer to Scan example.

24.14 Set Logging

Sets the log level and optionally specifies communication events to be logged, without restarting the server. POST only.

Request:

Note: The initial log level is set by the PRIZM.level logging property, currently FINE (equivalent to DEBUG).

Response:

Example: Refer to Set Logging example.

24.15 Shutdown

Shutdown the server. POST only.


Request:

Response:

Example: Refer to Shutdown example.

24.16 Trim Derived Tables

Trigger a derived tables trim, and a prunable tables pruning. POST only.


Request:

Response:

Example: Refer to Trim Derived Tables example.