MultiChain 1.0 API commands

Controlling a MultiChain 1.0 node from your application

Note: This page has been kept for MultiChain 1.0 – documentation for the MultiChain 2 API is now available.

Accessing the API

To access MultiChain’s API, use the included multichain-cli command-line tool or any other JSON-RPC client. (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, 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.

Compatibility with Bitcoin Core

MultiChain supports all commands in the Bitcoin Core API (as of version 0.10), except those which relate to Bitcoin Core’s “accounts” mechanism – see note below. In some cases, MultiChain extends Bitcoin Core’s commands in a backwards-compatible way to enable additional functionality.

A summary of Bitcoin Core commands is listed in the bitcoin wiki or consult the developer documentation for more comprehensive details. The most useful ones are listed below, along with MultiChain’s new commands.

List of API commands by category – view alphabetically

In the table below, all optional parameters are denoted in (round brackets) with non-empty default values indicated after the = symbol. You should also consult 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: `autosubscribe bantx handshakelocal hideknownopdrops lockadminminerounds lockblock maxshowndata mineemptyrounds miningrequirespeers miningturnover`.
`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 `entity.issue` or `entity.write,admin` where `entity` 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 transaction granting the permissions. 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 administrator permissions.
`grantwithdata` or `grantwithmetadata`	`addresses permissions data-hex\|object (native-amount=0) (start-block) (end-block)`	This works like `grant`, but with an additional data-only transaction output. To include raw data, pass a `data-hex` hexadecimal string. To publish the data to a stream, pass an object `{"for":stream,"key":"...","data":"..."}` where `stream` is a stream name, ref or creation txid, the `key` is in text form, and the `data` is hexadecimal.
`grantwithdatafrom` or `grantwithmetadatafrom`	`from-address to-addresses permissions data-hex\|object (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 `entity.issue`, `entity.write,admin` or `entity.` where `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.

Asset management

`issue`	`address name\|params qty (units=1) (native-amount=min-per-output) ({"custom-field-1":"x",...})`	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}`. If `open` is `true` then additional units can be issued in future by the same key which signed the original issuance, via the `issuemore` or `issuemorefrom` command. 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. 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-field-1":"x",...})`	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-field-1":"x",...})`	Issues `qty` additional units of `asset`, sending them to `address`. 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. Any custom fields will be attached to the new issuance event, and 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-field-1":"x",...})`	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` or `sendtoaddress`	`address amount (comment) (comment-to)`	Sends one or more assets to `address`, returning the txid. In Bitcoin Core, the `amount` field is the quantity of the bitcoin currency. For MultiChain, an `{"asset":qty, ...}` object can be used for `amount`, in which each `asset` is an asset name, ref or issuance txid, and each `qty` is the quantity of that asset to send (see native assets). Use `""` as the `asset` inside this object to specify a quantity of the native currency. See also `sendasset` for sending a single asset and `sendfrom` to control the address whose funds are used.
`sendasset` or `sendassettoaddress`	`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` or `sendfromaddress`	`from-address to-address amount (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` or `sendwithmetadata`	`address amount data-hex\|object`	This works like `send`, but with an additional data-only transaction output. To include raw data, pass a `data-hex` hexadecimal string. To publish the data to a stream, pass an object `{"for":stream,"key":"...","data":"..."}` where `stream` is a stream name, ref or creation txid, the `key` is in text form, and the `data` is hexadecimal.
`sendwithdatafrom` or `sendwithmetadatafrom`	`from-address to-address amount data-hex\|object`	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, ...} (data-hex\|object)`	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 to the transaction, signed by this user only. To include raw data, pass a `data-hex` hexadecimal string. To publish the data to a stream, pass an object `{"for":stream,"key":"...","data":"..."}` where `stream` is a stream name, ref or creation txid, the `key` is in text form, and the `data` is hexadecimal. 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 open ({"custom-field-1":"x",...})`	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). If `open` is `true` then anyone with global `send` permissions can publish to the stream, otherwise publishers must be explicitly granted per-stream `write` permissions. Returns the txid of the transaction creating the stream.
`createfrom`	`from-address type=stream name open ({"custom-field-1":"x",...})`	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.
`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 data-hex`	Publishes an item in `stream`, passed as a stream name, ref or creation txid, with `key` provided in text form and `data-hex` in hexadecimal.
`publishfrom`	`from-address stream key data-hex`	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.

Managing stream and asset subscriptions

`subscribe`	`asset(s)\|stream(s) (rescan=true)`	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. Returns `null` if successful. See also the `autosubscribe` runtime parameter.
`unsubscribe`	`asset(s)\|stream(s)`	Instructs the node to 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.

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`.
`gettxoutdata`	`txid vout (count-bytes=INT_MAX) (start-byte=0)`	Returns the data embedded 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. Use the `count-bytes` and `start-byte` parameters to retrieve part of the data only.
`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=`.

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` or `appendrawmetadata`	`tx-hex data-hex\|object`	Adds a metadata output (using an `OP_RETURN`) to the raw transaction in `tx-hex` given by a previous call to `createrawtransaction`. Raw metadata can be specified in `data-hex` in hexadecimal form. Alternatively, 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":amount,...}) (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":amount,...} (data=[]) (action="")`	Creates a transaction spending the specified inputs, sending to the given addresses. In Bitcoin Core, each `amount` field is a quantity of the bitcoin currency. For MultiChain, an `{"asset":qty, ...}` object can be used for `amount`, in which each `asset` is an asset name, ref or issuance txid, and each `qty` is the quantity of that asset to send (see native assets). Use `""` as the `asset` inside this object to specify a quantity of the native currency. The optional `data` array adds one or more metadata outputs to the transaction, where each element is a raw hexadecimal string or object, 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":amount,...} (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":txid,"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.
`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`. 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.

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 the number of transactions (`txcount`) and unspent transaction outputs (`utxocount`), the pool of pregenerated keys. 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`.

Blockchain upgrading

`approvefrom`	`from-address upgrade approve`	Approves the specified upgrade from admin `from-address` if `approve=true`, or removes a previous approval if `approve=false`. The `upgrade` can be specified using its name or creation txid. Returns the txid of the approval transaction.
`create`	`type=upgrade name open=false {"protocol-version":100xx}`	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 `false` for the `open` parameter. For now, only the protocol version can be upgraded, for example from `10008` to `10009`. You can also pass `{"protocol-version":100xx,"startblock":yy}` to create an upgrade that will only be applied after a certain block height. 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=upgrade name open=false {"protocol-version":100xx}`	This works like `create`, but with control over the `from-address` used to create the upgrade. It is useful if the node has multiple addresses with both `admin` and `create` permissions.
`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.

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.
`pause`	`tasks`	Pauses the specified `tasks`, specified as a comma-delimited list of `mining` (i.e. generating blocks) and/or `incoming` (i.e. processing of incoming blocks and transactions). 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.

A note about accounts

Bitcoin Core has a notion of “accounts”, whereby 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.

As of alpha 22, MultiChain no longer supports 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.