clearinghoused Documentation - Read the Docs · clearinghoused Documentation, Release 0.1.0 ... By default, clearinghoused will listen on port 7300 (if on mainnet) or port 17300 (on

clearinghoused DocumentationRelease 0.1.0

ClearingHouse Team

August 21, 2014

Contents

1 Table of Contents 31.1 Interacting with the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Indices and tables 29

i

ii

clearinghoused Documentation, Release 0.1.0

Clearinghouse is a protocol for the creation and use of decentralised financial instruments such as asset exchanges,contracts for difference and dividend payments. It uses Viacoin as a transport layer. The Clearinghouse protocolspecification may be found here.

clearinghoused is the reference client (and server daemon) implementation of the Clearinghouse protocol.

To get clearinghoused installed and set up on your computer, you have two options:

• Set it up manually, using the instructions here

• For Windows and Ubuntu Linux users, you can use the automated build system

Contents 1

https://github.com/ClearingHouse/Clearinghouse

https://github.com/ClearingHouse/clearinghoused/blob/master/README.md

http://clearinghoused-build.rtfd.org


2 Contents

CHAPTER 1

Table of Contents

1.1 Interacting with the API

Warning: This API documentation is still in an early state. It contains errors, omissions, etc., and could changedrastically at any time.

1.1.1 Overview

clearinghoused features a full-fledged JSON RPC 2.0-based API, which allows third-party applications to per-form functions on the Clearinghouse network without having to deal with the lowlevel details of the protocol such astransaction encoding and state management.

1.1.2 Connecting and Making Requests

By default, clearinghoused will listen on port 7300 (if on mainnet) or port 17300 (on testnet) for API requests.

Note that this API is built on JSON-RPC 2.0, not 1.1. JSON-RPC itself is pretty lightweight, and API requests aremade via a HTTP POST request to /api/ (note the trailing slash), with JSON-encoded data passed as the POSTbody.

General Format

All requests must have POST data that is JSON encoded and in the format of:

{ "method": "METHOD NAME", "params": {"param1": "value1", "param2":"value2"}, "jsonrpc": "2.0", "id": 0 }

In particular, note the jsonrpc and id properties. These are requirements under the JSON-RPC 2.0 spec.

Here’s an example of the POST data for a valid API request:

You should note that the data in params is a JSON object (e.g. mapping), not an array. In other words, the API onlysupports named arguments, not positional arguments (e.g. use {“argument1”: “value1”, “argument2”: “value2”}instead of [”value1”, “value2”]). This is the case for safety and bug-minimzation reasons.

For more information on JSON RPC, please see the JSON RPC 2.0 specification.

3

http://www.jsonrpc.org/specification


Authentication

Also note that the clearinghoused API interface requires HTTP basic authentication to use. The username andpassword required are stored in the clearinghoused.conf file, as rpc-user and rpc-password, respec-tively. You can also modify rpc-host and rpc-port to change what interface and port number counterpartydbinds to from the defaults. Below we provide a few examples of using the clearinghoused API. Examples inother languages are welcome, if you’d like to submit them to us, structured in a way to be useful to other people anduse standard libraries/methods.

Python Example

import jsonimport requestsfrom requests.auth import HTTPBasicAuth

url = "http://localhost:7300/api/"headers = {’content-type’: ’application/json’}auth = HTTPBasicAuth(’rpcuser’, ’rpcpassword’)

#Fetch all balances for all assets for a specific address, using keyword-based argumentspayload = {

"method": "get_balances","params": {"filters": {’field’: ’address’, ’op’: ’==’, ’value’: "14qqz8xpzzEtj6zLs3M1iASP7T4mj687yq"}},"jsonrpc": "2.0","id": 0,

}response = requests.post(

url, data=json.dumps(payload), headers=headers, auth=auth).json()print("GET_BALANCES RESULT: ", response)

#Fetch all balances for all assets for both of two addresses, using keyword-based argumentspayload = {

"method": "get_balances","params": {"filters": [{’field’: ’address’, ’op’: ’==’, ’value’: "14qqz8xpzzEtj6zLs3M1iASP7T4mj687yq"},

{’field’: ’address’, ’op’: ’==’, ’value’: "1bLockjTFXuSENM8fGdfNUaWqiM4GPe7V"}],"filterop": "or"},

"jsonrpc": "2.0","id": 0,


url, data=json.dumps(payload), headers=headers, auth=auth).json()print("GET_BALANCES RESULT: ", response)

#Get all burns between blocks 280537 and 280539 where greater than .2 VIA was burned, sorting by tx_hash (ascending order)#With this (and the rest of the examples below) we use positional arguments, instead of keyword-based argumentspayload = {

"method": "get_burns","params": {"filters": {’field’: ’burned’, ’op’: ’>’, ’value’: 20000000},

"filterop": "AND","order_by": ’tx_hash’,"order_dir": ’asc’,"start_block": 280537,"end_block": 280539},

"jsonrpc": "2.0","id": 0,


4 Chapter 1. Table of Contents


url, data=json.dumps(payload), headers=headers, auth=auth).json()print("GET_BURNS RESULT: ", response)

#Fetch all debits for > 2 XCH between blocks 280537 and 280539, sorting the results by quantity (descending order)payload = {

"method": "get_debits","params": {"filters": [{’field’: ’asset’, ’op’: ’==’, ’value’: "XCH"},

{’field’: ’quantity’, ’op’: ’>’, ’value’: 200000000}],"filterop": ’AND’,"order_by": ’quantity’,"order_dir": ’desc’},

"jsonrpc": "2.0","id": 0,


url, data=json.dumps(payload), headers=headers, auth=auth).json()print("GET_DEBITS RESULT: ", response)

#Send 1 XCH (specified in satoshis) from one address to another (you must have the sending address in your viacoind wallet# and it will be broadcast as a multisig transactionpayload = {

"method": "create_send","params": {’source’: "1CUdFmgK9trTNZHALfqGvd8d6nUZqH2AAf",

’destination’: "17rRm52PYGkntcJxD2yQF9jQqRS4S2nZ7E",’asset’: "XCH",’quantity’: 100000000},

"jsonrpc": "2.0","id": 0,

}unsigned_tx = requests.post(url, data=json.dumps(payload), headers=headers, auth=auth)print("\nCREATE_SEND RESULT: ", unsigned_tx)

#2. Now sign it with a key from the walletpayload = {

"method": "sign_tx","params": {’unsigned_tx_hex’: unsigned_tx}, #could also specify an external private key to use for signing here"jsonrpc": "2.0","id": 0,

}signed_tx = requests.post(url, data=json.dumps(payload), headers=headers, auth=auth)print("\nSIGN_TX RESULT: ", signed_tx)

#3. Now broadcast the signed transactionpayload = {

"method": "broadcast_tx","params": {’signed_tx_hex’: signed_tx},"jsonrpc": "2.0","id": 0,

}tx_hash = requests.post(url, data=json.dumps(payload), headers=headers, auth=auth)print("\BROADCAST_TX RESULT: ", tx_hash)

PHP Example

With PHP, you can connect and query counterpartyd using the JsonRPC library. Here’s a simple example thatwill get you the asset balances for a specific address:

1.1. Interacting with the API 5

https://github.com/fguillot/JsonRPC


require ’JsonRPC/Client.php’;use JsonRPC\Client;$client = new Client(’http://localhost:7300/api/’);$client->authentication(’rpcuser’, ’rpcpassword’);$addr = ’15vA2MJ4ESG3Rt1PVQ79D1LFMBBNtcSz1f’; // BTC/XCP address you want to query$result = $client->execute(’get_balances’, array(’field’ => ’address’, ’op’ => ’==’, ’value’ => $addr));

curl Example

Here’s an example using curl to make an API call to the get_running_info method on mainnet.

For testnet, you could use the example above, but change the port to 17300 and change the username and passwordas necessary.

1.1.3 Terms & Conventions

assets

Everywhere in the API an asset is referenced as an uppercase alphabetic (base 26) string name of the asset, of at least4 characters in length and not starting with ‘A’, or as ‘VIA’ or ‘XCH’ as appropriate. Examples are:

• “VIA”

• “XCH”

• “FOOBAR”

Quantities & balances

Anywhere where an quantity is specified, it is specified in satoshis (if a divisible asset), or as whole numbers (if anindivisible asset). To convert satoshis to floating-point, simply cast to float and divide by 100,000,000.

Examples:

• 4381030000 = 43.8103 (if divisible asset)

• 4381030000 = 4381030000 (if indivisible asset)

NOTE: XCH and VIA themselves are divisible assets, and thus are listed in satoshis.

floats

Floats are are ratios or floating point values with six decimal places of precision, used in bets, dividends and callbacks.

Filtering Read API results

The Clearinghouse API aims to be as simple and flexible as possible. To this end, it includes a straightforward way tofilter the results of most Read API functions to get the data you want, and only that.

For each Read API function that supports it, a filters parameter exists. To apply a filter to a specific data field,specify an object (e.g. dict in Python) as this parameter, with the following members:

• field: The field to filter on. Must be a valid field in the type of object being returned



• op: The comparison operation to perform. One of: "==", "!=", ">", "<", ">=", "<=", "IN", "LIKE","NOT IN", "NOT LIKE"

• value: The value that the field will be compared against. Must be the same data type as the field is (e.g. if thefield is a string, the value must be a string too)

If you want to filter by multiple fields, then you can specify a list of filter objects. To this end, API functions that takefilters also take a filterop parameter, which determines how the filters are combined when multiple filters arespecified. It defaults to "and", meaning that filters are ANDed togeher (and that any match must satisfy all of them).You can also specify "or" as an alternative setting, which would mean that filters are ORed together, and that anymatch must satisfy only one of them.

To disable filtering, you can just not specify the filter argument (if using keyword-based arguments), or, if usingpositional arguments, just pass null or [] (empty list) for the parameter.

For examples of filtering in-use, please see the API code examples.

NOTE: Note that with strings being compared, operators like >= do a lexigraphic string comparison (which compares,letter to letter, based on the ASCII ordering for individual characters. For more information on the specific comparisonlogic used, please see this page.

The encoding Parameter of create_ Calls

All create_ API calls return an unsigned raw transaction string, hex encoded (i.e. the same format that viacoindreturns with its raw transaction API calls).

The exact form and format of this unsigned raw transaction string is specified via the encoding and pubkeyparameters on each create_ API call:

• To return the transaction as an OP_RETURN transaction, specify opreturn for the encoding parameter.Note that as of viacoind 0.9.0, not all Clearinghouse transactions are possible with OP_RETURN, due to the40 byte limit imposed by the viacoind client in order for the transaction to be relayed on mainnet.

• To return the transaction as a multisig transaction, specify multisig for the encoding parameter.

– If the source address is in the local viacoind wallet.dat. pubkey can be left as null.

– If the source address is not in the local viacoind wallet.dat, pubkey should be set to the hex-encoded public key.

• auto may also be specified to let clearinghoused choose here. Note that at this time, auto is effectivelythe same as multisig.

• To return the Clearinghouse transaction encoded into arbitrary address outputs (i.e. pubkeyhash encoding), spec-ify pubkeyhash for the encoding parameter. pubkey is also required to be set (as above, with multisigencoding) if the source address is not contained in the local viacoind wallet.dat. Note that this methodis not recommended as a first-resort, as it pollutes the UTXO set.

With any of the above settings, as the unsigned raw transaction is returned from the create_ API call itself, youthen have two approaches with respect to broadcasting the transaction on the network:

• If the private key you need to sign the raw transaction is in the local viacoind wallet.dat, you shouldthen call the sign_tx API call and pass it to the raw unsigned transaction string as the tx_hex parameter,with the privkey parameter set to None. This method will then return the signed hex transaction, which youcan then broadcast using the broadcast_tx API method.

• If the private key you need to sign the raw transaction is not in the local viacoind wallet.dat, you mustfirst sign the transaction yourself (or, alternatively, you can call the sign_tx API method and specify theprivate key string to it, and clearinghoused will sign it for you). In either case, once you have the signed,hex-encoded transaction string, you can then call the broadcast_tx API method, which will then broadcastthe transaction on the Viacoin network for you.


http://www.sqlite.org/lang_expr.html


Note that you can also use a :ref:‘do_ call instead <do_table>‘, which will take care of creating the transaction,signing it, and broadcasting it, all in one step.

1.1.4 Read API Function Reference

get_{table}

get_{table}(filters=[], filterop=’AND’, order_by=None, order_dir=None, start_block=None, end_block=None,status=None, limit=1000, offset=0, show_expired=True)

{table} must be one of the following values: balances, credits, debits, bets, bet_matches,broadcasts, viapays, burns, callbacks, cancels, dividends, issuances, orders,order_matches, sends, bet_expirations, order_expirations, bet_match_expirations,order_match_expirations, rps, rps_expirations, rps_matches, rps_match_expirations,or rpsresolves.

For example: get_balances, get_credits, get_debits, etc are all valid API methods.

Parameters:

• filters (list/dict): An optional filtering object, or list of filtering objects. See Filtering Read API results for moreinformation.

• filterop (string): Specifies how multiple filter settings are combined. Defaults to AND, but OR can be specifiedas well. See Filtering Read API results for more information.

• order_by (string): If sorted results are desired, specify the name of an attribute of the appropriate table to orderthe results by (e.g. quantity for balance objects, if you called get_balances). If left blank, the list ofresults will be returned unordered.

• order_dir (string): The direction of the ordering. Either ASC for ascending order, or DESC for descendingorder. Must be set if order_by is specified. Leave blank if order_by is not specified.

• start_block (integer): If specified, only results from the specified block index on will be returned

• end_block (integer): If specified, only results up to and including the specified block index on will be returned

• status (string/list): return only results with the specified status or statuses (if a list of status strings is supplied).See the list of possible statuses. Note that if null is supplied (the default), then status is not filtered. Alsonote that status filtering can be done via the filters parameter, but doing it through this parameter is moreflexible, as it essentially allows for situations where OR filter logic is desired, as well as status-based filtering.

• limit (integer): (maximum) number of elements to return. Can specify a value less than or equal to 1000. Formore results, use a combination of limit and offset parameters to paginate results.

• offset (integer): return results starting from specified offset

Special Parameters:

• show_expired (boolean): used only for get_orders. When false, get_orders don’t return orders whichexpire next block.

Return:

A list of objects with attributes corresponding to the queried table fields.

Examples:

• To get a listing of bets, call get_bets. This method will return a list of one or more bet objects .

• To get a listing all open orders for a given address like 1Ayw5aXXTnqYfS3LbguMCf9dxRqzbTVbjf, you couldcall get_orders with the appropriate parameters. This method will return a list of one or more order objects.



Notes:

• Please note that the get_balances API call will not return balances for VIA itself. It only returns balancesfor XCH and other Clearinghouse assets. To get VIA-based balances, use an existing system such as Insight,blockr.io, or blockchain.info.

get_asset_info

get_asset_info(assets)

Gets information on an issued asset.

Parameters:

• assets (list): A list of one or more asset for which to retrieve information.

Return:

null if the asset was not found. Otherwise, a list of one or more objects, each one with the followingparameters:

• asset (string): The name of the asset itself

• owner (string): The address that currently owns the asset (i.e. has issuance rights to it)

• divisible (boolean): Whether the asset is divisible or not

• locked (boolean): Whether the asset is locked (future issuances prohibited)

• total_issued (integer): The quantity of the asset issued, in total

• callable (boolean): If the asset is callable or not

• call_date (integer): The call date, as an epoch timestamp

• call_price (float): The call price

• description (string): The asset’s current description

• issuer (string): The asset’s original owner (i.e. issuer)

get_asset_names

get_asset_names()

Returns a list of all existing Clearinghouse assets.

Parameters: None

Return:

A list of existing Clearinghouse asset names.

get_messages

get_messages(block_index)

Return message feed activity for the specified block index. The message feed essentially tracks all clearinghouseddatabase actions and allows for lower-level state tracking for applications that hook into it.

Parameters:

• block_index (integer): The block index for which to retrieve activity.



Return:

A list of one or more messages if there was any activity in the block, otherwise [] (empty list).

get_messages_by_index

get_messages_by_index(message_indexes)

Return the message feed messages whose message_index values are contained in the specified list of messageindexes.

Parameters:

• message_indexes (list): An array of one or more message_index values for which the cooresponding mes-sage feed entries are desired.

Return:

A list containing a message for each message found in the specified message_indexes list. If nonewere found, [] (empty list) is returned.

get_xch_supply

get_xch_supply()

Gets the current total quantity of XCH in existance (i.e. quantity created via proof-of-burn, minus quantity destroyedvia asset issuances, etc).

Parameters:

None

Return:

The quantity of XCH currently in existance.

get_block_info

get_block_info(block_index)

Gets some basic information on a specific block.

Parameters:

• block_index (integer): The block index for which to retrieve information.

Return:

If the block was found, an object with the following parameters:

• block_index (integer): The block index (i.e. block height). Should match what was specified forthe block_index input parameter).

• block_hash (string): The block hash identifier

• block_time (integer): A UNIX timestamp of when the block was processed by the network



get_blocks

get_blocks(block_indexes)

Gets block and message data (for each block) in a bulk fashon. If fetching info and messages for multiple blocks, thisis much quicker than using multiple get_block_info() and get_messages() calls.

Parameters:

• block_index (list): A list of 1 or more block indexes for which to retrieve the data.

Return:

A list of objects, one object for each valid block index specified, in order from first block index to last.Each object has the following parameters:

• block_index (integer): The block index (i.e. block height). Should match what was specified forthe block_index input parameter).

• block_hash (string): The block hash identifier

• block_time (integer): A UNIX timestamp of when the block was processed by the network

• _messages (list): A list of one or more messages if there was any activity in the block, otherwise [](empty list).

get_running_info

get_running_info()

Gets some operational parameters for clearinghoused.

Parameters:

None

Return:

An object with the following parameters:

• db_caught_up (boolean): true if clearinghoused block processing is caught up with the Viacoinblockchain, false otherwise.

• viacoin_block_count (integer): The block height on the Viacoin network (may not necessarily bethe same as last_block, if clearinghoused is catching up)

• last_block (integer): The index (height) of the last block processed by clearinghoused

• clearinghoused_version (float): The clearinghoused program version, expressed as a float, such as0.5

• last_message_index (integer): The index (ID) of the last message in the clearinghoused mes-sage feed

• running_testnet (boolean): true if clearinghoused is configured for testnet, false if configuredon mainnet.

• db_version_major (integer): The major version of the current clearinghoused database

• db_version_minor (integer): The minor version of the current clearinghoused database



1.1.5 Action/Write API Function Reference

sign_tx

sign_tx(unsigned_tx_hex, privkey=None)

Sign a transaction created with the Action/Write API.

Parameters:

• tx_hex (string): A hex-encoded raw transaction (which was created via one of the create_ calls).

• privkey (string): The private key in WIF format to use for signing the transaction. If not provided, the privatekey must to be known by the viacoind wallet.

Return:

A hex-encoded signed raw transaction ready to be broadcast with the broadcast_tx call.

broadcast_tx

broadcast_tx(signed_tx_hex)

Broadcast a signed transaction onto the Viacoin network.

Parameters:

• signed_tx_hex (string): A hex-encoded signed raw transaction (which was created via one of the create_calls and signed with sign_tx method).

Return:

The created transaction’s id on the Viacoin network, or an error if the transaction is invalid for any reason.

create_bet

create_bet(source, feed_address, bet_type, deadline, wager, counterwager, target_value=0.0, leverage=5040, en-coding=’auto’, pubkey=null, allow_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Issue a bet against a feed.

Parameters:

• source (string): The address that will make the bet.

• feed_address (string): The address that host the feed to be bet on.

• bet_type (integer): 0 for Bullish CFD, 1 for Bearish CFD, 2 for Equal, 3 for NotEqual.

• deadline (integer): The time at which the bet should be decided/settled, in Unix time.

• wager (integer): The quantity of XCH to wager.

• counterwager (integer): The minimum quantity of XCH to be wagered against, for the bets to match.

• target_value (float): Target value for Equal/NotEqual bet

• leverage (integer): Leverage, as a fraction of 5040

• encoding (string): The encoding method to use, see this section for more info.

• pubkey (string): The pubkey hex string. Required if multisig transaction encoding is specified for a key externalto clearinghoused‘s local wallet. See this section for more info.



• allow_unconfirmed_inputs (boolean): Set to true to allow this transaction to utilize unconfirmed UTXOs asinputs.

• fee (integer): If you’d like to specify a custom miners’ fee, specify it here (in satoshi). Leave as default forclearinghoused to automatically choose.

• fee_per_kb (integer): The fee per kilobyte of transaction data constant that clearinghoused uses whendeciding on the dynamic fee to use (in satoshi). Leave as default unless you know what you’re doing.

Return:

The unsigned transaction, as an hex-encoded string. See this section for more information.

create_broadcast

create_broadcast(source, fee_fraction, text, value=0, encoding=’multisig’, pubkey=null, al-low_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Broadcast textual and numerical information to the network.

Parameters:

• source (string): The address that will be sending (must have the necessary quantity of the specified asset).

• fee_fraction (float): How much of every bet on this feed should go to its operator; a fraction of 1, (i.e. .05 isfive percent).

• text (string): The textual part of the broadcast.

• timestamp (integer): The timestamp of the broadcast, in Unix time.

• value (float): Numerical value of the broadcast.






Return:


create_viapay

create_btcpay(order_match_id, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false, fee=null,fee_per_kb=10000)

Create and (optionally) broadcast a VIApay message, to settle an Order Match for which you owe VIA.

Parameters:

• order_match_id (string): The concatenation of the hashes of the two transactions which compose the ordermatch.








Return:


create_burn

create_burn(source, quantity, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false, fee=null,fee_per_kb=10000)

Burn a given quantity of VIA for XCH (only possible between blocks 278310 and 283810).

Parameters:

• source (string): The address with the VIA to burn.

• quantity (integer): The quantity of VIA to burn (1 VIA maximum burn per address).






Return:


create_callback

create_callback(offer_hash, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false, fee=null,fee_per_kb=10000)

Make a call on a callable asset (where some whole or part of the asset is returned to the issuer, on or after the asset’scall date).

Parameters:

• source (string): The callback source address. Must be the same address as the specified asset’s owner.

• fraction (float): A floating point number greater than zero but less than or equal to 1, where 0% is for a callbackof 0% of the balance of each of the asset’s holders, and 1 would be for a callback of 100%). For example, 0.56would be 56%. Each holder of the called asset will be paid the call price for the asset, times the number of unitsof that asset that were called back from them.








Return:


create_cancel

create_cancel(offer_hash, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false, fee=null,fee_per_kb=10000)

Cancel an open order or bet you created.

Parameters:

• offer_hash (string): The transaction hash of the order or bet.






Return:


create_dividend

create_dividend(source, quantity_per_unit, asset, dividend_asset, encoding=’multisig’, pubkey=null, al-low_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Issue a dividend on a specific user defined asset.

Parameters:

• source (string): The address that will be issuing the dividend (must have the ownership of the asset which thedividend is being issued on).

• asset (string): The asset that the dividends are being rewarded on.

• dividend_asset (string): The asset that the dividends are paid in.

• quantity_per_unit (integer): The quantity of XCH rewarded per whole unit of the asset.








Return:


create_issuance

create_issuance(source, asset, quantity, divisible, description, callable=false, call_date=null, call_price=null,transfer_destination=null, lock=false, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false,fee=null, fee_per_kb=10000)

Issue a new asset, issue more of an existing asset, lock an asset, or transfer the ownership of an asset (note that youcan only do one of these operations in a given create_issuance call).

Parameters:

• source (string): The address that will be issuing or transfering the asset.

• quantity (integer): The quantity of the asset to issue (set to 0 if transferring an asset).

• asset (string): The asset to issue or transfer.

• divisible (boolean): Whether this asset is divisible or not (if a transfer, this value must match the value specifiedwhen the asset was originally issued).

• callable (boolean): Whether the asset is callable or not.

• call_date (integer): The timestamp at which the asset may be called back, in Unix time. Only valid for callableassets.

• call_price (float): The price per unit XCH at which the asset may be called back, on or after the specifiedcall_date. Only valid for callable assets.

• description (string): A textual description for the asset. 52 bytes max.

• transfer_destination (string): The address to receive the asset (only used when transferring assets – leave setto null if issuing an asset).

• lock (boolean): Set to true if this asset should be locked with this API call. Only valid if the asset is notalready locked. To keep as-is, set this to false, or simply do not specify it.








Return:


create_order

create_order(source, give_asset, give_quantity, get_asset, get_quantity, expiration, fee_required=0,fee_provided=0, encoding=’multisig’, pubkey=null, allow_unconfirmed_inputs=false, fee=null,fee_per_kb=10000)

Issue an order request.

Parameters:

• source (string): The address that will be issuing the order request (must have the necessary quantity of thespecified asset to give).

• give_quantity (integer): The quantity of the asset to give.

• give_asset (string): The asset to give.

• get_quantity (integer): The quantity of the asset requested in return.

• get_asset (string): The asset requested in return.

• expiration (integer): The number of blocks for which the order should be valid.

• fee_required (integer): The miners’ fee required to be paid by orders for them to match this one; in VIA;required only if buying VIA (may be zero, though). If not specified or set to null, this defaults to 1% of theVIA desired for purchase.

• fee_provided (integer): The miners’ fee provided; in VIA; required only if selling VIA (should not be lowerthan is required for acceptance in a block). If not specified or set to null, this defaults to 1% of the VIA forsale.






Return:


create_send

create_send(source, destination, asset, quantity, encoding=’multisig’, pubkey=null, al-low_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Send XCH or a user defined asset.



Parameters:


• destination (string): The address to receive the asset.

• quantity (integer): The quantity of the asset to send.

• asset (string): The asset to send.






Return:


create_rps

create_rps(source, possible_moves, wager, move_random_hash, expiration, encoding=’multisig’, pubkey=null,allow_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Open a Rock-Paper-Scissors (RPS) like game.

Parameters:


• possible_moves (integer): The number of possible moves. Must be an odd number greater or equal than 3.

• wager (integer): The quantity of XCH to wager.

• move_random_hash (string): A 32 bytes hex string (64 chars): sha256(sha256(random+move)). Where ran-dom is 16 bytes random number.

• expiration (integer): The number of blocks for which the game should be valid.






Return:




create_rpsresolve

create_rpsresolve(source, move, random, rps_match_id, encoding=’multisig’, pubkey=null, al-low_unconfirmed_inputs=false, fee=null, fee_per_kb=10000)

Resolve a Rock-Paper-Scissors game.

Parameters:


• move (integer): The selected move.

• random (string): A 16 bytes hex string (32 chars) used to generate the move_random_hash value.

• rps_match_id (string): The concatenation of the hashes of the two transactions which compose the rpsmatch.


• pubkey (string): The pubkey hex string. Required if multisig transaction encoding is specified for a keyexternal to clearinghoused‘s local wallet. See this section for more info.

• allow_unconfirmed_inputs (boolean): Set to true to allow this transaction to utilize unconfirmedUTXOs as inputs.

• fee (integer): If you’d like to specify a custom miners’ fee, specify it here (in satoshi). Leave as defaultfor clearinghoused to automatically choose.

• fee_per_kb (integer): The fee per kilobyte of transaction data constant that clearinghoused useswhen deciding on the dynamic fee to use (in satoshi). Leave as default unless you know what you’redoing.

Return:


do_{table}

do_{entity}(VARIABLE)

This method is a simplified alternative to the appropriate create_ method. Instead of returning just an unsigned rawtransaction, which you must then sign and broadcast, this call will create the transaction, then sign it and broadcast itautomatically.

{entity} must be one of the following values: bet, broadcast, viapay, burn, callback, cancel,dividend, issuance, order, send, rps, rpsresolve.

For example: do_bet, do_burn, do_dividend, etc are all valid API methods.

Parameters:

• privkey (string): The private key in WIF format to use for signing the transaction. If not provided, the privatekey must to be known by the viacoind wallet.

• The other parameters for a given do_ method are the same as the corresponding create_ call.

Return:

The created transaction’s id on the Viacoin network, or an error if the transaction is invalid for any reason.



1.1.6 Objects

The API calls documented can return any one of these objects.

Balance Object

An object that describes a balance that is associated to a specific address:

• address (string): The address that has the balance

• asset (string): The ID of the asset in which the balance is specified

• quantity (integer): The balance of the specified asset at this address

Bet Object

An object that describes a specific bet:

• tx_index (integer): The transaction index

• tx_hash (string): The transaction hash

• block_index (integer): The block index (block number in the block chain)

• source (string): The address that made the bet

• feed_address (string): The address with the feed that the bet is to be made on

• bet_type (integer): 0 for Bullish CFD, 1 for Bearish CFD, 2 for Equal, 3 for Not Equal

• deadline (integer): The timestamp at which the bet should be decided/settled, in Unix time.

• wager_quantity (integer): The quantity of XCH to wager

• counterwager_quantity (integer): The minimum quantity of XCH to be wagered by the user to bet against thebet issuer, if the other party were to accept the whole thing

• wager_remaining (integer): The quantity of XCH wagered that is remaining to bet on

• odds (float):



• expiration (integer): The number of blocks for which the bet should be valid

• fee_multiplier (integer):

• validity (string): Set to “valid” if a valid bet. Any other setting signifies an invalid/improper bet

Bet Match Object

An object that describes a specific occurance of two bets being matched (either partially, or fully):

• tx0_index (integer): The Viacoin transaction index of the initial bet

• tx0_hash (string): The Viacoin transaction hash of the initial bet

• tx0_block_index (integer): The Viacoin block index of the initial bet

• tx0_expiration (integer): The number of blocks over which the initial bet was valid

• tx0_address (string): The address that issued the initial bet



• tx0_bet_type (string): The type of the initial bet (0 for Bullish CFD, 1 for Bearish CFD, 2 for Equal, 3 for NotEqual)

• tx1_index (integer): The transaction index of the matching (counter) bet

• tx1_hash (string): The transaction hash of the matching bet

• tx1_block_index (integer): The block index of the matching bet

• tx1_address (string): The address that issued the matching bet

• tx1_expiration (integer): The number of blocks over which the matching bet was valid

• tx1_bet_type (string): The type of the counter bet (0 for Bullish CFD, 1 for Bearish CFD, 2 for Equal, 3 forNot Equal)

• feed_address (string): The address of the feed that the bets refer to

• initial_value (integer):

• deadline (integer): The timestamp at which the bet match was made, in Unix time.



• forward_quantity (integer): The quantity of XCH bet in the initial bet

• backward_quantity (integer): The quantity of XCH bet in the matching bet

• fee_multiplier (integer):

• validity (string): Set to “valid” if a valid order match. Any other setting signifies an invalid/improper ordermatch

Broadcast Object

An object that describes a specific occurance of a broadcast event (i.e. creating/extending a feed):




• source (string): The address that made the broadcast

• timestamp (string): The time the broadcast was made, in Unix time.

• value (float): The numerical value of the broadcast

• fee_multiplier (float): How much of every bet on this feed should go to its operator; a fraction of 1, (i.e. .05 isfive percent)

• text (string): The textual component of the broadcast

• validity (string): Set to “valid” if a valid broadcast. Any other setting signifies an invalid/improper broadcast

VIAPay Object

An object that matches a request to settle an Order Match for which VIA is owed:






• source (string):

• order_match_id (string):

• validity (string): Set to “valid” if valid

Burn Object

An object that describes an instance of a specific burn:




• source (string): The address the burn was performed from

• burned (integer): The quantity of VIA burned

• earned (integer): The quantity of XPC actually earned from the burn (takes into account any bonus quantitys, 1VIA limitation, etc)

• validity (string): Set to “valid” if a valid burn. Any other setting signifies an invalid/improper burn

Cancel Object

An object that describes a cancellation of a (previously) open order or bet:




• source (string): The address with the open order or bet that was cancelled

• offer_hash (string): The transaction hash of the order or bet cancelled


Debit/Credit Object

An object that describes a account debit or credit:




• address (string): The address debited or credited

• asset (string): The asset debited or credited

• quantity (integer): The quantity of the specified asset debited or credited



Dividend Object

An object that describes an issuance of dividends on a specific user defined asset:




• source (string): The address that issued the dividend

• asset (string): The asset that the dividends are being rewarded on

• quantity_per_unit (integer): The quantity of XCH rewarded per whole unit of the asset


Issuance Object

An object that describes a specific occurance of a user defined asset being issued, or re-issued:




• asset (string): The asset being issued, or re-issued

• quantity (integer): The quantity of the specified asset being issued

• divisible (boolean): Whether or not the asset is divisible (must agree with previous issuances of the asset, ifthere are any)

• issuer (string):

• transfer (boolean): Whether or not this objects marks the transfer of ownership rights for the specified quantityof this asset

• validity (string): Set to “valid” if a valid issuance. Any other setting signifies an invalid/improper issuance

Order Object

An object that describes a specific order:




• source (string): The address that made the order

• give_asset (string): The asset being offered

• give_quantity (integer): The quantity of the specified asset being offered

• give_remaining (integer): The quantity of the specified give asset remaining for the order

• get_asset (string): The asset desired in exchange

• get_quantity (integer): The quantity of the specified asset desired in exchange

• get_remaining (integer): The quantity of the specified get asset remaining for the order



• price (float): The given exchange rate (as an exchange ratio desired from the asset offered to the asset desired)

• expiration (integer): The number of blocks over which the order should be valid

• fee_provided (integer): The miners’ fee provided; in VIA; required only if selling VIA (should not be lowerthan is required for acceptance in a block)

• fee_required (integer): The miners’ fee required to be paid by orders for them to match this one; in VIA;required only if buying VIA (may be zero, though)

Order Match Object

An object that describes a specific occurance of two orders being matched (either partially, or fully):

• tx0_index (integer): The Viacoin transaction index of the first (earlier) order

• tx0_hash (string): The Viacoin transaction hash of the first order

• tx0_block_index (integer): The Viacoin block index of the first order

• tx0_expiration (integer): The number of blocks over which the first order was valid

• tx0_address (string): The address that issued the first (earlier) order

• tx1_index (integer): The transaction index of the second (matching) order

• tx1_hash (string): The transaction hash of the second order

• tx1_block_index (integer): The block index of the second order

• tx1_address (string): The address that issued the second order

• tx1_expiration (integer): The number of blocks over which the second order was valid

• forward_asset (string): The asset exchanged FROM the first order to the second order

• forward_quantity (integer): The quantity of the specified forward asset

• backward_asset (string): The asset exchanged FROM the second order to the first order

• backward_quantity (integer): The quantity of the specified backward asset

• validity (string): Set to “valid” if a valid order match. Any other setting signifies an invalid/improper ordermatch

Send Object

An object that describes a specific send (e.g. “simple send”, of XCH, or a user defined asset):




• source (string): The source address of the send

• destination (string): The destination address of the send

• asset (string): The asset being sent

• quantity (integer): The quantity of the specified asset sent

• validity (string): Set to “valid” if a valid send. Any other setting signifies an invalid/improper send



Message Object

An object that describes a specific event in the clearinghoused message feed (which can be used by 3rd party applica-tions to track state changes to the clearinghoused database on a block-by-block basis).

• message_index (integer): The message index (i.e. transaction index)

• block_index (integer): The block index (block number in the block chain) this event occurred on

• category (string): A string denoting the entity that the message relates to, e.g. “credits”, “burns”, “debits”. Thecategory matches the relevant table name in clearinghoused (see blocks.py for more info).

• command (string): The operation done to the table noted in category. This is either “insert”, or “update”.

• bindings (string): A JSON-encoded object containing the message data. The properties in this object match thecolumns in the table referred to by category.

Callback Object

An object that describes a specific asset callback (i.e. the exercising of a call option on an asset owned by the sourceaddress).




• source (string): The source address of the call back (should be the current owner of the asset)

• fraction (integer): A floating point number greater than zero but less than or equal to 1, where 0% is for a callback of 0%of the balance of each of the asset’s holders, and 1 would be for a callback of 100%). For example, 0.56would be 56%. Each holder of the called asset will be paid the call price for the asset, times the numberof units of that asset that were called back from them.

• asset (string): The asset being called back

• validity (string): Set to “valid” if a valid send. Any other setting signifies an invalid/improper send

Bet Expiration Object

An object that describes the expiration of a bet created by the source address.

• bet_index (integer): The transaction index of the bet expiring

• bet_hash (string): The transaction hash of the bet expiriing

• block_index (integer): The block index (block number in the block chain) when this expiration occurred

• source (string): The source address that created the bet

Order Expiration Object

An object that describes the expiration of an order created by the source address.

• order_index (integer): The transaction index of the order expiring

• order_hash (string): The transaction hash of the order expiriing


• source (string): The source address that created the order



Bet Match Expiration Object

An object that describes the expiration of a bet match.

• bet_match_id (integer): The transaction index of the bet match ID (e.g. the concatenation of the tx0 and tx1hashes)

• tx0_address (string): The tx0 (first) address for the bet match

• tx1_address (string): The tx1 (second) address for the bet match


Order Match Expiration Object

An object that describes the expiration of an order match.

• order_match_id (integer): The transaction index of the order match ID (e.g. the concatenation of the tx0 andtx1 hashes)

• tx0_address (string): The tx0 (first) address for the order match

• tx1_address (string): The tx1 (second) address for the order match


1.1.7 Status

Here the list of all possible status for each table:

• balances: No status field

• bet_expirations: No status field

• bet_match_expirations: No status field

• bet_matches: pending, settled: liquidated for bear, settled, settled: liquidated for bull, settled: for equal, settled:for notequal, dropped, expired

• bets: open, filled, cancelled, expired, dropped, invalid: {problem(s)}

• broadcasts: valid, invalid: {problem(s)}

• viapays: valid, invalid: {problem(s)}

• burns: valid, invalid: {problem(s)}

• callbacks: valid, invalid: {problem(s)}

• cancels: valid, invalid: {problem(s)}

• credits: No status field

• debits: No status field

• dividends: valid, invalid: {problem(s)}

• issuances: valid, invalid: {problem(s)}

• order_expirations: No status field

• order_match_expirations: No status field

• order_matches: pending, completed, expired



• orders: open, filled, canceled, expired, invalid: {problem(s)}

• sends: valid, invalid: {problem(s)}

1.1.8 API Changes

This section documents any changes to the clearinghoused API, for version numbers where there were API-levelmodifications.

9.32.0

Summary: API framework overhaul for performance and simplicity

• “/api” with no trailing slash no longer supported as an API endpoint (use “/” or “/api/” instead)

• We now consistently reject positional arguments with all API methods. Make sure your API calls do not use po-sitional arguments (e.g. use {“argument1”: “value1”, “argument2”: “value2”} instead of [”value1”, “value2”])

9.24.1

Summary: New API parsing engine added, as well as dynamic get_ method composition in api.py:

• Added sql API method

• Filter params: Added LIKE, NOT LIKE and IN

9.25.0

• new do_* methods: like create_*, but also sign and broadcast the transaction. Same parameters as create_*,plus optional privkey parameter.

backwards incompatible changes

• create_*: accept only dict as parameters

• create_bet: bet_type must be a integer (instead string)

• create_bet: wager and counterwager args are replaced by wager_quantity andcounterwager_quantity

• create_issuance: parameter lock (boolean) removed (use LOCK in description)

• create_issuance: parameter transfer_destination replaced by destination

• DatabaseError: now a DatabaseError is returned immediately if the clearinghoused database is behind the back-end, instead of after fourteen seconds




CHAPTER 2

Indices and tables

• genindex

• modindex

• search

29

Documents

clearinghoused Documentation - Read the Docs · clearinghoused Documentation, Release 0.1.0 ... By default, clearinghoused will listen on port 7300 (if on mainnet) or port 17300 (on