Blue0x API Documentation
The Blue0x API interacts with Blue0x nodes using HTTP requests to
port 2022. 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
Nfor number or
- In the examples, the Blue0x node is represented as
localhostand 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
%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:2022/test (opens in a new tab) while a local BLX node is running. For specific API calls, use http://localhost:2022/test?requestType=specificRequestType (opens in a new tab).
Many API requests make reference to the genesis block. FYI, the genesis block's ID is
4777664216118977193. Sending messages, selling aliases, and leasing balances to the Genesis account are not allowed.
One billion BLX were created in the Genesis Block, and 100,000 BLX were then distributed to NXT owners as per the Jelurida license agreement.
The Blue0x (BLX) blockchain was created on
May 7, 2021 at 12:34:00
All API requests that require an account ID accept either an account number or the corresponding Reed-Solomon address (opens in a new tab).
The Blue0x token, BLX, is used to quantify value within the network and a certain amount of BLX is required, as a fee, for each transaction within the network. This fee goes to the node that forges (generates) the new block containing the transaction that is then accepted into the blockchain.
The Blue0x system can be thought of as a network owned by all who posses BLX. In this sense, BLX quantifies ownership of or stake in the system. Stakeholders are entitled to forge blocks and collect transaction fees in proportion to the amount of BLX they possess.
Seperate assets and currencies, such as USDX, are created within the Blue0x network. The amount of these assets and currencies are represented as integers in units of QNT, and are priced in NQT per QNT.
All API requests that create a new transaction will accept either a
secretPhrase or a
secretPhraseis supplied, a transaction is created, signed at the server, and broadcast by the server as usual.
- If only a
publicKeyparameter 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
transactionJSONwithout a signature. This JSON object along with
secretPhrasecan then be supplied to Sign Transaction as
unsignedTransactionJSONand the resulting signed
transactionJSONcan then be supplied to Broadcast Transaction. This sequence allows for offline signing of transactions so that
secretPhrasenever needs to be exposed.
unsignedTransactionBytesmay be used instead of unsigned
transactionJSONwhen there is no encrypted message. Messages to be encrypted require the
secretPhrasefor encryption and so cannot be included in
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
false. She sends to Bob the
fullHashof 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
signatureitself, as then Bob can just broadcast transaction A himself).
- Bob prepares, signs and broadcasts transaction B, setting the
referencedTransactionFullHashparameter to the
fullHashof 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
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
signedTransactionBytesshe 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.
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.
The behavior of some API calls is affected by property settings loaded from files in the
conf directory during Blue0x server intialization. This directory contains the
logging-default.properties files, both of which contain default property settings along with documentation.
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
logging.properties files in the same directory. For example, a
nxt.properties file can be created with the contents:
This causes the Blue0x server to connect to the Testnet instead of the Mainnet.
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.
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 Set API Proxy Peer API, or forced to a specific peer using the
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.