Controlling MultiChain from the command line or your application

Note: This page has been updated for MultiChain 2.0 – documentation for the MultiChain 1.0 API is still available.

Accessing the API

To access MultiChain’s API, use the included multichain-cli command-line tool or any other JSON-RPC client with basic access authentication. (MultiChain is compatible with any API library developed for Bitcoin Core.)

The API credentials for each blockchain are stored in the ~/.multichain/[chain-name]/multichain.conf file and read by multichain-cli. These credentials are randomly generated the first time that multichaind is called for that chain. (Note that you can change this ~/.multichain/ path using the -datadir= option, and %APPDATA%\MultiChain\ is the equivalent on Windows.)

You can use multichain-cli to send a single API command in the following form:

multichain-cli [chain-name] [command] [parameters...]

Alternatively, on Linux you can use multichain-cli in interactive mode, to send multiple commands in a single session:

multichain-cli [chain-name]

Each command is then entered in the [command] [parameters...] form. To end the session, type bye, exit, quit or Control-D.

List of API commands by category – view alphabetically

All optional parameters below are denoted in (round brackets) with non-empty default values indicated after the = symbol. Any commands, parameters and functionality which require MultiChain Enterprise are highlighted like this. See also the list of error codes and messages.

General utilities
Command Parameters Description
getblockchainparams (display-names=true)
(with-upgrades=true)
Returns a list of values of this blockchain’s parameters. Use display-names to set whether parameters are shown with display names (with hyphens) or canonical names (without hyphens). Use with-upgrades to set whether to show the chain’s latest parameters (after any upgrades) or its original parameters (in the genesis block). Note that as of MultiChain 1.0.1, only the protocol version can be upgraded.
getruntimeparams Returns a selection of this node’s runtime parameters, which are set when the node starts up. Some parameters can be modified while MultiChain is running using setruntimeparam.
setruntimeparam param value Sets the runtime parameter param to value and immediately applies the change. Currently supported parameters: acceptfiltertimeout autosubscribe bantx handshakelocal hideknownopdrops lockadminminerounds lockblock lockinlinemetadata maxshowndata maxqueryscanitems mineemptyrounds miningrequirespeers miningturnover sendfiltertimeout. From MultiChain 2.0.2, use the storeruntimeparams runtime parameter to persistently store these changes for future launches of MultiChain.
getinfo Returns general information about this node and blockchain. MultiChain adds some fields to Bitcoin Core’s response, giving the blockchain’s chainname, description, protocol, peer-to-peer port. There are also incomingpaused and miningpaused fields – see the pause command. The burnaddress is an address with no known private key, to which assets can be sent to make them provably unspendable. The nodeaddress can be passed to other nodes for connecting. The setupblocks field gives the length in blocks of the setup phase in which some consensus constraints are not applied.
help Returns a list of available API commands, including MultiChain-specific commands.
stop Shuts down the this blockchain node, i.e. stops the multichaind process.
Managing wallet addresses
addmultisigaddress nrequired ["key", ...] Creates a pay-to-scripthash (P2SH) multisig address and adds it to the wallet. Funds sent to this address can only be spent by transactions signed by nrequired of the specified keys. Each key can be a full public key, or an address if the corresponding key is in the node’s wallet. (Public keys for a wallet’s addresses can be obtained using the getaddresses call with verbose=true.) Returns the P2SH address.
getaddresses (verbose=false) Returns a list of addresses in this node’s wallet. Set verbose to true to get more information about each address, formatted like the output of the validateaddress command. For more control see the new listaddresses command.
getnewaddress Returns a new address whose private key is added to the wallet.
importaddress address(es) (label)
(rescan=true)
Adds address (or an array of addresses) to the wallet, without an associated private key. This creates one or more watch-only addresses, whose activity and balance can be retrieved via various APIs (e.g. with the includeWatchOnly parameter), but whose funds cannot be spent by this node. The rescan parameter controls whether and how the blockchain is rescanned for transactions relating to all wallet addresses, including these new ones. Pass true to rescan the entire chain, false to skip rescanning, and from version 1.0.5, a positive integer to rescan from that block number or a negative integer to rescan that many recent blocks. Returns null if successful.
listaddresses (addresses=*) (verbose=false)
(count=MAX) (start=-count)
Returns information about the addresses in the wallet. Provide one or more addresses (comma-delimited or as an array) to retrieve information about specific addresses only, or use * for all addresses in the wallet. Use count and start to retrieve part of the list only, with negative start values (like the default) indicating the most recently created addresses.
Working with non-wallet addresses
createkeypairs (count=1) Generates one or more public/private key pairs, which are not stored in the wallet or drawn from the node’s key pool, ready for external key management. For each key pair, the address, pubkey (as embedded in transaction inputs) and privkey (used for signatures) is provided.
createmultisig nrequired
["key", ...]
Creates a pay-to-scripthash (P2SH) multisig address. Funds sent to this address can only be spent by transactions signed by nrequired of the specified keys. Each key can be a full hexadecimal public key, or an address if the corresponding key is in the node’s wallet. Returns an object containing the P2SH address and corresponding redeem script.
validateaddress address|
privkey|pubkey
Returns information about address, or the address corresponding to the specified privkey private key or pubkey public key, including whether this node has the address’s private key in its wallet.
Permissions management
grant addresses permissions
(native-amount=0)
(start-block) (end-block)
(comment) (comment-to)
Grants permissions to addresses, a comma-separated list of addresses. For global permissions, set permissions to one of connect, send, receive, create, issue, mine, activate, admin, or a comma-separated list thereof. For per-asset or per-stream permissions, use the form asset.issue,send,receive,activate,admin or stream.write,read,activate,admin where asset or stream is an asset or stream name, ref or creation txid. (Each grant command can only assign global permissions, or permissions for a single asset or stream.) If the chain uses a native currency, you can send some to each recipient using the native-amount parameter. Returns the txid of the grant transaction sent. For more information, see permissions management.
grantfrom from-address to-addresses
permissions (native-amount=0)
(start-block) (end-block)
(comment) (comment-to)
This works like grant, but with control over the from-address used to grant the permissions. It is useful if the node has multiple addresses with the required permissions.
grantwithdata addresses permissions
metadata (native-amount=0)
(start-block) (end-block)
This works like grant, but adds an additional transaction output containing metadata specified in one of these forms.
grantwithdatafrom from-address to-addresses
permissions metadata
(native-amount=0)
(start-block) (end-block)
This works like grantwithdata, but with control over the from-address used to grant the permissions.
listpermissions (permissions=*)
(addresses=*)
(verbose=false)
Returns a list of all permissions which have been explicitly granted to addresses. To list information about specific global permissions, set permissions to one of connect, send, receive, issue, mine, activate, admin, or a comma-separated list thereof. Omit or pass * or all to list all global permissions. For per-asset or per-stream permissions, use the form asset.issue,send,receive,activate,admin, stream.write,read,activate,admin or entity.* where asset, stream or entity is an asset or stream name, ref or creation txid. Provide a comma-delimited list in addresses to list the permissions for particular addresses or * for all addresses. If verbose is true, the admins output field lists the administrator/s who assigned the corresponding permission, and the pending field lists permission changes which are waiting to reach consensus.
revoke addresses permissions
(native-amount=0)
(comment) (comment-to)
Revokes permissions from addresses, a comma-separated list of addresses. The permissions parameter works the same as for grant. This is equivalent to calling grant with start-block=0 and end-block=0. Returns the txid of transaction revoking the permissions. For more information, see permissions management.
revokefrom from-address to-addresses
permissions (native-amount=0)
(comment) (comment-to)
This works like revoke, but with control over the from-address used to revoke the permissions. It is useful if the node has multiple addresses with administrator permissions.
verifypermission address
permission
Checks whether the specified address has the specified permission, returning true or false as appropriate. Global permissions such as connect as well as per-asset or per-stream permissions such as stream1.write can be checked. Unlike listpermissions, this includes implicit permissions, e.g. even if an address has admin permissions only, this will return true for send permissions. This can also be used as a Smart Filter callback and provides less information than listpermissions.
Asset management
getassetinfo asset
(verbose=false)
Returns information about a single asset issued on the blockchain, where asset is the asset name, ref or issuance txid. In assets with multiple issuance events, the top-level issuetxid and details fields refer to the first issuance only – set verbose to true for details about each of the individual issuances. This command can also be used as a Smart Filter callback and so excludes the node-specific information provided by listassets.
issue address name|params
qty (units=1)
(native-amount=min-per-output)
(custom-fields)
Creates a new asset on the blockchain, sending the initial qty units to address. To create an asset with the default behavior, use an asset name only for name|params. For more control, use an object such as {"name":"asset1","open":true,"restrict":"send"}. If this object contains "open":true, then additional units of the asset can be issued via the issuemore(from) command in future. If this object contains "restrict":"send", "restrict":"receive" or "restrict":"send,receive", then the asset will have per-asset send and/or receive permissions. The smallest transactable unit is given by units, e.g. 0.01. If the chain uses a native currency, you can send some with the new asset using the native-amount parameter. Pass a JSON object in the optional custom-fields parameter to provide extra information about the asset. Returns the txid of the issuance transaction. For more information, see native assets.
issuefrom from-address to-address
name|params qty (units=1)
(native-amount=min-per-output)
(custom-fields)
This works like issue, but with control over the from-address used to issue the asset. It is useful if the node has multiple addresses with issue permissions.
issuemore address asset qty
(native-amount=min-per-output)
(custom-fields)
Issues qty additional units of asset, sending them to address. This can only be done if the asset was issued open and by an address with per-asset issue permissions (by default, the original issuer). The asset can be specified using its name, ref or issuance txid – see native assets for more information. If the chain uses a native currency, you can send some with the new asset units using the native-amount parameter. Pass a JSON object in the optional custom-fields parameter to provide extra information about the issuance event – this will not affect the original values (use listassets with verbose=true to see both sets). Returns the txid of the issuance transaction.
issuemorefrom from-address to-address
asset qty
(native-amount=min-per-output)
(custom-fields)
This works like issuemore, but with control over the from-address used.
listassets (assets=*) (verbose=false)
(count=MAX) (start=-count)
Returns information about assets issued on the blockchain. Pass an asset name, ref or issuance txid in assets to retrieve information about one asset only, an array thereof for multiple assets, or * for all assets. In assets with multiple issuance events, the top-level issuetxid and details fields refer to the first issuance only – set verbose to true for details about each of the individual issuances. Use count and start to retrieve part of the list only, with negative start values (like the default) indicating the most recently created assets. Extra fields are shown for assets to which this node is subscribed.
Querying wallet balances and transactions

getaddressbalances address (minconf=1)
(includeLocked=false)
Returns a list of all the asset balances for address in this node’s wallet, with at least minconf confirmations. Use includeLocked to include unspent outputs which have been locked, e.g. by a call to preparelockunspent.
getaddresstransaction address txid
(verbose=false)
Provides information about transaction txid related to address in this node’s wallet, including how it affected that address’s balance. Use verbose to provide details of transaction inputs and outputs.
getmultibalances (addresses=*)
(assets=*)
(minconf=1)
(includeWatchOnly=false)
(includeLocked=false)
Returns a list of balances of the addresses in this node’s wallet for the specified assets, with at least minconf confirmations. The addresses are specified as a comma-delimited list or array, or * for all addresses with non-zero balances. The assets are specified as an array of asset names, refs or issuance txids, or * for all assets with non-zero balances. Use includeWatchOnly to include watch-only addresses (only relevant if addresses=*) and includeLocked to include unspent outputs which have been locked, e.g. by a call to preparelockunspent. The response includes a total of the balances shown.
gettotalbalances (minconf=1)
(includeWatchOnly=false)
(includeLocked=false)
Returns a list of all the asset balances in this node’s wallet, with at least minconf confirmations. Use includeWatchOnly to include the balance of watch-only addresses and includeLocked to include unspent outputs which have been locked, e.g. by a call to preparelockunspent.
getwallettransaction txid
(includeWatchOnly=false)
(verbose=false)
Provides information about transaction txid in this node’s wallet, including how it affected the node’s total balance. Use includeWatchOnly to consider watch-only addresses as if they belong to this wallet and verbose to provide details of transaction inputs and outputs.
listaddresstransactions address
(count=10) (skip=0)
(verbose=false)
Lists information about the count most recent transactions related to address in this node’s wallet, including how they affected that address’s balance. Use skip to go back further in history and verbose to provide details of transaction inputs and outputs.
listwallettransactions (count=10) (skip=0)
(includeWatchOnly=false)
(verbose=false)
Lists information about the count most recent transactions in this node’s wallet, including how they affected the node’s total balance. Use skip to go back further in history and includeWatchOnly to consider watch-only addresses as if they belong to this wallet. Use verbose to provide the details of transaction inputs and outputs. Note that unlike Bitcoin Core’s listtransactions command, the response contains one element per transaction, rather than one per transaction output.
Sending one-way payments
send address amounts
(comment)
(comment-to)
Sends a payment to address, returning the txid. The amounts field can specify a quantity of the native blockchain currency, some asset(s) and/or inline metadata, using one of these forms. See also sendasset for sending a single asset and sendfrom to control the address whose funds are used.
sendasset address asset qty
(native-amount=min-per-output)
(comment) (comment-to)
Sends qty of asset to address, returning the txid. The asset can be specified using its name, ref or issuance txid – see native assets for more information. See also sendassetfrom to control the address whose funds are used, send for sending multiple assets in one transaction, and sendfrom to combine both of these.
sendassetfrom from-address to-address
asset qty
(native-amount=min-per-output)
(comment) (comment-to)
This works like sendasset, but with control over the from-address whose funds are used. Any change from the transaction is sent back to from-address. See also sendfrom for sending multiple assets in one transaction.
sendfrom from-address to-address amounts
(comment) (comment-to)
This works like send, but with control over the from-address whose funds are used. Any change from the transaction is sent back to from-address.
sendwithdata address amounts metadata This works like send, but with an additional transaction output containing metadata specified in one of these forms.
sendwithdatafrom from-address to-address
amounts metadata
This works like sendwithdata, but with control over the from-address whose funds are used. Any change from the transaction is sent back to from-address.
Atomic exchange transactions
appendrawexchange tx-hex txid vout
{"asset":qty, ...}
Adds to the raw atomic exchange transaction in tx-hex given by a previous call to createrawexchange or appendrawexchange. This adds an offer to exchange the asset/s in output vout of transaction txid for qty units of asset, where asset is an asset name, ref or issuance txid (use "" as the asset to specify a quantity of the native currency). The txid and vout should generally be taken from preparelockunspent or preparelockunspentfrom. Multiple items can be specified within the fourth parameter to request multiple assets. Returns a raw transaction in the hex field alongside a complete field stating whether the exchange is complete (i.e. balanced) or not. If complete, the transaction can be broadcast to the network using sendrawtransaction. If not, it can be passed to a further counterparty, who can call decoderawexchange and appendrawexchange as appropriate.
completerawexchange tx-hex txid vout
{"asset":qty, ...}
(metadata)
This works like appendrawexchange but finalizes the exchange, preventing any further additions. (Technically, it adds a SIGHASH_ALL signature.) If the completed exchange is not balanced, an error is returned. Optional metadata can be added in an additional transaction output, signed by this user only, by specifying it in one of these forms. Returns a raw transaction in hexadecimal which can be broadcast to the network using sendrawtransaction.
createrawexchange txid vout
{"asset":qty, ...}
Creates a new atomic exchange transaction which offers to exchange the asset/s in output vout of transaction txid for qty units of asset, where asset is an asset name, ref or issuance txid (use "" as the asset to specify a quantity of the native currency). The txid and vout should generally be taken from the response to preparelockunspent or preparelockunspentfrom. Multiple items can be specified within the third parameter to request multiple assets. Returns a raw partial transaction in hexadecimal which can be passed to the counterparty, who can call decoderawexchange and appendrawexchange as appropriate.
decoderawexchange tx-hex
(verbose=false)
Decodes the raw exchange transaction in tx-hex, given by a previous call to createrawexchange or appendrawexchange. Returns details on the offer represented by the exchange and its present state. The offer field in the response lists the quantity of native currency and/or assets which are being offered for exchange. The ask field lists the native currency and/or assets which are being asked for. The candisable field specifies whether this wallet can disable the exchange transaction by double-spending against one of its inputs. The cancomplete field specifies whether this wallet has the assets required to complete the exchange. The complete field specifies whether the exchange is already complete (i.e. balanced) and ready for sending. If verbose is true then all of the individual stages in the exchange are listed. Other fields relating to fees are only relevant for blockchains which use a native currency.
disablerawtransaction tx-hex Sends a transaction to disable the offer of exchange in tx-hex, returning the txid. This is achieved by spending one of the exchange transaction’s inputs and sending it back to the wallet. To check whether this can be used on an exchange transaction, check the candisable field of the output of decoderawexchange.
preparelockunspent {"asset":qty, ...}
(lock=true)
Prepares an unspent transaction output (useful for building atomic exchange transactions) containing qty units of asset, where asset is an asset name, ref or issuance txid (use "" as the asset to specify a quantity of the native currency). Multiple items can be specified within the first parameter to include several assets within the output. The output will be locked against automatic selection for spending unless the optional lock parameter is set to false. Returns the txid and vout of the prepared output.
preparelockunspentfrom from-address
{"asset":qty, ...}
(lock=true)
This works like preparelockunspent, but with control over the from-address whose funds are used to prepare the unspent transaction output. Any change from the transaction is send back to from-address.
Stream management
create type=stream name
restrictions
(custom-fields)
Creates a new stream on the blockchain called name. Pass the value "stream" in the type parameter (the create API can also be used to create upgrades and filters). Pass an object such as {"restrict":"offchain,onchain,write,read"} in restrictions to restrict some activites, where offchain disallows publishing off-chain items, onchain disallows publishing on-chain items, write restricts writing to addresses with per-stream write permissions, and read restricts reading to addresses with per-stream read permissions. (Writing and reading in streams with read permissions requires MultiChain Enterprise, but any node can create these streams and manage their permissions.) Include "salted":true in restrictions to include random salt in all offchain chunks, to protect against dictionary attacks and ensure each chunk hash is unique. Read-restricted streams automatically use salting and disallow on-chain items. Pass a JSON object in the optional custom-fields parameter to provide extra information about the stream. Returns the txid of the transaction creating the stream.
createfrom from-address
type=stream
name open|params
(custom-fields)
This works like create, but with control over the from-address used to create the stream. It is useful if the node has multiple addresses with create permissions.
getstreaminfo stream
(verbose=false)
Returns information about a single stream created on the blockchain, where stream is the stream name, ref or creation txid. Set verbose to true for the stream’s creator addresses. This command can also be used as a Smart Filter callback and so excludes the node-specific information provided by liststreams.
liststreams (streams=*)
(verbose=false)
(count=MAX)
(start=-count)
Returns information about streams created on the blockchain. Pass a stream name, ref or creation txid in streams to retrieve information about one stream only, an array thereof for multiple streams, or * for all streams. Use count and start to retrieve part of the list only, with negative start values (like the default) indicating the most recently created streams. Extra fields are shown for streams to which this node has subscribed.
Publishing stream items
publish stream key(s)
data (options)
Publishes an item in stream, passed as a stream name, ref or creation txid. Pass a single textual key or an array thereof in the key(s) parameter. The data parameter can accept raw hexadecimal data like a1b2c3d4, a reference to the binary cache {"cache":"Ev1HQV1aUCY"}, textual data {"text":"hello world"} or JSON data {"json":{"i":[1,2],"j":"yes"}}. Pass offchain in the options parameter to publish as an off-chain stream item. Returns the txid of the transaction sent. To easily publish multiple items in a single transaction, see the publishmulti(from) command.
publishfrom from-address stream
key(s) data (options)
This works like publish, but publishes the item from from-address. It is useful if a stream is open or the node has multiple addresses with per-stream write permissions.
publishmulti stream
items
(options)
Publishes multiple stream items in a single transaction, up to the max-std-op-returns-count blockchain parameter. Set stream to the name, ref or creation txid of the default stream for publishing and options to offchain to publish off-chain items by default. Pass an array in items, each member of which takes the minimum form {"key":"k1","data":"0123"} or {"keys":["k1","k2"],"data":"0123"}. As with the regular publish API, each data field can also contain a {"cache":"..."} or {"text":"..."} or {"json":...} structure. Each element in items may also contain a "for":"stream1" and/or "options":"offchain" field to override the defaults. Returns the txid of the transaction publishing the items.
publishmultifrom from-address
stream items
(options)
This works like publishmulti, but publishes the items from from-address.
Managing stream and asset subscriptions
subscribe asset(s)|stream(s)
(rescan=true)
(parameters)
Instructs the node to start tracking one or more asset(s) or stream(s). These are specified using a name, ref or creation/issuance txid, or for multiple items, an array thereof. If rescan is true, the node will reindex all items from when the assets and/or streams were created, as well as those in other subscribed entities. To improve performance in MultiChain Enterprise, pass a comma-delimited string such as "items,keys,retrieve" in parameters to control which indexes are built for streams and whether to retrieve all off-chain items. Other options are publishers,items-local,keys-local,publishers-local, where -local indexes are used for querying the stream with local ordering in APIs such as liststreamitems. Returns null if successful. See also the autosubscribe runtime parameter.
trimsubscribe stream(s)
parameters
Available in MultiChain Enterprise only. Instructs the node to stop building certain indexes for one or more stream(s), specified using a name, ref or creation/issuance txid, or for multiple items, an array thereof. Pass a comma-delimited list in parameters containing one or more of retrieve,keys,publishers,items-local,keys-local,publishers-local whose meanings are the same as for subscribe. It is not possible to remove the items index.
unsubscribe asset(s)|stream(s)
(purge=false)
Instructs the node to completely stop tracking one or more asset(s) or stream(s). Assets or streams are specified using a name, ref or creation/issuance txid, or for multiple items, an array thereof. If purge is true then any off-chain data retrieved for this stream will be purged from disk.
Querying subscribed assets
getassettransaction asset txid
(verbose=false)
Retrieves a specific transaction txid involving asset, passed as an asset name, ref or issuance txid, to which the node must be subscribed. Set verbose to true for additional information about the transaction.
listassettransactions asset (verbose=false)
(count=10) (start=-count)
(local-ordering=false)
Lists transactions involving asset, passed as an asset name, ref or issuance txid, to which the node must be subscribed. Set verbose to true for additional information about each transaction. Use count and start to retrieve part of the list only, with negative start values (like the default) indicating the most recent items. Set local-ordering to true to order transactions by when first seen by this node, rather than their order in the chain.
Querying subscribed streams
getstreamitem stream txid
(verbose=false)
Retrieves a specific item with txid from stream, passed as a stream name, ref or creation txid, to which the node must be subscribed. Set verbose to true for additional information about the item’s transaction. If an item’s data is larger than the maxshowndata runtime parameter, it will be returned as an object whose fields can be used with gettxoutdata. If the transaction contains more than one item for the stream, this will return an error – use liststreamtxitems instead.
getstreamkeysummary stream
key
mode

Outputs a summary of all items in stream (passed as a stream name, ref or creation txid) with stream key. (Any items which are marked as invalid by a stream filter are not included in the summary.) The mode parameter is a comma-delimited list of keywords. For now, mode must contain jsonobjectmerge, which states that all JSON objects in the qualifying stream items should be merged into a single object. The merged object contains all the JSON keys from the individual objects, with the latest value for each. Optional keywords include:

  • recursive merges JSON sub-objects recursively.
  • noupdate returns the first value for each JSON key instead of the last.
  • omitnull omits JSON keys with null values from the response.
  • ignoreother ignores non-JSON object items instead of giving an error.
  • ignoremissing ignores off-chain items with missing data instead of giving an error.
  • firstpublishersany only includes items signed by a publisher of the key’s first item.
  • firstpublishersall only includes items signed by all publishers of the key’s first item.

This API enables a stream to be efficiently used as a general-purpose database, with each stream key representing a separate entity, and each stream item representing the creation or updating of that entity.

getstreampublishersummary stream
address
mode
This works like getstreamkeysummary, except it summarizes all stream items published by address independent of their key, and the firstpublishersany and firstpublishersall keywords are not allowed. This API enables a stream to be efficiently used as an identity database, where each participant independently maintains their own entry.
gettxoutdata txid vout
(count-bytes=INT_MAX)
(start-byte=0)
Returns the data embedded or referenced (for off-chain stream items) in output vout of transaction txid, in hexadecimal. This is particularly useful if a stream item’s data is larger than the maxshowndata runtime parameter. For binary data only, use the count-bytes and start-byte parameters to retrieve part of the data.
liststreamblockitems stream blocks
(verbose=false)
(count=MAX) (start=-count)
This works like liststreamitems, but listing items within the specified blocks only. One or more blocks can be specified using their heights, hashes or timestamps – see the listblocks command for more information.
liststreamkeyitems stream key (verbose=false)
(count=10) (start=-count)
(local-ordering=false)
This works like liststreamitems, but listing items with the given key only.
liststreamkeys stream (keys=*)
(verbose=false)
(count=MAX) (start=-count)
(local-ordering=false)
Provides information about keys in stream, passed as a stream name, ref or creation txid. Pass a single key in keys to retrieve information about one key only, pass an array for multiple keys, or * for all keys. Set verbose to true to include information about the first and last item with each key shown. See liststreamitems for details of the count, start and local-ordering parameters.
liststreamitems stream (verbose=false)
(count=10) (start=-count)
(local-ordering=false)
Lists items in stream, passed as a stream name, ref or creation txid. Set verbose to true for additional information about each item’s transaction. Use count and start to retrieve part of the list only, with negative start values (like the default) indicating the most recent items. Set local-ordering to true to order items by when first seen by this node, rather than their order in the chain. If an item’s data is larger than the maxshowndata runtime parameter, it will be returned as an object whose fields can be used with gettxoutdata.
liststreampublisheritems stream address
(verbose=false)
(count=10) (start=-count)
(local-ordering=false)
This works like liststreamitems, but listing items published by the given address only.
liststreampublishers stream (addresses=*)
(verbose=false)
(count=MAX) (start=-count)
(local-ordering=false)
Provides information about publishers who have written to stream, passed as a stream name, ref or creation txid. Pass a single address in addresses to retrieve information about one publisher only, pass an array or comma-delimited list for multiple publishers, or * for all publishers. Set verbose to true to include information about the first and last item by each publisher shown. See liststreamitems for details of the count, start and local-ordering parameters, relevant only if address=*.
liststreamqueryitems stream
query
(verbose=false)
This works like liststreamitems, but listing items in stream which match all of the specified keys and/or publishers in query. The query is an object with a key or keys field, and/or a publisher or publishers field. If present, key and publisher should specify a single key or publisher respectively, whereas keys and publishers should specify arrays thereof. Note that, unlike other stream retrieval APIs, liststreamqueryitems cannot rely completely on prior indexing, so the maxqueryscanitems runtime parameter limits how many items will be scanned after using the best index. If more than this is needed, an error will be returned.
liststreamtxitems stream
txid
(verbose=false)
This works like liststreamitems, but listing items in stream within the given txid only. It should be used as a replacement for getstreamitem if multiple items are being published to a single stream in a single transaction.
Controlling off-chain data
purgepublisheditems items Available in MultiChain Enterprise only. Purges selected off-chain items published by this node from local storage. Use with caution – this can lead to permanent data loss if no other node has retrieved the items. The items parameter can accept all for all items, a comma-delimited list or array of transaction IDs, an array of {"txid":"id","vout":n} transaction outputs, or a {"blocks":blocks-set} set of blocks (where blocks-set takes any format accepted by listblocks). Returns statistics on how many chunks were purged and their total size. If this node is subscribed to the stream in which a purged item appears, the item will no longer be available. However this does not purge any item retrieved by this node from the network, unless that item is identical to a purged published item, and neither item is salted. To avoid these collisions, create streams with {"salted":true}. To explicitly purge retrieved items, use purgestreamitems.
purgestreamitems stream
items
Available in MultiChain Enterprise only. Purges selected off-chain items retrieved from stream (specified by name, ref or creation txid) from local storage and prevents their future automatic retrieval. The items parameter can accept all for all items, a comma-delimited list or array of transaction IDs, an array of {"txid":"id","vout":n} transaction outputs, a {"blocks":blocks-set} set of blocks (where blocks-set takes any format accepted by listblocks) or any query such as {"key":"key1"} accepted by liststreamqueryitems. Returns statistics on how many items were matched and how many chunks were purged and their total size. This does not purge items published by this node – see purgepublisheditems. Note also that if another stream contains an identical item, and neither item is salted, then the purged item may still be available in this stream. To avoid these collisions, create streams with {"salted":true}.
retrievestreamitems stream
items
Available in MultiChain Enterprise only. Queues selected off-chain items in stream (specified by name, ref or creation txid) for retrieval from the network, including items that were not automatically retrieved and items that were explicitly purged. The items parameter takes the same form as for purgestreamitems. Returns statistics on how many items and chunks were matched, and their total size.
Managing wallet unspent outputs
combineunspent (addresses=*) (minconf=1)
(maxcombines=100) (mininputs=2)
(maxinputs=100) (maxtime=15)
Sends transactions to combine unspent outputs (UTXOs) belonging to the same address into a single unspent output, returning a list of txids. This can improve wallet performance, especially for block creators in a chain with short block times and non-zero rewards. Set addresses to a comma-separated list of addresses to combine outputs for, or * for all addresses in the wallet. Only combines outputs with at least minconf confirmations, using between mininputs and maxinputs per transaction. A single call to combineunspent can create up to maxcombines transactions over up to maxtime seconds. See also the autocombine runtime parameters.
listlockunspent Returns a list of locked unspent transaction outputs in the wallet. These will not be used when automatically selecting the outputs to spend in a new transaction.
listunspent (minconf=1) (maxconf=999999)
(["address", ...])
Returns a list of unspent transaction outputs in the wallet, with between minconf and maxconf confirmations. For a MultiChain blockchain, each transaction output includes assets and permissions fields listing any assets or permission changes encoded within that output. If the third parameter is provided, only outputs which pay an address in this array will be included.
lockunspent unlock
([{"txid":"id","vout":n},...])
If unlock is false, locks the specified transaction outputs in the wallet, so they will not be used for automatic coin selection. If unlock is true, it unlocks the specified outputs, or unlocks all outputs if no second parameter is provided.
Working with raw transactions
appendrawchange tx-hex address
(native-fee)
Adds a change output to the raw transaction in tx-hex given by a previous call to createrawtransaction. Any assets or native currency in the transaction inputs which are not claimed in the outputs will be sent to address, minus the native-fee (which is calculated automatically if omitted). The returned raw transaction can be signed and broadcast to the network using signrawtransaction and sendrawtransaction.
appendrawdata tx-hex metadata|object Adds a metadata output to the raw transaction in tx-hex given by a previous call to createrawtransaction. Regular metadata can be specified in one of these forms, or an object can be passed to represent asset issuance, stream creation or a stream item – see raw transactions for more details. The returned raw transaction can be signed and broadcast to the network using signrawtransaction and sendrawtransaction.
appendrawtransaction tx-hex
[{"txid":"id","vout":n},...]
({"address":amounts,...})
(data=[]) (action="")
This works like createrawtransaction but adds the given inputs and (regular or metadata) outputs to the raw transaction specified in tx-hex, rather than creating a new transaction. It is particularly useful for accepting an offer of exchange using an address whose private key is held outside the node's wallet. Note that if tx-hex contains more outputs than inputs, the new outputs will be inserted at position n, where n is the number of inputs in tx-hex. (This is important to preserve the viability of certain types of transaction signatures.)
createrawtransaction [{"txid":"id","vout":n},...]
{"address":amounts,...}
(data=[]) (action="")
Creates a transaction spending the specified inputs, sending to the given addresses. Each amounts field can specify a quantity of the native blockchain currency, some asset(s) and/or inline metadata, using one of these forms. The optional data array adds one or more metadata outputs to the transaction, where each element is formatted as passed to appendrawdata. The optional action parameter can be lock (locks the given inputs in the wallet), sign (signs the transaction using wallet keys), lock,sign (does both) or send (signs and sends the transaction). If action is send the txid is returned. If action contains sign, an object with hex and complete fields is returned, as for signrawtransaction. Otherwise, the raw transaction hexadecimal is returned. See raw transactions for more details on building raw transactions.
createrawsendfrom from-address
{"to-address":amounts,...}
(data=[]) (action="")
This works like createrawtransaction, except it automatically selects the transaction inputs from those belonging to from-address, to cover the appropriate amounts. One or more change outputs going back to from-address will also be added to the end of the transaction.
decoderawtransaction tx-hex Returns a JSON object describing the serialized transaction in tx-hex. For a MultiChain blockchain, each transaction output includes assets and permissions fields listing any assets or permission changes encoded within that output. There will also be a data field listing the content of any OP_RETURN outputs in the transaction.
sendrawtransaction tx-hex Validates the raw transaction in tx-hex and transmits it to the network, returning the txid. The raw transaction can be created using createrawtransaction, (optionally) appendrawdata and signrawtransaction, or else createrawexchange and appendrawexchange.
signrawtransaction tx-hex
([{parent-output},...])
(["private-key",...])
(sighashtype=ALL)
Signs the raw transaction in tx-hex, often provided by a previous call to createrawtransaction or createrawsendfrom. Returns a raw hexadecimal transaction in the hex field alongside a complete field stating whether it is now completely signed. If complete, the transaction can be broadcast to the network using sendrawtransaction. If not, it can be passed to other parties for additional signing. To create chains of unbroadcast transactions, pass an optional array of {parent-output} objects, each of which takes the form {"txid":"id","vout":n,"scriptPubKey":"hex"}. To sign using (only) specific private keys, which need not be in the node's wallet, pass an array of "private-key" strings, formatted like the output of dumpprivkey. To sign using the wallet's private keys, omit this parameter or pass null. To sign only part of the transaction, use sighashtype to control the signature hash type.
Peer-to-peer connections
addnode ip(:port)
command
Manually adds or removes a peer-to-peer connection (peers are also discovered and added automatically). The ip can be a hostname, IPv4 address, IPv4-as-IPv6 address or IPv6 address. For the entire ip:port you can also use the part after the @ symbol of the other node's nodeaddress, as given by the getinfo command. The command parameter should be one of add (to manually queue a node for the next available slot), remove (to remove a node), or onetry (to immediately connect to a node even if a slot is not available).
getaddednodeinfo verbose (ip(:port)) If verbose=true, returns information about a node which was added using addnode, or all such nodes if ip(:port) is omitted. If verbose=false, returns a list of added nodes only.
getnetworkinfo Returns information about the network ports to which the node is connected, and its local IP addresses.
getpeerinfo Returns information about the other nodes to which this node is connected. If this is a MultiChain blockchain, includes handshake and handshakelocal fields showing the remote and local address used during the handshaking for that connection.
ping Sends a ping message to all connected nodes to measure network latency and backlog. The results are received asynchronously and retrieved from the pingtime field of the response to getpeerinfo.
Messaging signing and verification
signmessage address|privkey
message
Returns a base64-encoded digital signature which proves that message was approved by the owner of address (which must belong to this wallet) or any other private key given in privkey. The signature can be verified by any node using the verifymessage command.
verifymessage address signature
message
Verifies that message was approved by the owner of address by checking the base64-encoded digital signature provided by a previous call to signmessage. The result is true or false unless an error occurred.
Querying the blockchain
getblock hash|height
(verbose=1)
Returns information about the block with hash (retrievable from getblockhash) or at the given height in the active chain. Set verbose to 0 or false for the block in raw hexadecimal form. Set to 1 or true for a block summary including the miner address and a list of txids. Set to 2 to 3 to include more information about each transaction and its raw hexadecimal. Set to 4 to include a full description of each transaction, formatted like the output of decoderawtransaction.
getblockchaininfo Returns information about the blockchain, including the bestblockhash of the most recent block on the active chain, which can be compared across nodes to check if they are perfectly synchronized.
getblockhash height Returns the hash of the block at the given height. This can be passed to getblock to get information about the block.
getlastblockinfo (skip=0) Returns information about the last or recent blocks in the active chain. Omit skip or set to 0 for information about the most recent block. Pass 1 for the block before that, and so on. This command can also be used as a Smart Filter callback and provides less information than listblocks or getblock.
getmempoolinfo Returns information about the memory pool, which contains transactions that the node has seen and validated, but which have not yet been confirmed on the active chain. If the memory pool is growing continuously, this suggests that transactions are being generated faster than the network is able to process them.
getrawmempool Returns a list of transaction IDs which are in the node's memory pool (see getmempoolinfo).
getrawtransaction txid (verbose=0) If verbose is 1, returns a JSON object describing transaction txid. This may fail with an error for some transactions if the runtime parameter txindex=0. For a MultiChain blockchain, each transaction output includes assets and permissions fields listing any assets or permission changes encoded within that output. There will also be a data field listing the content of any OP_RETURN outputs in the transaction.
gettxout txid vout
(unconfirmed=false)
Returns details about an unspent transaction output vout of txid. For a MultiChain blockchain, includes assets and permissions fields listing any assets or permission changes encoded within the output. Set unconfirmed to true to include unconfirmed transaction outputs.
listblocks blocks
(verbose=false)
Returns information about the blocks specified, on the active chain only. The blocks parameter can contain a comma-delimited list or array of block heights, hashes, height ranges (e.g. 100-200) or -n for the most recent n blocks. Alternatively, pass an object {"starttime":...,"endtime":...} for blocks whose timestamps are in the given range.
Binary cache
createbinarycache This creates a new empty item in the binary cache. The binary cache allows large pieces of data (as raw metadata or in stream items) to be written and read from a chain, while avoiding huge JSON-RPC API requests. Returns a unique textual identifier for the item.
appendbinarycache identifier
data-hex
Appends the hexadecimal data in data-hex to the binary cache item named identifier, and returns its resulting size. Pass the empty string in data-hex to obtain the item's current size. Each binary cache item is stored as a file in the cache subdirectory of the blockchain directory, and can be safely modified on disk directly by external processes.
deletebinarycache identifier Removes the item named identifier from the binary cache.
txouttobinarycache identifier
txid vout
(count-bytes=INT_MAX)
(start-byte=0)
Extracts the binary data embedded or referenced (for off-chain stream items) in output vout of transaction txid to the binary cache item named identifier, and returns its resulting size. The binary cache item must currently be empty. Use the count-bytes and start-byte parameters to retrieve only part of the data.
Advanced wallet control
backupwallet filename Creates a backup of the wallet.dat file in which the node's private keys and watch-only addresses are stored. The backup is created in file filename. Use with caution – any node with access to this file can perform any action restricted to this node's addresses.
dumpprivkey address Returns the private key associated with address in this node's wallet. Use with caution – any node with access to this private key can perform any action restricted to the address.
dumpwallet filename Dumps the entire set of private keys in the wallet into a human-readable text format in file filename. Use with caution – any node with access to this file can perform any action restricted to this node's addresses.
encryptwallet passphrase This encrypts the node's wallet for the first time, using passphrase as the password for unlocking. Once encryption is complete, the wallet's private keys can no longer be retrieved directly from the wallet.dat file on disk, and MultiChain will stop and need to be restarted. Use with caution – once a wallet has been encrypted it cannot be permanently unencrypted, and must be unlocked for signing transactions with the walletpassphrase command. In a permissioned blockchain, MultiChain will also require the wallet to be unlocked before it can connect to other nodes, or sign blocks that it has created.
getwalletinfo Returns information about the node's wallet, including txcount showing the number of transactions and stream keys (name preserved for compatibility) and utxocount showing the number of tracked unspent transaction outputs. If the wallet has been encrypted and unlocked, it also shows when it is unlocked_until.
importprivkey privkey(s) (label)
(rescan=true)
Adds a privkey private key (or an array thereof) to the wallet, together with its associated public address. The rescan parameter controls whether and how the blockchain is rescanned for transactions relating to all wallet addresses, including these new ones. Pass true to rescan the entire chain, false to skip rescanning, and from version 1.0.5, a positive integer to rescan from that block number or a negative integer to rescan that many recent blocks. Returns null if successful.
importwallet filename
(rescan=0)
Imports the entire set of private keys which were previously dumped (using dumpwallet) into file filename into the wallet, together with their associated public addresses. From version 1.0.5, the rescan parameter controls whether and how the blockchain is rescanned for transactions relating to all wallet addresses, including these new ones. Pass zero or a positive integer to rescan from that block number or a negative integer to rescan that many recent blocks. Versions prior to 1.0.5 always perform a full rescan.
walletlock This immediately relocks the node's wallet, independent of the timeout provided by a previous call to walletpassphrase.
walletpassphrase passphrase timeout This uses passphrase (as set in earlier calls to encryptwallet or walletpassphrasechange) to unlock the node's wallet for signing transactions for the next timeout seconds. In a permissioned blockchain, this will also need to be called before the node can connect to other nodes or sign blocks that it has created.
walletpassphrasechange old-passphrase
new-passphrase
This changes the wallet's password from old-passphrase to new-passphrase.
Smart filters and upgrades
approvefrom from-address
entity approve
Approves or disapproves the specified upgrade or filter from from-address. The entity specifies an upgrade using its name or creation txid, or a filter using its name, ref or creation txid. When approving or disapproving an upgrade or global transaction filter, pass true or false in the approve parameter as appropriate. When approving or disapproving a stream filter for a stream, pass a {"for":stream,"approve":true|false} object instead, where stream is the stream's name, ref or creation txid. Returns the txid of the approval transaction sent.
create type=streamfilter
name
restrictions
js-code
Creates a new stream filter on the blockchain called name. Pass the value "streamfilter" in the type parameter (the create API can also be used to create other things) and the empty object {} in the restrictions parameter. (Stream filters are not created for specific streams, but are rather approved on a per-stream basis by each stream's administrator.) Pass the JavaScript code for the filter itself in js-code – see Smart Filters for more details. Note that an address requires create permissions to create a stream filter. Returns the txid of the transaction creating the filter.
create type=txfilter
name
restrictions
js-code
Creates a new (as yet unapproved) transaction filter on the blockchain called name. Pass the value "txfilter" in the type parameter (the create API can also be used to create other things). To apply the filter for all transactions, pass {} in the restrictions parameter. To only apply for transactions referencing a particular asset or stream, pass {"for":"entity"}, where entity is an asset or stream name, ref or creation txid. To apply for multiple entities, pass {"for":["entity1","entity2",...]}. Pass the JavaScript code for the filter itself in js-code – see Smart Filters for more details. Note that an address requires both admin and create permissions to create a transaction filter. Returns the txid of the transaction creating the filter.
create type=upgrade
name open=false
params
Creates a new (as yet unapproved) upgrade on the blockchain called name. Pass the value "upgrade" in the type parameter (the create API can also be used to create streams and filters) and false for the open parameter. Pass an object in params with the blockchain parameters to change, e.g. {"protocol-version":20005,"target-block-time":20}. As of the most recent protocol version, the following parameters can be upgraded: protocol-version target-block-time maximum-block-size maximum-chunk-size maximum-chunk-count, all max-std-* and all anyone-can-* except mine and admin. To prevent abrupt changes in blockchain capacity and performance, target-block-time cannot be changed more than once per 100 blocks and all capacity-related parameters cannot be changed to less than half or more than double their previous size. To create an upgrade that is applied from a specific block height, include "startblock":12345 in the params object. Note that an address requires both admin and create permissions to create an upgrade. Returns the txid of the transaction creating the upgrade.
createfrom from-address type
name open=false
{"protocol-version":100xx}
This works like create, but with control over the from-address used to create the filter or upgrade. It is useful if the node has multiple addresses with the appropriate permissions.
getfiltercode filter Returns the JavaScript code for a transaction or stream filter, where filter is the filter name, ref or creation txid.
liststreamfilters (filters=*)
(verbose=false)
Returns information about stream filters on the blockchain. Pass a filter name, ref or creation txid in filters to retrieve information about one filter only, an array thereof for multiple filters, or * for all stream filters. The response includes information on whether each filter can be compiled successfully. Set verbose to true to see each filter's creators.
listtxfilters (filters=*)
(verbose=false)
Returns information about transaction filters on the blockchain, whether pending or approved. Pass a filter name, ref or creation txid in filters to retrieve information about one filter only, an array thereof for multiple filters, or * for all transaction filters. The response includes information on whether each filter can be compiled successfully and whether it has been approved by consensus. Set verbose to true to see each filter's creators, which admins have approved it so far, and pending approval changes.
listupgrades (upgrades=*) Returns information about upgrades on the blockchain, whether pending or approved. Pass an upgrade name or creation txid in upgrades to retrieve information about one upgrade only, an array thereof for multiple upgrades, or * for all upgrades. The response includes information on whether each upgrade has been approved by consensus, which admins have approved it so far, how many more admins are required to reach consensus, and the appliedblock where the upgrade became active.
runstreamfilter filter
(tx-hex|txid)
(vout)
This works like teststreamfilter, but tests a stream filter already created on the blockchain, where filter is the filter name, ref or creation txid.
runtxfilter filter
(tx-hex|txid)
This works like testtxfilter, but tests a transaction filter already created on the blockchain, where filter is the filter name, ref or creation txid.
teststreamfilter restrictions
js-code
(tx-hex|txid)
(vout)
Tests a stream filter before it is created on the blockchain. See create streamfilter for a description of the restrictions and js-code parameters. If no tx-hex or txid is passed, only compilation is tested, with compiled in the response indicating success, and reason containing the error if compilation failed. If a raw transaction or the id of a previous transaction containing a stream item is passed in tx-hex|txid, the stream item is also tested against the compiled filter. (If the transaction contains multiple stream items, pass the appropriate output index in vout.) In the response, passed indicates whether the item passed the filter, and reason contains the reason (given by the filter) if not. The response also contains a log of callbacks made by the filter, including their responses, and the time it took to run.
testtxfilter restrictions
js-code
(tx-hex|txid)
Tests a transaction filter before it is created on the blockchain. See create txfilter for a description of the restrictions and js-code parameters. If no tx-hex or txid is passed, only compilation is tested, with compiled in the response indicating success, and reason containing the error if compilation failed. If a raw transaction or the id of a previous transaction is passed in tx-hex|txid, the transaction is also tested against the compiled filter. In the response, passed indicates whether the transaction passed the filter, and reason contains the reason (given by the filter) if not. The response also contains a log of callbacks made by the filter, including their responses, and the time it took to run.
Advanced node control
clearmempool Removes all unconfirmed transactions from this node's memory pool. This can only be called after pause incoming,mining. Successful if no error is returned.
getchunkqueueinfo Returns information about the queue for retrieving off-chain stream items, providing both a count of chunks and the total number of bytes represented by each state. Chunks can be waiting in the queue, querying across the network, or retrieving from a specific node.
getchunkqueuetotals Returns cumulative statistics on queries and requests for off-chain stream items sent out by this node, and their outcomes. The API provides both a count of chunks and the total number of bytes represented by each outcome. Of the queries sent out to find a chunk in the network, it shows how many were successfully responded and how many were unresponded (no positive response before timeout). Of the requests for delivery sent to specific nodes, it shows how many were successfully delivered, and how many were undelivered (no delivery before timeout) or baddelivered (mismatching data delivered).
pause tasks Pauses the specified tasks, specified as a comma-delimited list of mining (generating blocks), incoming (processing of incoming blocks and transactions) and/or offchain (requesting, relaying or delivering off-chain stream items). Successful if no error is returned.
resume tasks Resumes the specified tasks, specified as in the pause command. Successful if no error is returned.
setlastblock hash|height Rewinds this node's active chain to height or rewinds/switches to another block with hash. This can only be called after pause incoming,mining. Returns the hash of the last block in the chain after the change.

Amounts parameter forms

All amounts parameters specify the content of a single transaction output and can take any of the following forms:

  • A quantity of the native blockchain currency only, e.g. 0.01
  • A single asset quantity, e.g. {"asset1":50}
  • Multiple asset quantities, e.g. {"asset1":50,"asset2":1.5}
  • Asset(s) with native currency specified with a "", e.g. {"asset1":50,"asset2":1.5,"":0.01}
  • Asset(s) and/or native currency with binary inline metadata, e.g. {"asset1":50,"data":"a1b2c3d4"}
  • Asset(s) and/or native currency with textual inline metadata, e.g. {"asset1":50,"asset2":1.5,"data":{"text":"hello"}}
  • Asset(s) and/or native currency with JSON inline metadata, e.g. {"":0.01,"asset1":50,"data":{"json":[1,2,3]}}

Within these forms, assets can be specified using their name, ref or issuance txid. Note that inline metadata sits within a regular transaction output that can contain spendable assets. This is different from regular transaction metadata or stream items which sit in a separate output that cannot be spent.

Metadata parameter forms

All metadata parameters can take any of the following forms:

  • Raw binary metadata in hexadecimal, e.g. a1b2c3d4
  • Raw metadata from the binary cache, e.g. {"cache":"Ev1HQV1aUCY"}
  • Raw textual metadata, e.g. {"text":"hello world"}
  • Raw JSON metadata, e.g. {"json":{"i":[1,2],"j":"yes"}}
  • A binary stream item in hexadecimal, e.g. {"for":"stream1","keys":["key1","key2"],"data":"a1b2c3d4"}
  • A binary stream item from the cache, e.g. {"for":"stream1","keys":["key1","key2"],"data"{"cache":"Ev1HQV1aUCY"}}
  • A textual stream item, e.g. {"for":"stream1","keys":["key1","key2"],"data":{"text":"hello"}}
  • A JSON stream item, e.g. {"for":"stream1","keys":["key1"],"data":{"json":{"i":[1,2]}}}

In all stream item forms, a single key can be passed using "key":"key1" instead of "keys":["key1","key2"]. In addition, all stream item forms can include an optional "options":"offchain" field to publish their data off-chain.

Incompatible changes from MultiChain 1.0

The MultiChain 2.0 API is close to 100% backwards compatible with applications built on MultiChain 1.0.x. Nonetheless, some enhancements cause inevitable changes, and a major release is a good time to deprecate unclear input formats and shorten responses that were too verbose.

Below is a full list of incompatible changes introduced in the transition from MultiChain 1.0 to 2.0. To continue including all MultiChain 1.0 fields to remain in 2.0 API responses, set the runtime parameter v1apicompatible=1.

  • When viewing stream items, key is replaced by keys showing an array of item keys. (If v1apicompatible=1 then key still shows the first key.) Note that when specifying stream items in various APIs, a single key or array can still be used, and key and keys can be used interchangeably.
  • When listing streams, or viewing a transaction which created a stream, the open field is superceded by the write field of the restrict subelement (with the boolean opposite value).
  • When viewing a wallet transaction, the payload of stream items is not duplicated in the top-level data element.
  • When decoding a raw transaction, empty assets, permissions and items arrays for individual outputs are not shown.
  • When decoding a raw transaction, the payload of raw metadata or stream items is not duplicated in a top-level data element.
  • When using raw transactions to issue an asset, "create":"asset" must be stated in the data element.
  • When using raw transactions to perform a follow-on asset issuance, "update":[asset-identifier] must be stated in the data element.

A note about accounts

MultiChain supports all commands in the Bitcoin Core API (as of version 0.10), except those which relate to external mining hardware and Bitcoin Core's "accounts" mechanism. In Bitcoin Core's "accounts", each address can belong to specific account, which is credited when bitcoin is sent to that address. However the separation of accounts is not preserved when bitcoin is sent out, because the internal accounting mechanism has no relationship to the bitcoin protocol itself. Because of all the confusion this has caused, Bitcoin Core's accounts mechanism is to be deprecated in future.

MultiChain does not support Bitcoin Core's account APIs, if you are using the new wallet version which is activated by default (walletdbversion=2 in the output from getinfo). This includes the commands: getaccount getaccountaddress getreceivedbyaccount listreceivedbyaccount move sendfrom sendmany setaccount. In addition it only supports an empty value for the account parameter of: addmultisigaddress getaddressesbyaccount getbalance getnewaddress. If you are using the old wallet version, MultiChain preserves full backwards compatibility with the Bitcoin Core API, but (a) sendfrom is renamed to sendfromaccount, and (b) the accounts mechanism is not applied to native asset balances, all of which are considered as belonging to a single global account.

Overall we recommend not using accounts at all with MultiChain, and using "" for any account parameter in the API. Instead, to support multiple users in a single MultiChain node's wallet, call getnewaddress to get a different address for each user. You should then use MultiChain's from APIs, such as sendassetfrom and sendfrom, to control whose funds are spent in each transaction. Unlike bitcoin-style accounts, this method maps directly to the blockchain protocol.