The Burst API

From Burstwiki
Revision as of 07:34, 4 December 2018 by Umbrellacorp03 (talk | contribs) (Get Account OK)

Jump to: navigation, search
The Burst API
API Version 1.0.0
BRS Version 2.2.6

Description Verified.png

The Burst API allows interaction with Burst nodes using HTTP requests to port 8125. 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 preceded by one of S for string, A for array, O for object, N for number or B for boolean.
  • In the examples, the Burst 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 on the TestNet at https://wallet.dev.burst-test.net/test. For specific API calls, use the GET url https://wallet.dev.burst-test.net/burst?requestType=specificRequestType.

Table of Contents

Contents

General Notes Verified.png

Genesis Block Verified.png

Many API requests make reference to the Genesis Block.

Flexible Account IDs Verified.png

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

Quantity Units BURST, NQT and QNT Verified.png

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


Yet internally, the currency is still stored in integer form in units of NQT or NxtQuant, where 1 BURST = 108 NQT. All parameters and fields in the API involving a quantity of BURST are denominated in units of NQT, for example feeNQT. The only exception is the field effectiveBalanceNXT, used in forging calculations.


Other assets can be created within Burst 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.

Units of BURST and its fractions
Decimal (BURST) Canonical Name Alternate Name NQT
1.00000000 BURST Burst 100,000,000
0.01000000 cBURST Bessie 1,000,000
0.00100000 mBURST - 100,000
0.00001000 - Maybel 1,000
0.00000100 uBURST - 100
0.00000001 - Planck 1
0.12345678 digit reference - -

Creating Unsigned Transactions Verified.png

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.

Escrow Operations Verified.png

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).
  • 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 1440 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.

Prunable Data Verified.png

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.


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 is only one variety of prunable data in the Burst system: prunable Arbitrary Messages. It has a maximum prunable data length of 42 kilobytes.

Properties Files Verified.png

The behavior of some API calls is affected by property settings loaded from files in the brs/conf directory during Burst server intialization. This directory contains the brs-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 brs.properties and logging.properties files in the same directory. For example, a brs.properties file can be created with the content:


DEV.TestNet = yes


This causes the Burst server to connect to the TestNet instead of the MainNet.

Create Transaction

The following API calls create Burst 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.


Create Transaction Request

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


secretPhrase is the secret passphrase of the account (optional, but transaction neither signed nor broadcast if omitted)
publicKey is the public key of the account (optional if secretPhrase provided)
feeNQT is the is the fee (in NQT) for the transaction
deadline deadline (in minutes) for the transaction to be confirmed, 1440 minutes maximum
broadcast is set to false to prevent broadcasting the transaction to the network (optional)
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
messageIsText is false if the message is a hex string, otherwise the message is text (optional)
messageToEncrypt is either UTF-8 text or a string of hex digits to be compressed and converted into a bytecode with a maximum length of one kilobyte, 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)
encryptedMessageData is already encrypted data which overrides messageToEncrypt if provided (optional)
encryptedMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptedMessageData is provided)
messageToEncryptToSelf is either UTF-8 text or a string of hex digits to be compressed 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)
encryptToSelfMessageData is already encrypted data which overrides messageToEncryptToSelf if provided (optional)
encryptToSelfMessageNonce is a unique 32-byte number which cannot be reused (optional unless encryptToSelfMessageData is provided)
recipientPublicKey is the public key of the receiving account (optional, enhances security of a new account)


For feeNQT, please refer to the following "rules":

  • minimum 1000 BURST for Issue Asset, unless singleton asset is issued, for which the fee is 1 BURST
  • 2 BURST in base fee for Set Alias, with 2 BURST additional fee for each 32 chars of name plus URI total length, after the first 32 chars
  • 1 BURST for the first 32 bytes of a unencrypted non-prunable message, 1 BURST for each additional 32 bytes
  • 2 BURST for the first 32 bytes of an encrypted non-prunable message, 1 BURST for each additional 32 bytes. The length is measured excluding the nonce and the 16 byte AES initialization vector.
  • 1 BURST for the first 1024 bytes of a prunable message, 0.1 BURST for each additional 1024 prunable bytes
  • 1 BURST for Set Account Info, including 32 chars, with 2 BURST additional fee for each 32 chars
  • 2 BURST for DGS Listing, including 32 chars of name plust description. With 2 BURST additional fee for each 32 chars.
  • 1 BURST for DGS Delivery, including 32 bytes of encrypted goods data (AES initialization bytes and nonce excluded). With 2 BURST additional fee for each 32 bytes.
  • 2 BURST for transactions that make use of referencedTransactionFullHash property when creating a new transaction.
  • Dynamic tx fee otherwise, where 1 BURST = 100000000 NQT
Progressive Tx fee reference
Tx no Tx fees
1 0.00735
100 0.73500
255 1.87425
510 3.74850
765 5.62275
1020 7.49700

Note: A detailed explanation is available here : Slot-Based Transaction Fees.


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

Create Transaction Response Verified.png

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

(S) signatureHash is the SHA-256 hash of the transaction signature
(S) unsignedTransactionBytes is the the unsigned transaction bytes
(O) transactionJSON is the transaction object (refer to Get Transaction for details)
(B) broadcasted is the the transaction was broadcasted or not
(N) requestProcessingTime is the API request processing time (in millisec)
(S) transactionBytes is the the signed transaction bytes
(S) fullHash is the full hash of the signed transaction
(S) transaction is the ID of the newly created transaction

Account Operations Verified.png

Get Account Verified.pngVerified.png

Get account information given an account ID.

Request:
requestType is getAccount
account is the account ID

Response:

(S) unconfirmedBalanceNQT is the balanceNQT less unconfirmed outgoing transactions, the balance displayed in the client
(S) guaranteedBalanceNQT is the balance (in NQT) of the account with at least 1440 confirmations
(A) unconfirmedAssetBalances is the uncofirmend asset balance of the account
(S) effectiveBalanceNXT is the balance (in BURST) of the account available for forging: the unleased guaranteedBalance of this account plus the leased guaranteedBalance of all lessors to this account
(S) accountRS is the Reed-Solomon address of the account
(S) name is the name of the account
(S) forgedBalanceNQT is the balance (in NQT) that the account has forged
(S) balanceNQT is the minimally confirmed basic balance (in NQT) of the account
(S) publicKey is the public key of the account
(A) assetBalances is the balance of all assets of the account
(S) account is the account number
(N) requestProcessingTime is the the API request processing time (in millisec)

Example: Refer to Get Account example.

Get Account Block Ids Verified.png

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

Request:
requestType is getAccountBlockIds
account is the account ID
timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)
firstIndex is the zero-based index to the first block to retrieve (optional)
lastIndex is the zero-based index to the last block to retrieve (optional)

Response:

(A) blockIds is the array of block IDs
(N) requestProcessingTime is the API request processing time (in millsec)

Example: Refer to Get Account Block Ids example.

Get Account Blocks Verified.png

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

Request:
requestType is getAccountBlocks
timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)
firstIndex is the zero-based index to the first block to retrieve (optional)
lastIndex is the zero-based index to the last block to retrieve (optional)
includeTransactions is the true to retrieve transaction details, otherwise only transaction IDs are retrieved (optional) (optional)

Response:

(A) blocks is the array of blocks (refer to Get Block for details)
(N) requestProcessingTime is the API request processing time (in millsec)

Example: Refer to Get Account Blocks example.

Get Account Id Verified.png

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

Request:
requestType is getAccountId
secretPhrase is the secret passphrase of the account (optional if publicKey provided)
publicKey is the public key of the account (optional if secretPhrase provided)

Response:

(S) accountRS is the Reed-Solomon address of the account
(S) publicKey is the public key of the account
(N) requestProcessingTime is the API request processing time (in millisec)
(S) account is the account number

Example: Refer to Get Account Id example.

Get Account Lessors Verified.png

Get the lessors to an account.

Request:
requestType is getAccountLessors
account is the account ID
height is the height of the blockchain to detemine the lessors (option, default is the last block)
Note: If table trimming is enabled (default), the height must be within 1440 blocks of the last block.

Response:

(A) lessors is the array of lessor objects including the fields:

  • lessorRS (S)
  • lessor (S)
  • guaranteedBalanceNQT (S)

(S) accountRS is the Reed-Solomon address of the account
(N) requestProcessingTime is the API request processing time (in millisec)
(S) account is the account number
(N) height is the height of the blockchain

Example: Refer to Get Account Lessors example.

Get Account Public Key Verified.png

Get the public key associated with an account ID.

Request:
requestType is getAccountPublicKey
account is the account ID

Response:

(S) publicKey is the 32-byte public key associated with the account, returned as a hex string
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Public Key example.

Get Account Transaction Ids Verified.png

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

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 the a zero-based index to the first transaction ID to retrieve (optional)
lastIndex is the a zero-based index to the last transaction ID to retrieve (optional)
numberOfConfirmations is the required number of confirmations per transaction (optional)
Note: Refer to Get Constants for definitions of types and subtypes

Response:

(A) transactionIds is the array of transaction IDs
(S) lastBlock is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Transaction Ids example. ===Get Account Transactions Verified.png===Get the transactions associated with an account in reverse block timestamp order.

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 the a zero-based index to the first transaction ID to retrieve (optional)
lastIndex is the a zero-based index to the last transaction ID to retrieve (optional)
numberOfConfirmations is the required number of confirmations per transaction (optional)

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

Response:

(A) transaction is the array of transaction (refer to Get Transaction for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Transactions example.

Get Balance Verified.png

Get the balance of an account.

Request:
requestType is getBalance
account is the account ID

Response:

(S) unconfirmedBalanceNQT is the balanceNQT less unconfirmed outgoing transactions, the balance displayed in the client
(S) guaranteedBalanceNQT is the balance (in NQT) of the account with at least 1440 confirmations
(N) effectiveBalanceNXT is the balance (in BURST) of the account available for forging: the unleased guaranteedBalance of this account plus the leased guaranteedBalance of all lessors to this account
(S) forgedBalanceNQT is the balance (in NQT) that the account has forged
(S) balanceNQT is the minimally confirmed basic balance (in NQT) of the account
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Balance example.

Get Guaranteed Balance Verified.png

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

Request:
requestType is getGuaranteedBalance
account is the 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)

Response:

(S) guaranteedBalanceNQT is the balance (in NQT) of the account with at least numberOfConfirmations confirmations
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Guaranteed Balance example.

Get Unconfirmed Transaction Ids Verified.png

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

Request:
requestType is getUnconfirmedTransactionIds
account is the account ID (optional)

Response:

(N) requestProcessingTime is the API request processing time (in millisec)
(A) unconfirmedTransactionIds is the array of unconfirmed transaction IDs

Example: Refer to Get Unconfirmed Transaction Ids example.

Get Unconfirmed Transactions Verified.png

Get a list of unconfirmed transactions associated with an account.

Request:
requestType is getUnconfirmedTransactions
account is the account ID (optional)

Response:

(A) unconfirmedTransactions is the array of unconfirmed transactions (refer to Get Transaction for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Unconfirmed Transactions example.

Get Escrow Transaction Verified.png

Get information regarding an escrow with the escrow transaction ID.

Request:
requestType is getEscrowTransaction
escrow is the escrow ID

Response:

(A) signers is the array of signers
(S) senderRS is the Reed-Solomon address of the sender
(S) sender is the account ID of the sender
(S) amountNQT is the amount (in NQT) of the transaction
(S) recipientRS is the Reed-Solomon address of the recipient, if applicable
(S) recipient is the account number of the recipient, if applicable
(N) id is the id of the escrow transaction
(N) requestProcessingTime is the API request processing time (in millisec)
(N) deadline is the deadline for the transaction to be confirmed
(S) deadlineAction is the the action at the end of the escrow transaction. ("split", "refund" or "release")
(N) requiredSigners is the number of required signers

Example: To do

Get Account Escrow Transactions Verified.png

Request:
requestType is getAccountEscrowTransactions
account is the account ID

Response:

(A) escrows is the array of escows
(N) requestProcessingTime is the API request processing time (in millisec)

Example: To do

Get Subscription Verified.png

Get the detail of a subscription.

Request:
requestType is getSubscription
subscription is the subscription ID

Response:

(N) id is the id of the subscription transaction
(N) timeNext is the Time stamp of the next subscription payment
(N) requestProcessingTime is the API request processing time (in millisec)
(N) frequency is the frequency of the subscription payment (in seconds)

Example: Refer to Get Subscription example.

Get Subscriptions To Account Verified.png

Get the details of subcriptions paid to an account.

Request:
requestType is getSubscriptionsToAccount
account is the account ID

Response:

(A) subscriptions is the array of subscriptions
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Subscriptions To Account example.

Get Account Subscriptions Verified.png

Get all subscriptions related to an account.

Request:
requestType is getAccountSubscriptions

Response:

(A) subscriptions is the array of subscriptions
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Subscriptions example.

Send Money Verified.png

Send BURST to an account. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is sendMoney
recipient is the account ID of the recipient.
amountNQT is the amount (in NQT) in the transaction

Response: Refer to Create Transaction Response.

Example: Refer to Send Money example.

Send Money Multi Verified.png

Send individual amounts of BURST to up to 64 recipients. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is sendMoneyMulti
recipients is the account ID of the recipients. The recipients string is <numid1>:<amount1>;<numid2>:<amount2>;<numidN>:<amountN>

Response: Refer to Create Transaction Response.

Example: To do

Send Money Multi Same Verified.png

Send the same amount of BURST to up to 128 recipients. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is sendMoneyMultiSame
recipients is the account ID of the recipients. The recipients string is <numid1>;<numid2>;<numidN>
amountNQT is the amount (in NQT) in the transaction

Response: Refer to Create Transaction Response.

Example: To do

Send Money Escrow

Request:
requestType is sendMoneyEscrow

Response: To do

Example: To do

Send Money Subscription Verified.png

Send the same amount to a predefined account with a fixed frequency.

Request:
requestType is sendMoneySubscription
recipient is the account ID of the recipient.
amountNQT is the amount (in NQT) in the transaction
frequency is the frequency (in seconds) at which the money is sent.

Response: Refer to Create Transaction Response.

Example: Refer to Send Money Subscription example.

Cancel Subscription

Cancel a subscription. Refer to Create Transaction Request for common parameters.

Request:
requestType is subscriptionCancel
subscription is the ID of the subscription to cancel.

Response: Refer to Create Transaction Response

Example: Refer to Cancel Subscription example.

Set Account Info Verified.png

Set account information. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is setAccountInfo
name is the name to associate with the account
description is the description to associate with the account

Response: Refer to Create Transaction Response.

Example: Refer to Set Account Info example.

Alias Operations Verified.png

Buy / Sell Alias Verified.png

Buy or sell an alias. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is either buyAlias or sellAlias
alias is the ID of the alias (optional)
aliasName is the alias name (optional if alias provided)
priceNQT is the asking price (in NQT) of the alias (sellAlias only)
amountNQT is the amount (in NQT) offered for an alias for sale (buyAlias only)
recipient is the account ID of the recipient (only required for sellAlias and only if there is a designated recipient)

Note: An alias can be transferred rather than sold by setting priceNQT to zero. A pending sale can be canceled by selling again to self for a price of zero.

Response: Refer to Create Transaction Response.

Example: Refer to Buy / Sell Alias example.

Set Alias Verified.png

Create and/or assign an alias. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is setAlias
aliasName is the alias name
aliasURI is the alias URI (e.g. http://www.google.com/)

Response: Refer to Create Transaction Response. The transaction ID is also the alias ID.

Example: Refer to Set Alias example.

Get Alias Verified.png

Get information about a given alias.

Request:
requestType is getAlias
alias is the alias ID (optional)
aliasName is the name of the alias (optional if alias provided)

Response:

(S) aliasURI is the what the alias points to, in URI format
(S) aliasName is the name of the alias
(S) accountRS is the Reed-Solomon address of the account that owns the alias
(S) alias is the alias ID
(N) requestProcessingTime is the API request processing time (in millisec)
(S) account is the number of the account that owns the alias
(N) timestamp is the time (in seconds since the genesis block) when the alias was created or last transferred

Example: Refer to Get Alias example.

Get Aliases Verified.png

Get information on aliases owned by a given account in alias name order.

Request:
requestType is getAliases
timestamp is the earliest creation time (in seconds since the genesis block) of the aliases (optional)
account is the ID of the account that owns the aliases
firstIndex is the zero-based index to the first alias to retrieve (optional)
lastIndex is the zero-based index to the last alias to retrieve (optional)
lastIndex is the zero-based index to the last alias to retrieve (optional)

Response:

(A) aliases is the array of alias objects (refer to Get Alias for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Aliases example.

Arbitrary Message System Operations Verified.png

Decrypt From Verified.png

Decrypt an AES-encrypted message.

Request:
requestType is decryptFrom
account is the account ID of the sender
data is the AES-encrypted data
nonce is the unique nonce associated with the encrypted data
decryptedMessageIsText is false if the decrypted message is a hex string, true if the decrypted message is text
secretPhrase is the secret passphrase of the recipient

Response:

(S) decryptedMessage is the decrypted message
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Decrypt From example.

Encrypt To Verified.png

Encrypt a message using AES without sending it.

Request:
requestType is encryptTo
recipient is the account ID of the recipient.
messageToEncrypt is either UTF-8 text or a string of hex digits to be compressed and converted into a 1000 byte maximum bytecode then encrypted using AES
messageToEncryptIsText is false if the message to encrypt is a hex string, true if the encrypted message is text
secretPhrase is the secret passphrase of the recipient

Response:

(S) data is the AES-encrypted data
(S) nonce is the 32-byte pseudorandom nonce
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Encrypt To example.

Read Message Verified.png

Get a message given a transaction ID.

Request:
requestType is readMessage
transaction is the transaction ID of the message
secretPhrase is the secret passphrase of the account that received the message (optional)

Response:

(S) message is the plain message, if applicable
(S) decryptedMessage is the decrypted message, if applicable and only if the provided secretPhrase belongs to either the sender or receiver of the transaction
(S) decryptedMessageToSelf is the decrypted message sent to self, if applicable and only if the provided secretPhrase belongs to the sender of transaction
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Read Message example.

Send Message Verified.png

Create an Arbitrary Message transaction. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is sendMessage
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 (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

Response: Refer to Create Transaction Response.

Example: Refer to Send Message example.

Asset Exchange Operations Verified.png

Cancel Order Verified.png

Cancel an existing asset order. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is either cancelBidOrder or cancelAskOrder
order is the order ID of the order being canceled

Response: Refer to Create Transaction Response.

Example: Refer to Cancel Order example.

Get Account Current Order Ids Verified.png

Get current asset order IDs given an account ID in reverse block height order.

Request:
requestType is either getAccountCurrentBidOrderIds or getAccountCurrentAskOrderIds
account is the account ID
asset is an asset ID filter (optional)
firstIndex is a zero-based index to the first order ID to retrieve (optional)
lastIndex is a zero-based index to the last order ID to retrieve (optional)

Response:

(A) bidOrderIds or askOrderIds is the array of order IDs
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Current Order Ids example.

Get Account Current Orders Verified.png

Get current asset orders given an account ID in reverse block height order.

Request:
requestType is either getAccountCurrentBidOrders or getAccountCurrentAskOrders
account is the account ID
asset is an asset ID filter
firstIndex is a zero-based index to the first order ID to retrieve (optional)
lastIndex is a zero-based index to the last order ID to retrieve (optional)

Response:

(A) bidOrders or askOrders is the array of order objects (refer to Get Order for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Account Current Orders example.

Get All Assets Verified.png

Get all assets in the exchange in reverse block height of creation order.

Request:
requestType is getAllAssets
firstIndex is a zero-based index to the first asset to retrieve (optional)
lastIndex is a zero-based index to the last asset to retrieve (optional)

Response:

(A) assets is the array of asset objects (refer to Get Asset)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get All Assets example.

Get All Open Orders Verified.png

Get all open bid/ask orders in reverse block height order.

Request:
requestType is either getAllOpenBidOrders or getAllOpenAskOrders
firstIndex is a zero-based index to the first order to retrieve (optional)
lastIndex is a zero-based index to the last order to retrieve (optional)

Response:

(N) requestProcessingTime is the API request processing time (in millisec)
(A) openOrders is the array of order objects (refer to Get Order for details)

Example: Refer to Get All Open Orders example.

Get All Trades Verified.png

Get all trades since a given timestamp in reverse block height order.

Request:
requestType is getAllTrades
timestamp is the timestamp (in seconds since the genesis block) to begin retrieving trades (optional, default 0)
firstIndex is a zero-based index to the first trade to retrieve (optional)
lastIndex is a zero-based index to the last trade to retrieve (optional)
includeAssetInfo is true if asset information is to be included in the result (optional)

Note: If timestamp is omitted or zero, and no index is given, all trades in the entire blockchain will be retrieved, which may timeout or crash your system.

Response:

(A) trades is the array of trade objects (refer to Get Trades)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get All Trades example.

Get Asset Verified.png

Get asset information given an asset ID.

Request:
requestType is getAsset
asset is the asset ID

Response:

(S) quantityQNT is the total asset quantity (in QNT) in existence
(N) numberOfAccounts is the number of accounts that own the asset
(S) accountRS is the Reed-Solomon address of the account that issued the asset
(N) decimals is the number of decimal places used by the asset
(N) numberOfTransfers is the number of transfers of this asset
(S) name is the asset name
(S) description is the asset description
(N) numberOfTrades is the number of trades of this asset
(N) requestProcessingTime is the API request processing time (in millisec)
(N) asset is the asset ID
(S) account is the number of the account that issued the asset

Example: Refer to Get Asset example.

Get Asset Accounts Verified.png

Get the accounts that own an asset given the asset ID in reverse quantity order.

Request:
requestType is getAssetAccounts
asset is the asset ID
height is the height of the blockchain to determine the accounts (optional, default is last block)
firstIndex is a zero-based index to the first account to retrieve (optional)
lastIndex is a zero-based index to the last account to retrieve (optional)

Note: If table trimming is enabled (default), the height must be within 1440 blocks of the last block.

Response:

(A) accountAssets is the array of asset objects with the following fields for each asset:

  • (S) quantityQNT is the quantity (in QNT) of the asset
  • (S) accountRS is the Reed-Solomon address of the account that owns the asset
  • (S) unconfirmedQuantityQNT is the unconfirmed quantity (in QNT) of the asset
  • (S) asset is the asset ID
  • (S) account is the number of the account that owns the asset

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

Example: Refer to Get Asset Accounts example.

Get Asset Ids Verified.png

Get the IDs of all assets in the exchange in reverse block height of creation order.

Request:
requestType is getAssetIds
firstIndex is the zero-based index to the first asset ID to retrieve (optional)
lastIndex is the zero-based index to the last asset ID to retrieve (optional)

Response:

(A) assets is the array of asset IDs
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Asset Ids example.

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 getAssetTransfers provides expected transfers from the unconfirmed transactions pool or phased transactions scheduled to finish in the next block
asset is the asset ID (optional)
account is the account ID (optional if asset provided)
includeAssetInfo is true if the decimals and name fields are to be included (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 zero-based index to the last transfer to retrieve (optional, does not apply to expected transfers)

Response:

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

  • (S) quantityQNT is the quantity (in QNT) of the asset traded
  • (S) senderRS is the Reed-Solomon address of the sender
  • (S) assetTransfer is the transaction ID of the asset transfer
  • (S) sender is the account ID of the sender
  • (S) recipientRS is the Reed-Solomon address of the recipient
  • (N) decimals is the number of decimal places used by the asset (if includeAssetInfo is true)
  • (S) recipient is the account number of the recipient
  • (S) name is the name of the asset (if includeAssetInfo is true)
  • (S) asset is the asset ID
  • (N) height is the height of the transfer block
  • (N) timestamp is the timestamp (in seconds since the genesis block) of the transfer block, does not apply to an expected transfer

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

Example: Refer to Get Asset Transfers example.

Get Assets Verified.png

Get asset information given multiple asset IDs

Request:
requestType is getAssets
assets is one of the multiple asset IDs
assets is one of the multiple asset IDs
assets is one of the multiple asset IDs

Response:

(A) assets is the array of asset objects (refer to Get Asset)

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

Example: Refer to Get Assets example.

Get Assets By Issuer Verified.png

Get asset information given multiple creation account IDs in reverse block height of creation order.

Request:
requestType is getAssetsByIssuer
account is one of the multiple account IDs
account is one of the multiple account IDs
firstIndex is a zero-based index to the first asset to retrieve (optional)
lastIndex is zero-based index to the last asset to retrieve (optional)

Response:

(A) assets is the array of asset objects (refer to Get Asset)

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

Example: Refer to Get Assets By Issuer example.

Get Order Verified.png

Get a bid/ask order given an order ID.

Request:
requestType is either getBidOrder or getAskOrder
order is the Order ID

Response:

(S) quantityQNT is the order quantity (in QNT)
(S) priceNQT is the order price (in NQT)
(S) accountRS is the Reed-Solomon address of the account
(N) requestProcessingTime is the API request processing time (in millisec)
(S) asset is the ID of the asset being ordered
(S) type is the type of order (bid or ask)
(S) account is the account number associated with the order
(S) order is the ID of the order
(N) height is the block height of the order transaction

Example: Refer to Get Order example.

Get Order Ids Verified.png

Get bid/ask order IDs given an asset ID, in order of decreasing bid price or increasing ask price.

Request:
requestType is either getBidOrderIds or getAskOrderIds
asset is the asset ID
firstIndex is a zero-based index to the first order ID to retrieve (optional)
lastIndex is a zero-based index to the last order ID to retrieve (optional)

Response:

(A) bidOrderIds or askOrderIds is the array of order IDs
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Order Ids example.

Get Orders Verified.png

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

Response:

(A) bidOrders or askOrders is the 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

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

Example: Refer to Get Orders example.

Get Trades Verified.png

Get trades associated with a given asset and/or account in reverse block height order.

Request:
requestType is getTrades
asset is the asset ID
account is the account ID (optional if asset provided)
firstIndex is a zero-based index to the first trade to retrieve (optional)
lastIndex is a zero-based index to the last trade to retrieve (optional)
includeAssetInfo is true if the decimals and name fields are to be included (optional)

Response:

(A) trades is the array of trade objects with the following fields for each trade:

  • (S) seller is the account number of the seller
  • (S) quantityQNT is the quantity (in QNT) of the asset traded
  • (S) bidOrder is the bid order ID
  • (S) sellerRS is the Reed-Solomon address of the seller
  • (S) buyer is the account number of the buyer
  • (S) priceNQT is the trade price (in NQT, the ask price for a buy or the bid price for a sell)
  • (S) askOrder is the ask order ID
  • (S) buyerRS is the Reed-Solomon address of the buyer
  • (N) decimals is the number of decimal places used by the asset
  • (S) name is the name of the asset (if includeAssetInfo is true)
  • (S) block is the block ID of the trade (if includeAssetInfo is true)
  • (S) asset is the asset ID
  • (N) askOrderHeight is the block height of the ask order
  • (N) bidOrderHeight is the block height of the bid order
  • (S) tradeType is the trade type (sell or buy, where buy implies that the bid occurred after the ask, or if in the same block, has a greater order ID)
  • (N) timestamp is the timestamp (in seconds since the genesis block) of the trade block
  • (N) height is the height of the trade block

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

Example: Refer to Get Trades example.

Issue Asset Verified.png

Create an asset on the exchange. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is issueAsset
name is the name of the asset
description is the url-encoded description of the asset in UTF-8 with a maximum length of 1000 bytes (optional)
quantityQNT is the total amount (in QNT) of the asset in existence
decimals is the number of decimal places used by the asset (optional, zero default)

Response: Refer to Create Transaction Response. The transaction ID is also the asset ID.

Example: Refer to Issue Asset example.

Place Order Verified.png

Place an asset order. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is either placeBidOrder or placeAskOrder
asset is the asset ID of the asset being ordered
quantityQNT is the amount (in QNT) of the asset being ordered
priceNQT is the bid/ask price (in NQT)

Response: Refer to Create Transaction Response. The transaction ID is also the order ID.

Example: Refer to Place Order example.

Transfer Asset Verified.png

Transfer a quantity of an asset from one account to another. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is transferAsset
recipient is the recipient account ID
recipientPublicKey is the public key of the recipient account (optional, enhances security of a new account)
asset is the ID of the asset being transferred
quantityQNT is the amount (in QNT) of the asset being transferred

Response: Refer to Create Transaction Response. The transaction ID is also the transfered asset ID.

Example: Refer to Transfer Asset example.

Automated Transactions Invalid.png

Create an Automated Transaction Program Invalid.png

Request:
requestType is createATProgram

Response: To do

Example: To do

Get AT Invalid.png

Request:
requestType is getAT

Response: To do

Example: To do

Get AT Details Invalid.png

Request:
requestType is getATDetails

Response: To do

Example: To do

Get AT Ids Invalid.png

Request:
requestType is getATIds

Response: To do

Example: To do

Get AT Long Invalid.png

Request:
requestType is getATLong

Response: To do

Example: To do

Get Account ATs Verified.png Verified.png

Get all ATs of a specific account. Request:
requestType is getAccountATs
account is the account ID

Response:

(A) ats is the array containing all details of ATs
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get account ATs example.

Block Operations

Get Block Verified.png

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

Request:
requestType is getBlock
block is the block ID (optional)
height is the block height (optional if block provided)
timestamp is the timestamp (in seconds since the genesis block) of the block (optional if height provided)
includeTransactions is true to include transaction details (optional)

Note: block overrides height which overrides timestamp.

Response:

(S) previousBlockHash is the 32-byte hash of the previous block
(N) payloadLength is the length (in bytes) of all transactions included in the block
(S) totalAmountNQT is the total amount (in NQT) of the transactions in the block
(S) generationSignature is the 32-byte generation signature of the generating account
(S) generator is the the generating account number
(S) generatorPublicKey is the 32-byte public key of the generating account
(S) baseTarget is the base target for the next block generation
(S) payloadHash is the 32-byte hash of the payload (all transactions)
(S) generatorRS is the Reed-Solomon address of the generating account
(S) blocReward is the total block reward
(S) nextBlock is the next block ID
(N) requestProcessingTime is the API request processing time (in millisec)
(S) scoopNum is the scoop number
(N) numberOfTransactions is the number of transactions in the block
(S) blockSignature is the 64-byte block signature
(A) transactions is the array of transaction IDs or transaction objects (if includeTransactions provided, refer to Get Transaction for details)
(N) nonces is the actual nonce number
(S) version is the block version
(S) totalFeeNQT is the total fee (in NQT) of the transactions in the block
(S) previousBlock is the previous block ID
(S) block is the block ID
(N) height is the zero-based block height
(N) timestamp is the timestamp (in seconds since the genesis block) of the block

Example: Refer to Get Block example.

Get Block Id Verified.png

Get a block ID given a block height.

Request:
requestType is getBlockId
height is the block height

Response:

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

Example: Refer to Get Block Id example.

Get Blocks Verified.png

Get blocks from the blockchain in reverse block height order.

Request:
requestType is getBlocks
firstIndex is the first block to retrieve (optional, default is zero or the last block on the blockchain)
lastIndex is the last block to retrieve (optional, default is firstIndex + 99)
includeTransactions is true to include transaction details (optional)

Response:

(A) blocks is the array of blocks retrieved (refer to Get Block for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Blocks example.

Get EC Block Verified.png

Get Economic Cluster block data.

Request:
requestType is getECBlock
timestamp is the timestamp (in seconds since the genesis block) of the EC block (optional, default (or zero) is the current timestamp)
Note: If timestamp is more than 15 seconds before the timestamp of the last block on the blockchain, errorCode 4 is returned.

Response:

(N) ecBlockHeight is the EC block height
(N) requestProcessingTime is the API request processing time (in millisec)
(S) ecBlockId is the EC block ID
(N) timestamp is the timestamp (in seconds since the genesis block) of the EC block

Example: Refer to Get EC Block example.

Digital Goods Store Operations Verified.png

In the Burst client interface, the Digital Goods Store (DGS) is referred to as Marketplace.

DGS Delisting Verified.png

Delist a listed product. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsDelisting
goods is the goods ID

Response: Refer to Create Transaction Response.

Example: Refer to DGS Delisting example.

DGS Delivery Verified.png

Deliver a product. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsDelivery
purchase is the purchase order ID
discountNQT is the discount (in NQT) off the selling price (optional, default is zero)
goodsToEncrypt is the product, a text or a hex string to be encrypted (optional if goodsData provided)
goodIsText is false if goodsToEncrypt is a hex string (optional)
goodsData is AES-encrypted (using Encrypt To) goodsToEncrypt, up to 1000 bytes long (required only if secretPhrase is omitted)
goodsNonce is the unique nonce associated with the encrypted data (required only if secretPhrase is omitted)

Note: If the encrypted goods data is longer than 1000 bytes, use a prunable encrypted message to deliver the goods.

Response: Refer to Create Transaction Response.

Example: Refer to DGS Delivery example.

DGS Feedback Verified.png

Give feedback about a purchased product after delivery. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsFeedback
purchase is the purchase order ID
message is the unencrypted (public) feedback text up to 1000 bytes

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 BRS client does not recognize non-public feedback messages.

Response: Refer to Create Transaction Response.

Example: Refer to DGS Feedback example.

DGS Listing Verified.png

List a product in the DGS by creating a listing transaction. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsListing
name is the name of the product up to 100 characters in length
description is the description of the product up to 1000 characters in length
tags is up to three comma separated keywords describing the product up to 100 characters in length (optional)
quantity is the quantity of the product for sale
priceNQT is the price (in NQT) of the product

Response: Refer to Create Transaction Response. The transaction ID is also the goods ID.

Example: Refer to DGS Listing example.

DGS Price Change Verified.png

Change the price of a listed product. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsPriceChange
goods is the goods ID of the product
priceNQT is the new price of the product

Response: Refer to Create Transaction Response.

Example: Refer to DGS Price Change example.

DGS Purchase Verified.png

Purchase a product for sale. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsPurchase
goods is the goods ID of the product
priceNQT is the price of the product
quantity is the quantity to be purchased
deliveryDeadlineTimestamp is the timestamp (in seconds since the genesis block) by which delivery of the product must occur

Response: Refer to Create Transaction Response. The transaction ID is also the purchase order ID.

Example: Refer to DGS Purchase example.

DGS Quantity Change Verified.png

Change the quantity of a listed product. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsQuantityChange
goods is the goods ID of the product
deltaQuantity is the change in the quantity of the product for sale (use negative numbers for a decrease in quantity)

Response: Refer to Create Transaction Response.

Example: Refer to DGS Quantity Change example.

DGS Refund Verified.png

Refund a purchase. POST only. Refer to Create Transaction Request for common parameters.

Request:
requestType is dgsRefund
purchase is the purchase order ID
refundNQT is the amount (in NQT) of the refund

Response: Refer to Create Transaction Response.

Example: Refer to DGS Refund example.

Get DGS Good Verified.png

Get a DGS product given a goods ID.

Request:
requestType is dgsDGSGood
goods is the goods ID of the product

Response:

(S) seller is the seller's account ID
(S) priceNQT is the current price of the product
(N) quantity is the quantity of the product remaining for sale
(S) name is the name of the product
(S) goods is the ID of the product
(S) description is the description of the product
(S) sellerRS is the Reed-Solomon address of the seller's account
(N) requestProcessingTime is the API request processing time (in millisec)
(B) delisted is true if the product has been delisted, false otherwise
(S) tags is the comma separated list of tags provided by the seller when the listing was created
(N) timestamp is the timestamp (in seconds since the genesis block) of the creation of the product listing

Example: Refer to Get DGS Good example.

Get DGS Goods Verified.png

Get DGS products for sale in reverse chronological listing creation order unless a seller is given, then in product name order.

Request:
requestType is getDGSGoods
seller is the account ID of the product seller (optional)
firstIndex is the zero-based index to the first product to retrieve (optional)
lastIndex is the zero-based index to the last product to retrieve (optional)
inStockOnly is false if out-of-stock products (zero quantity) are to be retrieved (optional)

Note: If none of the optional parameters are specified, all in-stock products in the blockchain are retrieved at once, which may take a long time.

Response:

(A) goods is the array of goods (refer to Get DGS Good for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get DGS Goods example.

Get DGS Pending Purchases Verified.png

Get pending purchase orders given a seller ID in reverse chronological order.

Request:
requestType is getDGSPendingPurchases
seller is the account ID of the seller
firstIndex is the zero-based index to the first purchase order to retrieve (optional)
lastIndex is the zero-based index to the last purchase order to retrieve (optional)

Response:

(A) purchases is the array of pending purchase orders (refer to Get DGS Purchase for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get DGS Pending Purchases example.

Get DGS Purchase Verified.png

Get a purchase order given a purchase order ID.

Request:
requestType is getDGSPurchase
purchase is the purchase order ID

Response:

(S) seller is the account number of the seller
(N) quantity is the quantity of the product to be purchased
(B) pending is true if the deliveryDeadline has not passed, false otherwise
(S) purchase is the purchase order ID
(S) goods is the ID of the product
(S) sellerRS is the Reed-Solomon address of the seller
(N) requestProcessingTime is the API request processing time (in millisec)
(S) buyerRS is the account number of the buyer
(S) priceNQT is the the price (in NQT) of the product
(N) deliveryDeadlineTimestamp is the timestamp (in seconds since the genesis block) by which the product must be delivered
(S) buyerRS is the Reed-Solomon address of the buyer
(S) name is the name of the product
(N) timestamp is the timestamp (in seconds since the genesis block) of the purchase order

Example: Refer to Get DGS Purchase example.

Get DGS Purchases Verified.png

Get purchase orders given a seller and/or buyer ID in reverse chronological order.

Request:
requestType is getDGSPurchases
seller is the account ID of the seller (optional)
buyer is the account ID of the buyer (optional if seller provided)
firstIndex is the zero-based index to the purchase order to retrieve (optional)
lastIndex is the zero-based index to the purchase order to retrieve (optional)
completed is true if only completed purchase orders are to be included (optional)

Response:

(A) purchases is the array of purchase orders (refer to Get DGS Purchase for details)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get DGS Purchases example.

Mining Invalid.png

Get Mining Info Verified.png Verified.png

Request:
requestType is getMiningInfo

Response:

(S) generationSignature is based from the previous block generation signature and block generator. This value is then used by miners to forge a new block. Generation signature is 32bytes long.
(N) baseTarget is calculated from the last 24 blocks. This value adjusts the difficulty for the miners. The lower the base target, the harder it is for a miner to find a low deadline.
(N) requestProcessingTime is the API request processing time (in millisec)
(N) height is the previous block’s number + 1

Example: Refer to Get mining info example.

Set Reward Recipient Invalid.png

Set Reward recipient is used to set the reward recipient of a given account.

Request:
requestType is setRewardRecipient
recipient is the account ID of the recipient.

Response:

Refer to Create Transaction Response.

Example: To do

Get Reward Recipient Verified.png Verified.png

Request:
requestType is getRewardRecipient
account is the account ID.

Response:

(S) rewardRecipient is the id of the reward recipient.
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get reward recipient example.

Submit Nonce Invalid.png

Request:
requestType is submitNonce

Response: To do

Example: To do

Get Accounts With Reward Recipient Verified.png Verified.png

Request:
requestType is getAccountsWithRewardRecipient
account is the account ID (either RS address or number)

Response:

(A) accounts is the the account ID of pool members.
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Accounts With Reward Recipient example.

Server Information Operations Verified.png

Get My Info Verified.png Verified.png

Get hostname and address of the requesting node.

Request:
requestType is getMyInfo

Response:

(S) host is the node hostname
(S) address is the node address
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get My Info example.

Get Blockchain Status Verified.png Verified.png

Get the blockchain status.

Request:
requestType is getBlockchainStatus

Response:

(S) lastBlock is the last block ID on the blockchain
(S) application is the application name, typically BRS
(B) isScanning is true if the blockchain is being scanned by the application, false otherwise
(S) cumulativeDifficulty is the cumulative difficulty
(N) lastBlockchainFeederHeight is the height of the last blockchain of greatest cumulative difficulty obtained from a peer
(N) numberOfBlocks is the number of blocks in the blockchain (height + 1)
(N) time is the current timestamp (in seconds since the genesis block)
(S) version is the application version
(S) lastBlockchainFeeder is the address or announced address of the peer providing the last blockchain of greatest cumulative difficulty
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Blockchain Status example.

Get Constants Verified.png Verified.png

Get all defined constants.

Request:
requestType is getConstants

Response:

(N) maxBlockPayloadLength is the maximum block payload length (in bytes)
(S) genesisAccountId is the genesis account number
(S) genesisBlockId is the genesis block ID
(A) transactionTypes is the array of defined transaction types and subtypes (refer to the example below)
(A) peerStates is the array of defined peer states (refer to the example below)
(N) maxArbitraryMessageLength is the maximum length (in bytes) of an arbitrary message
(O) requestTypes is the array of decined request types (refer to the example below)

Example: Refer to Get Constants example.

Get Peer Verified.png Verified.png

Get information about a given peer.

Request:
requestType is getPeer
peer is the IP address or domain name of the peer (plus optional port)

Response:

(N) lastUpdated is the timestamp (in seconds since the genesis block) of the last peer status update
(N) downloadedVolume is the number of bytes downloaded by the peer
(B) blacklisted is true if the peer is blacklisted
(S) announcedAddress is the name that the peer announced to the network (could be a DNS name, IP address, or any other string)
(S) application is the name of the software application, typically BRS
(N) uploadedVolume is the number of bytes uploaded by the peer
(N) state defines the state of the peer: 0 for NON_CONNECTED, 1 for CONNECTED, or 2 for DISCONNECTED
(S) version is the version of the software running on the peer
(S) platform is the string representing the peer's platform
(B) shareAddress is true if the address is allowed to be shared with other peers
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Peer example.

Get Peers Verified.png Verified.png

Get a list of peer IP addresses.

Request:
requestType is getPeers
active is true for active (not NON_CONNECTED) peers only (optional, if true overrides state)
state is the state of the peers, one of NON_CONNECTED, CONNECTED, or DISCONNECTED (optional)

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

Response:

(A) peers is the array of peer addresses
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Peers example.

Get State Verified.png Verified.png

Get the state of the server node and network.

Request:
requestType is getState
includeCounts is false if the fields numberOf are to be excluded

Response:

(N) numberOfPeers is the number of known peers on the network
(N) numberOfUnlockedAccounts is the number of unlocked accounts on this node
(N) numberOfTransfers is the number of AE transfers in the blockchain
(N) numberOfOrders is the number of AE orders in the blockchain
(N) numberOfTransactions is the number of transactions in the blockchain
(N) maxMemory is the maximum amount of memory the node may use (in Bytes)
(B) isScanning is true if this node is scanning the blockchain, false otherwise
(S) cumulativeDifficulty is the current cumulative forging difficulty
(N) numberOfAssets is the number of AE assets in the blockchain
(N) freeMemory is the amount of free memory on this node (in Bytes)
(N) availableProcessors is the number of processors on this node
(N) totalEffectiveBalanceNxt is the total effective Balance of the network in BURST
(N) numberOfAccounts is the number of accounts in the blockchain
(N) numberOfBlocks is the number of blocks (height + 1) in the blockchain
(S) version is the software version on this node
(N) numberOfBidOrders is the number of AE bid orders in the blockchain
(S) lastBlock is the last block address
(N) totalMemory is the amount of memory this node is using (in Bytes)
(S) application is the name of the software running on this node (typically BRS)
(N) numberOfAliases is the number of aliases in the blockchain
(N) lastBlockchainFeederHeight is the height of the last blockchain feeder
(N) numberOfTrades is the number of AE trades in the blockchain
(N) time is the current node time (in seconds since the genesis block)
(N) numberOfAskOrders is the number of AE ask orders in the blockchain
(S) lastBlockchainFeeder is the announced name of the feeder of the last blockchain
(N) requestProcessingTime is the API request processing time (in millisec)

Note: AE is Asset Exchange, DGS is Digital Goods Store

Example: Refer to Get State example.

Get Time Verified.png Verified.png

Get the current time.

Request:
requestType is getTime

Response:

(N) time is the current node time (in seconds since the genesis block)
(N) requestProcessingTime is the API request processing time (in millisec)

Example: Refer to Get Time example.

Transaction Operations Verified.png

Broadcast Transaction Verified.png

Broadcast a transaction to the network. POST only.

Request:
requestType is broadcastTransaction
transactionBytes is the bytecode of a signed transaction (optional)
transactionJSON is the transaction object (optional if transactionBytes provided)

Response:

(N) requestProcessingTime is the API request processing time (in millisec)
(S) fullHash is the full hash of the signed transaction
(S) transaction is the transaction ID

Example: Refer to Broadcast Transaction example.

Calculate Full Hash Verified.png

Calculate the full hash of a transaction.

Request:
requestType is calculateFullHash
unsignedTransactionBytes is the unsigned bytes of a transaction (optional if unsignedTransactionJSON is provided)
signatureHash is the SHA-256 hash of the transaction signature

Response:

(N) requestProcessingTime is the API request processing time (in millisec)
(S) fullHash is the full hash of the signed transaction

Example: Refer to Calculate Full Hash example.

Get Transaction Verified.png

Get a transaction object given a transaction ID.

Request:
requestType is getTransaction
fullHash is the full hash of the transaction (optional if transaction ID is provided)

Response:

(S) senderPublicKey is the public key of the sending account for the transaction
(S) signature is the digital signature of the transaction
(S) feeNQT is the fee (in NQT) of the transaction
(N) requestProcessingTime is the API request processing time (in millisec)
(N) type is the transaction type (refer to Get Constants for a current list of types)
(N) confirmations is the number of transaction confirmations
(S) fullHash is the full hash of the signed transaction
(N) version is the transaction version number
(N) ecBlockId is the economic clustering block ID
(S) signatureHash is the SHA-256 hash of the transaction signature
(S) senderRS is the Reed-Solomon address of the sender
(N) subtype is the transaction subtype (refer to Get Constants for a current list of subtypes)
(S) amountNQT is the amount (in NQT) of the transaction
(S) sender is the account ID of the sender
(S) recipientRS is the Reed-Solomon address of the recipient, if applicable
(S) recipient is the account number of the recipient, if applicable
(N) ecBlockHeight is the economic clustering block height
(S) block is the ID of the block containing the transaction
(N) blockTimestamp is the timestamp (in seconds since the genesis block) of the block
(N) deadline is the deadline (in minutes) for the transaction to be confirmed
(N) timestamp is the time (in seconds since the genesis block) of the transaction
(N) height is the height of the block in the blockchain

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

Example: Refer to Get Transaction example.

Get Transaction Bytes Verified.png

Get the bytecode of a transaction.

Request:
requestType is getTransactionBytes
transaction is the transaction ID

Response:

(S) unsignedTransactionBytes is the unsigned bytes contained in the transaction
(N) requestProcessingTime is the API request processing time (in millisec)
(N) confirmations is the number of transaction confirmations
(S) transactionBytes is the bytes contained in the transaction

Example: Refer to Get Transaction Bytes example.

Parse Transaction Verified.png

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

Request:
requestType is parseTransaction
transactionBytes is the signed or unsigned bytecode of the transaction (optional)
transactionJSON is the transaction object (optional if transactionBytes is included)

Response: Refer to Get Transaction.

Example: Refer to Parse Transaction example.

Sign Transaction Verified.png

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

Request:
requestType is signTransaction
unsignedTransactionBytes is the unsignedTransactionBytes field of the transaction (optional, if unsignedTransactionJSON provided)
unsignedTransactionJSON is the transactionJSON field of the transaction, without a signature subfield
secretPhrase is the secret passphrase of the signing account

Response:

(S) signatureHash is the SHA-256 hash of the transaction signature, used in escrow transactions
(B) verify is true the signature is verified, false if not
(N) requestProcessingTime is the API request processing time (in millisec)
(S) transactionBytes is the the signed transaction bytes
(S) fullHash is the full hash of the signed transaction
(S) transaction is the transaction ID, derived from the fullHash

Example: Refer to Sign Transaction example.

Sign Escrow

Request:
requestType is escrowSign

Response: To do

Example: To do

Utilities Verified.png

Long Convert Verified.png

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

Request:
requestType is longConvert
id is the numerical ID, in decimal form but equivalent to an 8-byte unsigned integer as produced by SHA-256 hashing

Response:

(S) stringID is the numerical ID
(S) longID is the signed long integer (8-bytes) representation of the ID used internally, returned as a string
(N) requestProcessingTime is the API request processing time (in millisec)

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

Example: Refer to Long Convert example.

RS Convert Verified.png

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

Request:
requestType is rsConvert
account is the account ID (either RS address or number)

Response:

(S) accountRS is the Reed-Solomon address of the account
(N) requestProcessingTime is the API request processing time (in millisec)
(S) account is the account number

Example: Refer to RS Convert example.

Suggest Fee Verified.png

Get a cheap, standard, and priority fee.

Request:
requestType is suggestFee

Response:

(N) standard is the Standard fee
(N) requestProcessingTime is the API request processing time (in millisec)
(N) cheap is the Cheap fee. Your transaction may not be processed immediately
(N) priority is the Priority fee. Your transaction has high probability to be processed by the network.