View source for Asset exchange

<languages />
<translate>
{{#seo:
|title=Asset exchange
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, Asset exchange
|description=Asset exchange feature allows the following operation with assets: Issue, transfer, increase and delete shares, paying dividends, and exchange
}}
[[Category:Features]]
__TOC__
==Description==  <!--T:17-->
This page covers the decentralized Asset Exchange within the Ardor multichain platform. Before jumping into the details, we can start with an example that shows one of the possible uses of this feature. 

<!--T:18-->
In the words of ''BCNext (developer of the [https://nxtplatform.org Nxt blockchain]):''
{|border="0"
 |<blockquote>''I want to run a business.  I issue an asset (let's call it Krusty Krab tokens - KKT). I set the quantity of KKT to 1000.  I announce that I sell KKT for 20 NXT each and pay 5 NXT monthly interest within the next 6 months.  I create an ask order -- 1000 KKT for 20,000 NXT.''  
''You create a transaction that sends me 500 NXT for 25 KKT.  It's up to you what to do with your 25 KKT (you can place an ask order and sell them for 27 NXT) but each month I will check the blockchain to see who owns KKT.  And I will send 5 NXT for each KKT to those who own them.''
</blockquote>
 |}

==Accessing the Asset Exchange== <!--T:19--> 

<!--T:10-->
Ardor has the decentralized asset exchange feature since its deployment in production (the 1st of January of 2018)
If you do not know how to install the Ardor client, check out the [[Getting_started|getting started]] page or the [[common problems and resolutions]] page in case you are having problems.

==The Interface==  <!--T:20-->
With the server running, access the Ardor interface of your client by visiting http://localhost:27876/ (or https://localhost:27876/ if you have enabled SSL). On the sidebar, select a child chain that has the asset exchange enabled (e.g.: Ignins), click the menu ''Asset Exchange'', this will give you access to the following options:

<!--T:11-->
[[File:AE_menu.PNG|frame|left]]
{|
|'''Asset Exchange''': This tab gives you access to the Asset Exchange itself. To observe an asset click the "Add asset" button and enter either the Asset ID or ID of the issuing account. Assets of your interest will be listed on the left. By selecting an asset, further information is provided: a description, buy and sell orders, the quantity, etc.
|-
|'''Trade History''': This page will list all the assets traded by your account: both those bought by you and those you sold from the exchange.
|-
|'''Transfer History''': This page will list all the assets transferred and received by your account.
|-
|'''Quantity Change History''': This page will list the quantity change history of your assets.
|-
|'''My Assets''': This page will list all the assets in your possession: both those issued by you and those you bought from the exchange.
|-
|'''Open Orders''': Here is provided a list of all your orders, notably the assets you are either trying to sell or to buy. It also allows you to cancel them.
|-
|'''Approval Request''': Approval request for transactions related to your assets, see [[Asset_control|Asset control]]
|-
|'''Issue Asset''': A window will pop up allowing you to issue your own assets into the exchange.
|}<br /><br /><br /><br />

===Asset Exchange menu=== <!--T:21--> 

<!--T:22-->
By default, the Asset Exchange does not list any assets. You will have therefore to add the assets (using the ''Add Asset'' button) you are interested in, manually, yourself. For this purpose websites that rank the assets in meaningful ways (by volume, by the number of trades, etc) and that offer specific filters are starting to appear. In the future, you will be able to load asset lists in bulk instead of having to load them one by one. If you find yourself on the page of an asset, a ''Bookmark this Asset'' button will appear that will allow you to keep track of it.

<!--T:23-->
Remind always to check that the asset id you are adding correspond with the legit asset:

<!--T:24-->
* Asset names '''are not''' unique, asset ids '''are''' unique

<!--T:25-->
'''Note:''' you can only add assets to the list if you are using the browser in normal mode. If you are in incognito (or equivalent) then any added list will disappear once you close the browser window. In the future, more portable systems will be implemented.

<!--T:26-->
[[File:Asset_Exchange.PNG|thumb|none|border|630px|the Asset Exchange available within the client.]]
{|
|This is the main menu for the Asset Exchange, it is fundamentally organized in two areas.
|-
|
:*a list with all the assets you are tracking.
:*an interface that allows interaction with these assets.
|-
|If you own tokens for an asset, it will appear in yellow on the side list.
|-
|By selecting an asset, the interface area will automatically display the corresponding information. This includes the amount of tokens that have been created ''("quantity")'', how divisible is the token ''("asset decimals")'', a brief description of the asset, who created the asset ''("account")'' and the asset identifier ''("asset ID")''. These informations are crucial, in fact the asset names are '''''non-unique''''. What this means is that there can be multiple assets that have the same name. 
|-
|The cost of issuing an asset will be charged in child-chain tokens corresponding value of 100 Ardor, see [[Create_Transaction#Create Transaction Request|Create Transaction Request]]  should discourage people from spamming the exchange with assets whose only purpose is confusion and abuse. Without entering this worst-case scenario, it is reasonable to assume that perfectly legit users may create assets of the same name. Therefore a good degree of vigilance before buying is always beneficial.
|-
| To buy an asset, follow these simple steps:
|-
|
:1. select the asset from the list.
:2. '''quantity''': define how many tokens you are interested in buying.
:3. '''price''': set how much you are willing to pay.
::'''ATTENTION''': "price" refers to the cost of a unit of tokens. So, by entering 10, you are willing to pay 10 child chain tokens ''per'' asset token.
:4. '''fee''': define the fee, see fees in [[Create_Transaction#Create Transaction Request|Create Transaction Request]] or click on the "Calculate" button, which will automatically calculate the current network fee.
:5. press buy.
:6. it will ask you for your passphrase and finally press ''buy asset''.
|}

===My Assets menu===  <!--T:27-->
[[File:My_assets.PNG|none|thumb|border|600px|Transfer Asset]]

<!--T:28-->
In this menu all your confirmed assets will be displayed, this includes the assets you issued and those you obtained through trading.

====Transfer asset==== <!--T:29-->
Assets are also transferable, the procedure is very simple:
#Under '''''My Assets''''', find the asset you wish to transfer.
#Click ''transfer''.
#Complete the fields as follows.

<!--T:30-->
[[File:Transfer_asset.PNG|border|thumb|400px|left]]

{|
|-
|'''RECIPIENT''': the account you wish to transfer the assets to.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|'''COMMENT''': you can attach a brief commentary to the transfer. when marking "Add a message"
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
:''Characters allowed'': it can contain any Unicode characters but should be URL-encoded. Maximum length of 1000 characters. 
|-
|'''QUANTITY''': specify the amount of assets you wish to transfer.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Limits'': there is no upper limit, you can transfer all your assets. The minimum amount you can transfer depends on the nature of the asset. In particular, it depends on what has been defined as ''decimals''. For 0 decimals, the minimum would be 1 token. For 1 decimal, it would be 0.1 tokens and so on.
|-
|'''FEE''': set the fee you are willing to pay for the transaction.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Limits'': there is no upper limit. However the minimum fee is 0.01 tokens, see [[Create_Transaction#Create Transaction Request|fees]].
|-
|'''SECRET PASSPHRASE''': enter '''''your''''' passphrase.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|
|-
|'''VOUCHER''': see [[Transaction_Vouchers#Usage_Example|Transaction Voucher]].
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
|}
====Delete shares==== <!--T:31-->
The asset issuer can delete assets shares, the procedure is very simple:
#Under '''''My Assets''''', find the asset you wish to delete shares.
#Click ''Delete Shares''.
#Complete the fields as follows.

<!--T:15-->
[[File:DeleteShares.png|border|thumb|400px|left]]

<!--T:16-->
{|
|-
|'''QUANTITY''': specify the amount of shares you wish to delete.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|'''COMMENT''': you can attach a brief commentary to the transfer. when marking "Add a message"
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
:''Characters allowed'': it can contain any Unicode characters but should be URL-encoded. Maximum length of 1000 characters. 
|-
|'''FEE''': set the fee you are willing to pay for the transaction.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Limits'': there is no upper limit. However the minimum fee is 0.01 tokens, see [[Create_Transaction#Create Transaction Request|fees]].
|-
|'''SECRET PASSPHRASE''': enter '''''your''''' passphrase.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|
|-
|'''VOUCHER''': see [[Transaction_Vouchers#Usage_Example|Transaction Voucher]].
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
|}


====Increase shares==== <!--T:32-->
The asset issuer can increase assets shares, the procedure is very simple:
#Under '''''My Assets''''', find the asset you wish to increase shares.
#Click ''Increase Shares''.
#Complete the fields as follows.

<!--T:33-->
[[File:IncreaseShares.png|border|thumb|400px|left]]

<!--T:34-->
{|
|-
|'''QUANTITY''': specify the amount of shares you wish to increase.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|'''COMMENT''': you can attach a brief commentary to the transfer. when marking "Add a message"
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
:''Characters allowed'': it can contain any Unicode characters but should be URL-encoded. Maximum length of 1000 characters. 
|-
|'''FEE''': set the fee you are willing to pay for the transaction.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Limits'': there is no upper limit. However the minimum fee is 0.01 tokens, see [[Create_Transaction#Create Transaction Request|fees]].
|-
|'''SECRET PASSPHRASE''': enter '''''your''''' passphrase.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|
|-
|'''VOUCHER''': see [[Transaction_Vouchers#Usage_Example|Transaction Voucher]].
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
|}


===Open Orders menu===  <!--T:35-->
Under this menu you can see all your orders that are currently open.

<!--T:36-->
[[File:Open_orders_menu.PNG|none|border|thumb|630px]]

<!--T:37-->
'''What to keep in mind:'''
* You can cancel any order you made. ''However''
** The process is not instantaneous. Your cancel order is broadcasted to the network, your order may get accepted before you can manage to cancel it.
** The process of canceling an order is a transaction, meaning it involves a fee of 0.01 Tokens, see: [[Create_Transaction#Create Transaction Request|fees]].
** An order in the process of being canceled will appear in red under your Open Orders menu.
* In this image, the sell order I am willing to sell the shares (5 IGnis).
** The TESTAPPROV asset refers to an asset named TESTAPPROV, whose ID is 14572747084550678873, and that has been created by me.  

===Issue Asset menu===  <!--T:38-->
Under this menu, you can issue assets yourself. These will be publicly available on the Asset Exchange where they can be traded for Ignis and vice-versa. 

<!--T:39-->
The following window will pop up:

<!--T:40-->
'''NOTE: as the warning mentions, when you issue your asset you will not be able to modify any of the fields, ever. The reason why it is imperative to make sure all the information entered is correct.'''
[[File:Issue_asset.PNG|border|thumb|400px|left]]


<!--T:41-->
{|
|-
|'''ASSET NAME''': the name of the asset you intend to issue. This is also the name announced to other traders, allowing them to find this asset.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': you cannot issue an unnamed asset.
|-
|
:''Names are non-unique'': multiple assets can be issued with the same name. 
:'''Note''': for this reason, pay attention to what you are buying or selling!
|-
|
:''Length'': between 3 and 10 characters.
|-
|
:''Characters allowed'': uppercase letters, lowercase letters, and numbers.
|-
|'''DESCRIPTION''': in this field, you can briefly describe the asset being issued.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory. 
|-
|
:''Characters allowed'': it can contain any Unicode characters but should be URL-encoded. Maximum length of 1000 characters. 
|-
|'''QUANTITY''': specify how many tokens you intend to create.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Must be a whole number''
|-
|'''DECIMALS''': this field defines the divisibility of the token. As an example, by defining 2 decimals, the minimum amount of tokens you can sell or buy is 0.01.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Limits'': you can set from 0 to, at most, 8 decimals. The latter corresponds to the minimum of 0.00000001 tokens.
|-
|'''FEE''': define the fee related to issuing the asset. To avoid spam on the Asset Exchange, the IGNIS equivalent of 100 ARDR are the minimum required to issue an asset.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|'''DEADLINE''': how long you are willing to wait before the request gets automatically deleted.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|
:''Expressed in hours''
|-
|'''PASSPHRASE''': the asset belongs to the person issuing it. Therefore it is required to enter your own passphrase. It will not be broadcasted.
|-
|
:'''Note''': assets belong to the person that creates them, but they can be bought, sold, and transferred.
|-
|'''''Constraints''''':
|-
|
:''Mandatory'': this field is mandatory.
|-
|-
|'''VOUCHER''': see [[Transaction_Vouchers#Usage_Example|Transaction Voucher]].
|-
|'''''Constraints''''':
|-
|
:''Optional'': this field is optional.
|-
|
|}

==FAQ==  <!--T:42-->
See more: 
* [[Asset_Exchange#Asset_Exchange_Operations|API Asset Exchange Operations]]

==External Links== <!--T:43-->
* [http://nxter.org/how-to-use-nxt-asset-exchange-tutorial/ Nxter Magazine: How to Use the Nxt Asset Exchange] 
* [https://www.youtube.com/watch?v=0ZtFYEeHk8o Asset Exchange Introductory Video]
</translate>