MFT Blockchain Node API

Release 1.0

Introduction

The MFT Blockchain Node API provides access to the REST service as follows:

  • GET and DELETE parameters are part of the URL.
  • POST and PUT parameters are sent in the body as form-urlencoded.
  • The format of the response can be set by passing the "format" parameter as part of the request.
  • Supported response formats are presented along with the operation summary.
  • Errors are returned with HTTP status code of 400 (Bad Request), along with a plain-text error message in the response body.
  • Successful responses return an HTTP status code of 200 (OK), along with a object encoded in the selected format.
  • All hex-encoded string must be zero-padded to the left, so that the total length is as specified.
  • Base31/n identifiers are n-character strings from the alphabet consisting of all English consonants and digits 0-9.
  • Transaction IDs can either be Base31/8 or v4 UUID; however v4 UUID is highly recommended.
  • All signatures and hashes of responses are performed on a block formed by concatenating the values of the parameters, ordered corresponding to the property's name in ascending Unicode alphabetical order. For example, the signature of the output of /config would be performed on a block that results from concatenating the value of "apiurl", "basefee", "brokerid", "brokerkey", "daytime", "degree", "feeperc", "minversion", "pubkey" and "version".


/addressesGET

Get list of addresses

Get a list of addresses that have at least one transaction in the blockchain

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
offsetIntegerThe records offset, used for pagingYes
limitIntegerThe record limit, used for paging (if exceeds the value set in system.limit.rec.data, the value of system.limit.rec.data will be used)Yes

Output Parameters

FieldTypeDescription
responseSummariesA Summaries object
 hashStringThe SHA-256 hash of the concatenation of the individual hash of each summary, in the order they are returned..
 summariesListA list of Summary objects
  summarySummaryA Summary object
   addressStringThe address, which is the SHA-256 hash of its public key, encoded as a zero-padded hex string
   hashStringThe SHA-256 hash of the summary item.

Errors

CodeDescription

/apidocGET

Get the API documentation

Get the API documentation

Minimum seconds between requests: 0 Supported response formats: html

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription

Errors

CodeDescription

/apitestGET

Get API test web page

Get API test web page in HTML

Minimum seconds between requests: 0 Supported response formats: html

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription

Errors

CodeDescription

/apitestparamsGET

Get API test parameter inputs

Get API test parameter inputs in HTML

Minimum seconds between requests: 0 Supported response formats: html

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription

Errors

CodeDescription

/blockGET

Get block data

Get data from a block. If requested, may include the list of transactions.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
blocknumIntegerThe block number, or -1 to return the last block in the blockchain.No
blockidStringThe block's unique identifier. If not provided, the parameter "blocknum" will be used.No
includetxsBooleanIf true, include a list of the transactions of the block.Yes

Output Parameters

FieldTypeDescription
blockBlockA Block object
 blockidStringThe block's unique identifier (Base31/8)
 blocknumIntegerThe block number; its maximum value must be one increment over the last block in the blockchain.
 phashStringThe SHA-256 hash of the previous block in the chain, represented as a zero-padded, 64-byte hex string.
 txidsStringA comma-delimited list of IDs of the transactions in the block. The order of the transactions in the block is the order of the IDs in this list.
 solveridStringThe puzzle solver's ID, which is the SHA-256 hash of its public key.
 magicnumIntegerThe block's "magic number", which is the minimum positive integer that gives a zero-score starting puzzle.
 daytimeStringThe day/time of the block, in UTC. Encoded as a 16-byte hex string.
 hashStringThe SHA-256 hash of the block, as a function of the concatenation of the values of "blockid", "blocknum", "daytime", "magicnum", "phash", "solverid" and the individual hash values of the transactions referred by the "txid" field. Represented as a zero-padded, 64-byte hex string.
 puzzlestartStringThe starting puzzle, as a function of the hash value. Represented as a comma-delimited list of 24 tiles, where teach tile is a bit stream [b0..b7], as per the protocol specification.
 solutionStringThe puzzle solution, represented as a comma-delimited list of (row,column) integer pairs, where each pair are the zero-based row/column coordinates of the tile to move to the empty space of the puzzle.
 puzzlestopStringThe solved puzzle, which are the elements of "puzzlestart" after applying the solution. Represented as a comma-delimited list of 24 tiles, as per the protocol specification. The empty tile space is represented by an empty string (consecutive commas).
 puzzlescoreIntegerThe puzzle score, as a function of the number of matching tile sides, as per the protocol specification.
 nmovesIntegerThe number of moves made to solve the puzzle
 transactionsListA list of Transaction objects
  transactionTransactionA Transaction object
   txidStringThe transaction's unique identifier (v4 UUID)
   daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
   amountIntegerThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
   feeIntegerThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
   typeStringThe transaction type
   brokeridStringThe broker address, which is the SHA-256 of its public key
   senderidStringThe sender's address, which is the SHA-256 of its public key
   senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.
   receiveridStringThe receiver's address, which is the SHA-256 of its public key
   receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string
   rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed. Must be empty for other types of transactions.
   hashStringThe SHA-256 hash of the transaction
   signatureStringThe signature of the sender or the receiver (depending on the transaction type), as a function of the value of the "hash" field
   brokersigStringThe signature of the broker, as a function of the value of the "hash" field

Errors

CodeDescription

/blockPOST

Add a block to the blockchain

Add a block to the blockchain. If the request is valid, it will be broadcast to all nodes in the blockchain network. The requestor is responsible for verifying that the block was accepted by querying a majority of nodes in the network.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
blockidStringThe block's unique identifier (Base31/8)Yes
blocknumIntegerThe block number; if the last block in the chain was added less than 10 minutes before the current node time, this numbers should be the same as the number from the last block in the chain; otherwise it should be one more than the number from the last block in the chain.Yes
phashStringThe SHA-256 hash of the previous block in the chain, represented as a zero-padded, 64-byte hex string. For the first block, this value must be all-zeroes.Yes
txidsStringA comma-delimited list of transaction IDs to include in the block. All transactions must have been previously posted and not contained in any other block in the chain. The order of the transactions in the block is the order of the IDs in this list.Yes
solveridStringThe puzzle solver's ID, which is the SHA-256 hash of its public key. A transaction in the next block shall make the reward to this address.Yes
magicnumIntegerThe block's "magic number", which is the minimum positive integer that gives a zero-score starting puzzle.Yes
daytimeStringThe day/time of the block, in UTC. Encoded as a 16-byte hex string. The modulo-10 of this value divided by 60000 must be equal to zero (i.e. the number of minutes must be a multiple of 10) and not more than five minutes before this node's current day/time; otherwise the block will be rejected.Yes
hashStringThe SHA-256 hash of the block, as a function of the concatenation of the values of "blockid", "blocknum", "daytime", "magicnum", "phash", "solverid" and the individual hash values of the transactions referred by the "txid" field. Represented as a zero-padded, 64-byte hex string.Yes
puzzlestartStringThe starting puzzle, as a function of the hash value. Represented as a comma-delimited list of 24 tiles, where teach tile is a bit stream [b0..b7], as per the protocol specification.Yes
solutionStringThe puzzle solution, represented as a comma-delimited list of (row,column) integer pairs, where each pair are the zero-based row/column coordinates of the tile to move to the empty space of the puzzle.Yes
puzzlestopStringThe solved puzzle, which are the elements of "puzzlestart" after applying the solution. Represented as a comma-delimited list of 24 tiles, as per the protocol specification. The empty tile space is represented by an empty string (consecutive commas).Yes
puzzlescoreIntegerThe puzzle score, which is the number of matching tile sides, as per the protocol specification.Yes

Output Parameters

FieldTypeDescription

Errors

CodeDescription
duplicateIDDuplicate ID
blockNotFoundBlock not found
invalidBlockNumberInvalid block number
invalidPuzzleInvalid puzzle
invalidScoreInvalid solution score
invalidSolutionInvalid puzzle solution
invalidIDInvalid ID
invalidDayTimeInvalid day/time
invalidMagicNumberMagic number is not a minimum for the block hash
invalidHashInvalid hash
missingRewardTxReward transaction for previous block is missing

/broadcastPOST

Broadcast a request

Broadcast a request. Can only be used by nodes that are in the network; otherwise the request will be rejected.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
historyStringA comma-delimited list of addresses to which the message has been broadcast. The first address in the list is the address of the originator of the message. Used to avoid double-forwarding.Yes
reqtypeStringThe request type, either Transact or BlockYes
requestStringThe original URL-encoded request.No

Output Parameters

FieldTypeDescription

Errors

CodeDescription
notInNetworkRequesting node is not part of the network

/cdirGET

Get content directory

Get the content directory for a specific address

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
addressStringThe address to get the content for.Yes
pidStringThe content parent's unique identifier. Content items whose parent ID matches this parameter will be returned. If not provided, content items with no parent (typically belonging to the root) will be returned.No
cidStringThe content's unique identifier (v4 UUID). If provided, a single-item content directory list with the matching content will be returned.No
timelineBooleanIf true, all content and descendants from the parent "pid" will be returned, sorted by day/time in descending order; otherwise, only immediate descendants from the parent "pid" will be returned.No
claimedonlyBooleanIf true, only include content that has been claimed by the owner; otherwise all content will be included regardless of whether it has been claimed or not.No
pinnedBooleanIf "true", return only content that has been flagged as pinned.No
offsetIntegerThe records offset, used for pagingYes
limitIntegerThe record limit, used for paging (if exceeds the value set in system.limit.rec.data, the value of system.limit.rec.data will be used)Yes

Output Parameters

FieldTypeDescription
contentListContentListA ContentList object
 itemsListA list of content items
  itemContentOwnerA ContentOwner object
   cidStringThe content's unique identifier (v4 UUID)
   nameStringThe content's name, encrypted with the item's encryption key and encoded in Base64
   typeStringThe content's MIME type
   attrStringThe content's application-dependent attributes, encrypted with the item's encryption key and encoded in Base64
   gidStringThe content's group ID (v4 UUID)
   ekeyStringThe content's encryption key (v4 UUID) - only available for public content
   hashStringThe content SHA-256 hash. Typically used to verify content integrity after downloading.
   pidStringThe content parent's unique identifier (v4 UUID)
   claimedBooleanIf true, the content has been claimed by the owner after a transfer.
   pinnedBooleanIf true, the content has been flagged as pinned.
   daytimeStringThe day/time of the last modification of the content, encoded as a zero-padded hex string
 hashStringThe hash of the list, which is the hash of the concatenation of the hash value of each entry, in the order that they appear in the list.

Errors

CodeDescription

/chainGET

Get a portion of the blockchain

Get a portion of the blockchain. Returns a list of blocks as validated by this node. Clients are responsible for validating this chain by issuing this query to a majority of nodes in the network.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
blocknumIntegerThe starting block numberYes
limitIntegerThe number of blocks limit, used for paging (if exceeds the value set in system.limit.chain.data, the value of system.limit.chain.data will be used)Yes

Output Parameters

FieldTypeDescription
blocklistBlockchainA Blockchain object
 blocksListA list of Block objects
  blockBlockA Block object
   blockidStringThe block's unique identifier (Base31/8)
   blocknumIntegerThe block number; its maximum value must be one increment over the last block in the blockchain.
   phashStringThe SHA-256 hash of the previous block in the chain, represented as a zero-padded, 64-byte hex string.
   txidsStringA comma-delimited list of IDs of transactions in the block. The order of the transactions in the block is the order of the IDs in this list.
   solveridStringThe puzzle solver's ID, which is the SHA-256 hash of its public key.
   magicnumIntegerThe block's "magic number", which is the minimum positive integer that gives a zero-score starting puzzle.
   daytimeStringThe day/time of the block, in UTC. Encoded as a 16-byte hex string.
   hashStringThe SHA-256 hash of the block, as a function of the concatenation of the values of "blockid", "blocknum", "daytime", "magicnum", "phash", "solverid" and the individual hash values of the transactions referred by the "txid" field. Represented as a zero-padded, 64-byte hex string.
   puzzlestartStringThe starting puzzle, as a function of the hash value. Represented as a comma-delimited list of 24 tiles, where teach tile is a bit stream [b0..b7], as per the protocol specification.
   solutionStringThe puzzle solution, represented as a comma-delimited list of (row,column) integer pairs, where each pair are the zero-based row/column coordinates of the tile to move to the empty space of the puzzle.
   puzzlestopStringThe solved puzzle, which are the elements of "puzzlestart" after applying the solution. Represented as a comma-delimited list of 24 tiles, as per the protocol specification. The empty tile space is represented by an empty string (consecutive commas).
   puzzlescoreIntegerThe puzzle score, as a function of the number of matching tile sides, as per the protocol specification.

Errors

CodeDescription

/chistGET

Display transaction history of a content item

Display transaction history of a content item

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
cidStringThe content's unique identifier (v4 UUID)Yes
offsetIntegerThe records offset, used for pagingYes
limitIntegerThe record limit, used for paging (if exceeds the value set in system.limit.rec.data, the value of system.limit.rec.data will be used)Yes

Output Parameters

FieldTypeDescription
transactionsTransactionListA TransactionList object
 transactionsListA list of Transaction objects
  transactionTransactionA Transaction object
   txidStringThe transaction's unique identifier (v4 UUID)
   daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
   amountIntegerThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
   feeIntegerThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
   typeStringThe transaction type
   brokeridStringThe broker address, which is the SHA-256 of its public key
   brokerkeyStringThe public key of the broker, encoded as a 600-byte X.509 hex string.
   senderidStringThe sender's address, which is the SHA-256 of its public key
   senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.
   receiveridStringThe receiver's address, which is the SHA-256 of its public key
   receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string
   rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed.
   cdataStringThe contract data (if any), encoded in JSON
   hashStringThe SHA-256 hash of the transaction
   signatureStringThe signature of the sender or the receiver (depending on the transaction type), as a function of the value of the "hash" field
   brokersigStringThe signature of the broker, as a function of the value of the "hash" field
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the transactions as they are ordered in the list.

Errors

CodeDescription

/codeGET

Get latest version of code

Get latest version of code. Typicaly used by other nodes to upgrade the software to the latest version.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription
fileFileA binary zip file containing the code of the node's current version of the software.

Errors

CodeDescription

/configGET

Get node configuration

Get node configuration

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription
configurationNodeConfigurationA NodeConfiguration object.
 apiurlStringThe URL to access this node's API
 versionStringSoftware version number, in the format xx.yy, where - xx is the major version number - yy is the minor version number All version number components are zero-padded to the left.
 minversionStringThe minimum software version number for other nodes to be accepted into the network by this node.
 degreeIntegerThe broadcast degree, i.e. the number of nodes to which all broadcast messages will be forwarded.
 brokeridStringThe transaction broker's address, which is the SHA-256 hash of its public key. All fees processed by this node must be sent to this address.
 brokerkeyStringThe node broker address's public key, encoded as a 600-byte X.509 hex string
 feepercDoubleThe fee percentage charged by this node's broker. All transactions processed by this node should include a fee that is equal to the base fee plus this percentage multiplied by the transaction's amount, rounded to the nearest integer and sent to the broker's address identified by the element "brokerid".
 basefeeIntegerThe base fee charged by this node's broker. All transactions processed by this node should include a fee whose minimum is this fee amount. The fee may also include a percentage, as specified in the "feeperc" field.
 pubkeyStringThe node's public key, encoded as a 600-byte X.509 hex string
 burnListA list of "burn" addresses listed in this node. Burn addresses can only be transferred to but no transfers can go from them.
  summarySummaryA Summary object containing the burn address
   addressStringThe burn address
 daytimeStringThe node's current day/time in UTC. Encoded as a 16-byte hex string. The precision of this value must be +/-30 seconds within UTC; otherwise the node will not be allowed in the network.
 regtxidStringThe ID of the latest REG transaction ID issued for this node.
 signatureStringThe signature of the response, encoded as AAAA|hhhh, where AAAA is the name of the algorithm (as recognized by the package java.security) and hhhh is the binary value of the signature, encoded as a 512-byte hex string.

Errors

CodeDescription

/contentGET

Get content data

Get content data

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
cidStringThe content ID. If provided, a cursor ID and content length will be returned as a pipe (|) delimited line of text; otherwise the parameter "cursorid" must be provided.No
cursoridStringThe cursor ID. If provided, the next set of records for this cursor is returned. If omitted, a content ID must be provided.
NOTE: The maximum time between calls must not exceed the number of expiration seconds specified in the setting system.content.cursor.expseconds; otherwise the cursor will be invalidated.
No
limitIntegerThe maximum number of records to return. If this value exceeds the one specified by the setting system.content.cursor.limit, the value of the setting will be used instead.Yes

Output Parameters

FieldTypeDescription
contentListContentListA ContentList object
 blocksListA list of blocks that conform the content.
  blockContentBuferA ContentBuffer object
   blocknumIntegerThe block number (zero-based)
   phashStringThe hash of the previous block; for the first block, it is a hash of the concatenation of the content ID and the file key.
   cdataStringThe block data, encrypted with a secret key that must be known by the caller; and encoded in Base64.
   hashStringThe SHA-256 hash of the block, as a function of the concatenation of "cid", "blocknum", "cdata" and "phash".
 hashStringThe hash of the list, which is the hash of the concatenation of the hash value of each entry, in the order that they appear in the list.

Errors

CodeDescription
invalidIDInvalid ID

/contentPOST

Post content for minting

Post content for minting. Must be invoked prior to minting with a CCT (Content Create) transaction.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
cidStringThe content ID (v4 UUID). If the invocation is for the first block (blocknum=0), there must not exist any pending or validated transaction referencing this ID; otherwise an invalidID error will be returned.Yes
blocknumIntegerThe sequence number of the block, zero-based. A maximum of 32K blocks is allowed.Yes
phashStringThe SHA-256 hash of the previous block, encoded as a zero-padded 64-byte hex string. This value should be the hash of the concatenation of the "blocknum', "cdata" and "phash" values of the previous block.
For the first block, this value should be the hash of the concatenation of "cid" and a random v4 UUID used as the "ckey" (content key) value of the CCT transaction; if the "ckey" value of the CCT transaction does not produce this hash value, the transaction will be rejected.
Yes
cdataStringThe content data for the block, encrypted with a private key hash and encoded in Base64. The size of the block (after decoding) shall not exceed 32K.Yes
hashStringThe SHA-256 hash of the block, as a function of the concatenation of "cid", "blocknum", "cdata" and "phash".Yes

Output Parameters

FieldTypeDescription

Errors

CodeDescription
invalidBlockNumberInvalid block number
invalidIDInvalid ID
invalidHashInvalid hash
bufferOverflowBuffer overflow
invalidContentInvalid content

/dataGET

Get full or partial data records of a database table

Get full or partial data records of a database table.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
daytimeStringThe starting day/time of the records to be retrieved, encoded as a 16-byte hex string. All records whose day/time is greater or equal than this parameter are included. Should be zero (0) to get all records.Yes
tableStringThe name of the database table from which records are to be retrieved.Yes
offsetIntegerThe records offset, used for pagingYes
limitIntegerThe record limit, used for paging (if exceeds the value set in system.limit.rec.data, the value of system.limit.rec.data will be used)Yes

Output Parameters

FieldTypeDescription
fileFileA binary stream with SQL insert statements corresponding to the data being retrieved.

Errors

CodeDescription

/dumpGET

Dump the configuration tables

Dump the configuration tables. Typically used by nodes to obtain the latest configuration prior to joining the network

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription
fileFileThe SQL script file

Errors

CodeDescription

/joinPOST

Join the network

Join the blockchain nodes network. The requestor is responsible of joining the network by issuing this request to all nodes in the network.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
apiurlStringThe requesting node's API URL. This API will be invoked by all nodes in the network to qualify the node before admitting it to the network.Yes

Output Parameters

FieldTypeDescription
addressStringThe node's IP address

Errors

CodeDescription
requestDeniedRequest denied

/keypairGET

Get an importable broker key pair

Get an importable representation of this node's broker private/public key pair

Minimum seconds between requests: 0 Supported response formats: text

Input Parameters

FieldTypeDescriptionRequired
appkeyStringThe application keyYes

Output Parameters

FieldTypeDescription

Errors

CodeDescription
unauthorizedUnauthorized requestor

/namGET

Get a name-address mapping

Get a name-address mapping by returning an address mapped from a name

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
nameStringThe name to map, in the format [ <name> ] @ <base-name> where:
<name> is an optional name
<base-name> is the base name owned by a Name Service Provider
Yes

Output Parameters

FieldTypeDescription
namNAMA NAM Object
 nameStringThe name being mapped; this value is the same at the input parameter.
 addressStringThe address mapped to
 daytimeStringThe UCT day/time of the last update, represented as a zero-added, 16-byte hex string.
 hashStringThe SHA-256 hash of the response, as a function of "address", "daytime" and "name"

Errors

CodeDescription
objectNotFoundThe requested object was not found in the database.

/nodesGET

Get list of nodes in the blockchain network

Get list of nodes in the blockchain network, sorted by hit rate in descending order.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
regonlyBooleanIf true, only include registered nodes in the result; results are sorted by IP address is ascending order.No

Output Parameters

FieldTypeDescription
nodesNodeListA NodeList object
 nodesListA list of Node objects
  nodeNodeA Node object
   addressStringThe IPv4 address of the node. This is the node's unique identifier.
   hitrateIntegerThe node's hit rate, which is an integer number between 1024 and -1024.
   apiurlStringThe node's API URL
   versionStringThe node's software version number
   minversionStringThe node's minimum software version acceptance
   degreeIntegerThe node's broadcast degree (i.e. the number of nodes to which message will be broadcast)
   brokeridStringThe transaction broker's address, which is the SHA-256 hash of its public key. All fees processed by this node must be sent to this address.
   brokerkeyStringThe node broker address's public key, encoded as a 600-byte X.509 hex string
   regtxidStringThe ID of the latest REG transaction ID issued for this node
   pubkeyStringThe public key of the node, encoded as a 600-byte X.509 hex string.
   hashStringThe SHA-256 hash of the node, as a function of the concatenation of its attribute values.
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the nodes as they are ordered in the list.

Errors

CodeDescription

/nspsGET

Get list of Name Service Providers (NSPs)

Get list of Name Service Providers (NSPs)

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
nameStringIf provided, only an NSP that matches this name will be returned.No

Output Parameters

FieldTypeDescription
nspListNSPListA NSPList object
 providersListA list of NSP objects
  nspNSPAn NSP object
   nameStringThe name reserved by the NSP
   ownernameStringThe name of the NSP
   urlStringThe website URL of the NSP
   logourlStringThe URL of the NSP's logo
   webhooksWebHooksA WebHooks object
    namStringThe URL of the web hook used to register a Name-Address Mapping (NAM) with the NSP
    idvStringThe URL of the web hook used to query a Identity Verification (IDV) from the NSP
   daytimeStringThe day/time of the last registration, encoded as a zero-padded hex string
   expiredBooleanIf true, the NSP registration has expired
   addressStringThe NSP owner's address
   hashStringThe SHA-256 hash of the NSP object
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the transactions as they are ordered in the list.

Errors

CodeDescription

/pendingGET

Get list of pending transactions

Get a list of qualified, pending transactions, which are recent transactions that are either (i) not present in any block; or (ii) not present in a specific blockchain. Typically used by clients to build a new transaction block to be added to the blockchain.
A transaction is considered qualified if it satisfies all the conditions to be part of the blockchain to which the block identified by "blockid" belongs.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
blockidStringThe ID of the last block in the chain that is being considered for including the transactions. Any transactions in this chain won't be included in the results. Leave blank to include transactions that do not belong to any chain.Yes
addressStringThe address (SHA-256 hash of the address's public key) for which recent transactions are to be obtained. To get transactions for all addresses, leave blank. If this parameter is provided, the parameter blockid is ignored and the latest block in the node's blockchain will be used.Yes

Output Parameters

FieldTypeDescription
transactionsTransactionListA TransactionList object
 transactionsListA list of Transaction objects
  transactionTransactionA Transaction object
   txidStringThe transaction's unique identifier (v4 UUID)
   daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
   amountIntegerThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
   feeIntegerThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
   typeStringThe transaction type
   brokeridStringThe broker address, which is the SHA-256 of its public key
   brokerkeyStringThe public key of the broker, encoded as a 600-byte X.509 hex string.
   senderidStringThe sender's address, which is the SHA-256 of its public key
   senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.
   receiveridStringThe receiver's address, which is the SHA-256 of its public key
   receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string
   rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed.
   hashStringThe SHA-256 hash of the transaction
   signatureStringThe signature of the sender or the receiver (depending on the transaction type), as a function of the value of the "hash" field
   brokersigStringThe signature of the broker, as a function of the value of the "hash" field
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the transactions as they are ordered in the list.

Errors

CodeDescription

/puzzleGET

Generate a puzzle

Generate a puzzle with a random solution. Typically used by nodes in the network to attempt a machine-based validation that may be successful if no human validation is submitted. Only available to authorized IP addresses.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
blockidStringThe block's unique identifier (Base31/8)Yes
blocknumIntegerThe block number; its maximum value must be one increment over the last block in the blockchain.Yes
phashStringThe SHA-256 hash of the previous block in the chain, represented as a zero-padded, 64-byte hex string. For the first block, this value must be all-zeroes.Yes
txidsStringA comma-delimited list of transaction IDs to include in the block. All transactions must be in the node's pending queue. The order of the transactions in the block is the order of the IDs in this list.Yes
solveridStringThe puzzle solver's ID, which is the SHA-256 hash of its public key.Yes
daytimeStringThe day/time of the block, in UTC. Encoded as a 16-byte hex string. This value must be greater than the day/time of the last transaction in the block, less than the node's current day/time and not older than 10 minutes from this node's current day/time; otherwise the block will be rejected.Yes
donotsolveBooleanDo not solve the puzzle. Optional- defaults to false.
When true, the puzzle is not solved; this is typically used to create a puzzle for a human to solve.
No

Output Parameters

FieldTypeDescription
blockBlockA Block object with a generated puzzle
 blockidStringThe block's unique identifier (Base31/8)
 blocknumIntegerThe block number; its maximum value must be one increment over the last block in the blockchain.
 phashStringThe SHA-256 hash of the previous block in the chain, represented as a zero-padded, 64-byte hex string. For the first block, this value must be all-zeroes.
 txidsStringA comma-delimited list of transaction IDs to include in the block. All transactions must be in the node's pending queue. The order of the transactions in the block is the order of the IDs in this list.
 solveridStringThe puzzle solver's ID, which is the SHA-256 hash of its public key.
 magicnumIntegerThe block's "magic number", which is the minimum positive integer that gives a zero-score starting puzzle.
 daytimeStringThe day/time of the block, in UTC. Encoded as a 16-byte hex string. This value must be greater than the day/time of the last transaction in the block, less than the node's current day/time and not older than 10 minutes from this node's current day/time; otherwise the block will be rejected.
 hashStringThe SHA-256 hash of the block, as a function of the concatenation of the values of "blockid", "blocknum", "daytime", "magicnum", "phash", "solverid" and the individual hash values of the transactions referred by the "txid" field. Represented as a zero-padded, 64-byte hex string.
 puzzlestartStringThe starting puzzle, as a function of the hash value. Represented as a comma-delimited list of 24 tiles, where teach tile is a bit stream [b0..b7], as per the protocol specification.
 solutionStringA random puzzle solution, represented as a comma-delimited list of (row,column) integer pairs, where each pair are the zero-based row/column coordinates of the tile to move to the empty space of the puzzle.
 puzzlestopStringA randomly-solved puzzle, which are the elements of "puzzlestart" after applying the random solution. Represented as a comma-delimited list of 24 tiles, as per the protocol specification. The empty tile space is represented by an empty string (consecutive commas).
 puzzlescoreIntegerThe puzzle score, as a function of the number of matching tile sides, as per the protocol specification.

Errors

CodeDescription
objectNotFoundThe requested object was not found in the database.

/queryGET

Process a distributed query

Process a distributed query among nodes in the network. Only available to authorized IP addresses.
The only required parameters are the type of query and the response format, given in the "type" and "format" parameters, respectively; other parameters depend on the type of query.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
typeStringThe type of query. Current supported query types are: "/pending", "/block" and "/transacts"Yes
formatStringThe format of the response, as specified by the requested operation typeYes

Output Parameters

FieldTypeDescription
responseStringThe response string, encoded in the format specified by the "format" parameter.

Errors

CodeDescription
unauthorizedUnauthorized requestor

/schemaGET

Get the SQL schema for data tables

Get the schema for data tables as a SQL script file.
Warning:The script contains commands to drop tables; running them against an existing database will erase the contents of such tables.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription
fileFileThe SQL script for schema creation.

Errors

CodeDescription

/statementGET

Get list of transactions for an address

Get list of pending, accepted and validated transactions for an address

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
addressStringThe address for which the transactions will be returnedYes
statusStringThe status of the last transaction returned in the last call. Used to determine whether to retrieve more pending transactions (always returned first) or non-pending.Yes
offsetIntegerThe records offset, used for pagingYes
limitIntegerThe record limit, used for paging (if exceeds the value set in system.limit.rec.data, the value of system.limit.rec.data will be used)Yes

Output Parameters

FieldTypeDescription
transactionsTransactionListA TransactionList object
 transactionsListA list of Transaction objects
  transactionTransactionA Transaction object
   txidStringThe transaction's unique identifier (v4 UUID)
   daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
   amountIntegerThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
   feeIntegerThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
   typeStringThe transaction type
   brokeridStringThe broker address, which is the SHA-256 of its public key
   senderidStringThe sender's address, which is the SHA-256 of its public key
   receiveridStringThe receiver's address, which is the SHA-256 of its public key
   hashStringThe SHA-256 hash of the transaction
   statusStringThe status of the transaction, which can be either: (P)ending, (A)ccepted in a block or (V)alidated
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the transactions as they are ordered in the list.

Errors

CodeDescription

/summariesGET

Get list of address summaries

Get list of address summaries. Typically used by clients to display addresses with summaries.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
addressesStringA comma-delimited list of addresses. Each address is the zero-padded, hex-encoded SHA-256 hash of its public key (after encoding it in zero-padded hex)Yes
bdaytimeStringThe day/time of the beginning of the summary in UTC, encoded as a 16-byte hex string. If provided, only transactions that fall in the range (bdaytime,edaytime) will be included.No
edaytimeStringThe day/time of the ending of the summary in UTC, encoded as a 16-byte hex string. If provided, only transactions that fall in the range (bdaytime,edaytime) will be included.No
txtypeStringThe transaction type to include in the summary. If omitted, all transaction types will be included.No

Output Parameters

FieldTypeDescription
responseSummariesA Summaries object
 hashStringThe SHA-256 hash of the concatenation of the individual hash of each summary, in the order they are returned..
 summariesListA list of Summary objects
  summarySummaryA Summary object
   addressStringThe address, which is the SHA-256 hash of its public key, encoded as a zero-padded hex string
   balanceLongThe validated balance of the address, which is the net sum of all confirmed transactions. A transaction is confirmed if it has been validated at least six blocks earlier. The value of this amount in MFT is 1/1000000 of this value.
   availableLongThe available balance, which is the balance minus all non-confirmed and pending debit transactions. The value of this amount in MFT is 1/1000000 of this value.
   scoreIntegerThe total accumulated mining score
   hashStringThe SHA-256 hash of the summary item.

Errors

CodeDescription

/transactGET

Get transaction data

Get transaction data. Typically used by clients to verify that a transaction was accepted by a node.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
txidStringThe transaction ID (v4 UUID)Yes

Output Parameters

FieldTypeDescription
transactionTransactionA Transaction object
 txidStringThe transaction's unique identifier (v4 UUID)
 daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
 amountLongThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
 feeLongThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
 typeStringThe transaction type
 brokeridStringThe node's broker unique identifier, which is the SHA-256 hash of the broker's public key, encoded as a 64-byte hex string.
 brokerkeyStringThe broker address's public key, encoded as a 600-byte X.509 hex string.
 senderidStringThe sender's unique identifier, which is the SHA-256 hash of the sender's public key, encoded as a 64-byte hex string.
 senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.
 receiveridStringThe receiver's unique identifier, which is the SHA-256 hash of the receiver's public key, encoded as a 64-byte hex string.
 receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string
 rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed. Must be empty for other types of transactions.
 cdataStringThe contract data (if any), encoded in JSON
 hashStringThe SHA-256 hash of the transaction
 signatureStringThe signature of the sender or the receiver (depending on the transaction type), as a function of the value of the "hash" field
 brokersigStringThe signature of the broker, as a function of the value of the "hash" field
 statusStringThe status of the transaction, which can be either: (P)ending, (A)ccepted in a block or (V)alidated

Errors

CodeDescription
objectNotFoundThe requested object was not found in the database.

/transactPOST

Add a transaction

Add a transaction to the pending queue. If the request is valid, it will be broadcast to all nodes in the blockchain network. The requestor is responsible for verifying that the transaction was accepted by querying a majority of nodes in the network.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
txidStringThe transaction's unique identifier (v4 UUID). No other transaction can have this ID, otherwise the request will not be broadcast and the transaction will not be added to the pending queue.Yes
daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string. Cannot be later than 30 seconds after this node's current day/time.Yes
amountLongThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.Yes
feeLongThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.Yes
typeStringThe transaction type, which could be either:
XFR - Transfer currency from one address to another
RWD - Block validation reward
Yes
brokeridStringThis node's broker unique identifier, which is the SHA-256 hash of the broker's public key, encoded as a 64-byte hex string. Must match value of "brokerid" from this node. Once the transaction is validated, the broker's fee is added to this address.Yes
brokerkeyStringThe public key of the processing node broker's address, encoded as a 600-byte X.509 hex string.Yes
senderidStringThe sender's unique identifier, which is the SHA-256 hash of the sender's public key, encoded as a 64-byte hex string.Yes
senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.Yes
receiveridStringThe receiver's unique identifier, which is the SHA-256 hash of the receiver's public key, encoded as a 64-byte hex string.Yes
receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string.Yes
rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed. The value of "receiverid" of this transaction must match value the block's "solverid", which is the solver's public key hash. Must be empty for other types of transactions.Yes
cdataStringThe contract data (if any), encoded in JSONNo
hashStringThe SHA-256 hash of the transaction, as a function of the concatenation of the values of the following fields, in the following order: amount, brokerid, brokerkey, daytime, fee, receiverid, receiverkey, rewardforid, senderid, senderkey, txid, type. Represented as a zero-padded, 64-byte hex string.Yes
signatureStringThe signature of the sender or receiver, depending on the type of transaction. The signature is a function of the value of the "hash" field. Encoded as AAAA|hhhh, where AAAA is the name of the algorithm (as recognized by the package java.security) and hhhh is the binary value of the signature, encoded as a 512-byte hex string.Yes
brokersigStringThe signature of the broker, as a function of the value of the "hash" field. Encoded as AAAA|hhhh, where AAAA is the name of the algorithm (as recognized by the package java.security) and hhhh is the binary value of the signature, encoded as a 512-byte hex string.Yes

Output Parameters

FieldTypeDescription

Errors

CodeDescription
duplicateIDDuplicate ID
invalidKeyInvalid key
transactionDeniedTransaction denied
invalidIDInvalid ID
invalidTypeInvalid type

/transactsGET

Get a list of transactions from a list of transaction IDs

Get a list of transactions from a list of transaction IDs. Transactions in the response are ordered by their timestamp ("daytime") in ascending order; and then by transaction ID.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
txidsStringA comma-delimited list of transactions IDs. All transactions whose ID is in this list will be included in the result.Yes

Output Parameters

FieldTypeDescription
transactionsTransactionListA TransactionList object
 transactionsListA list of Transaction objects
  transactionTransactionA Transaction object
   txidStringThe transaction's unique identifier (v4 UUID)
   daytimeStringThe transaction day/time in UTC, encoded as a 16-byte hex string.
   amountIntegerThe amount of the transaction. The value of the amount in MFT is 1/1000000 of this value.
   feeIntegerThe fee to be paid to the broker. This value of the fee in MFT is 1/1000000 of this value.
   typeStringThe transaction type
   brokeridStringThe broker address, which is the SHA-256 of its public key
   brokerkeyStringThe public key of the broker, encoded as a 600-byte X.509 hex string.
   senderidStringThe sender's address, which is the SHA-256 of its public key
   senderkeyStringThe public key of the sender , encoded as a 600-byte X.509 hex string.
   receiveridStringThe receiver's address, which is the SHA-256 of its public key
   receiverkeyStringThe public key of the receiver, encoded as a 600-byte X.509 hex string
   rewardforidStringFor transactions of type RWD, the ID of the block for which a reward is being claimed.
   cdataStringThe contract data (if any), encoded in JSON
   hashStringThe SHA-256 hash of the transaction
   signatureStringThe signature of the sender or the receiver (depending on the transaction type), as a function of the value of the "hash" field
   brokersigStringThe signature of the broker, as a function of the value of the "hash" field
 hashStringThe SHA-256 of the response, which is the hash of the concatenated hashes of all the transactions as they are ordered in the list.

Errors

CodeDescription

/updatePOST

Update data from another node

Update the data from another node. Can only be invoked by authorized IP addresses.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
appkeyStringThe application keyYes
apiurlStringThe API URL of the node from which the update will be performed.Yes

Output Parameters

FieldTypeDescription

Errors

CodeDescription

/upgradeGET

Get installation script

Get an installation script. Typically used during initial configuration of a broker node.

Minimum seconds between requests: 0 Supported response formats: text

Input Parameters

FieldTypeDescriptionRequired

Output Parameters

FieldTypeDescription

Errors

CodeDescription

/upgradePOST

Upgrade software from another node

Upgrade the software from another node. Can only be invoked by authorized IP addresses. Upon a successful upgrade, the node's server will be rebooted.

Minimum seconds between requests: 0 Supported response formats: xml,json

Input Parameters

FieldTypeDescriptionRequired
appkeyStringThe application keyYes
apiurlStringThe API URL of the node from which the upgrade will be performed.Yes

Output Parameters

FieldTypeDescription

Errors

CodeDescription