ArdorDocs - User contributions [en]

Getting started

2026-05-14T17:33:17Z

Petko: Removed link to https://www.ardor.world/faucet_ardor/ and substituted the link to https://ardorforum.org/ with https://talk.jelurida.com/t/ardor-tesnet-tokens/1325

{{#seo:
|title=Getting started
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki
|description=Ardor documentation homepage - Getting started with the Ardor platform
}}
<languages />
<translate>


[https://www.jelurida.com/ardor Ardor] is a blockchain-as-a-service multi-chain platform that evolved from the time-tested and energy-efficient [https://www.jelurida.com/nxt Nxt blockchain]. The Ardor mainnet launched on 01 January 2018. Through this documentation, you will learn all about the extensive capabilities of the Ardor platform. Begin developing your knowledge by reading about each of Ardor’s distinctive [[Features]] or consider trying the technology yourself by following some [[Basic tutorials|Basic Tutorials]]. For developers, documentation is provided for each of Ardor’s more than 250 [[API|APIs]] that can be used to quickly and cost-effectively deploy dApps and smart contracts that integrate your business processes with the Ardor blockchain. Check this site regularly for new content and updates as additional features are released.

==Download Ardor== 


Before we begin, if you haven’t already done so, you may wish to check that you have the correct (usually most recent) version of [https://adoptopenjdk.net/ Java] installed on your computer. You can use any compatible Java available for your platform. The minimum required version is Java 8. The recommended version is Java 11. We usually test with OpenJDK 14.


To start with Ardor/[https://www.jelurida.com/ignis Ignis], you must first download the client, also known as a "wallet", on your machine. The client is distributed as a binary package for the following platforms:


[[File:200px-Windowslogo.jpg|100px|frameless|link=Getting_started#Windows]][[File:200px-AppleLogo.jpg|100px|frameless|link=Getting_started#MacOS]][[File:200px-Linuxlogo.jpg|130px|frameless|link=Getting_started#Linux]][[File:200px-RaspberryPi_Logo.png|100px|frameless|link=Getting_started#Raspberry_Pi]][[File:200px-Android.png|100px|frameless|link=Getting_started#Android]]

==Client Installation == 


<div class="accordion" id="accordion-win">
<accordion parent="accordion-win" heading="===Windows===">
#Download the Windows installer for the latest official Ardor Client {{NRSVersion}} from {{NRSWinInstaller}}. If you want to test the latest testnet-only version {{NRSVersionExperimental}} that includes the snapshotting and pruning functionality, refer to the Universal Zip Package.
#Ardor's Windows client comes as an .exe file. After downloading it, you can verify its integrity by performing an [[Faq#How_to_verify_authenticity_of_Ardor_installations|integrity check]]
#Run the installer and follow the instructions on the screen. Note that you can select either the testnet or mainnet during installation, if further details are needed please follow the [[How_to_download_the_ardor_client_wallet|step-by-step guide]]. Once installed icons will be created by default in your desktop and Start Menu.
#You can now run the Ardor software by clicking on the Ardor icon. After a few seconds, the Ardor wallet will open in its own window.
#If you already have created an Ardor account, click on 'Returning User' to introduce your passphrase. If you need to create your Ardor account, [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
</accordion>
</div>


<div class="accordion" id="accordion-mac">
<accordion parent="accordion-mac" heading="===MacOS===">


====Install and run the Ardor Client====
#Download the latest client version {{NRSVersion}} from or {{NRSDownload}} the experimental {{NRSVersionExperimental}} from {{NRSExperimentalDownload}}.
#Download the signature from https://www.jelurida.com/ardor-client.zip.asc (https://www.jelurida.com/ardor-client-experimental.zip.asc for the experimental version) to the same directory where the zip was downloaded. To verify the signature, open a terminal, navigate to the downloads directory and run the command</br><code>gpg --with-fingerprint ardor-client.zip.asc</code></br>
##In case of error that the gpg command is not found, install GnuPG:
###<code>brew install gpg</code>
###If brew is missing, follow the instructions at https://brew.sh to install it first.
##In case of error <code>gpg: Can't check signature: No public key</code>:
###Download the Jelurida GPG key from https://www.jelurida.com/sites/default/files/jelurida.gpg
###Import it to GnuPG:<br/><code>gpg --import jelurida.gpg</code>
#Unzip <code>ardor-client.zip</code> to a directory of your choice.
#Start Ardor by executing the file <code>ArdorMacOS.command</code>. A terminal window will open and an Ardor icon will appear in the status menu.
====Common problems====
* In case an error <code>Unable to locate a Java Runtime</code> is displayed in the terminal window, follow the instructions and install Java from http://www.java.com
* At first run Ardor may need about a minute to initialize the database. Messages like "Loading public keys" are displayed in the terminal. Wait for the initialization to complete and do not close the window.
* If the Desktop Application is inaccessible (the "Show Desktop Application" button is disabled in the status menu), it's likely due to missing JFX libraries in the Java installation. It's recommended to use the "Open Wallet in Browser" option from the menu instead. Alternatively, you can download JFX from https://openjfx.io/ and extract it into a directory named <code>javafx-sdk</code> under the directory where Ardor was extracted in step 3.
====Deprecated instructions for using the installer in older Ardor versions====
#Download the Mac installer for the latest official Ardor Client {{NRSVersion}} from {{NRSMacInstaller}}. After downloading, [[Faq#How_to_verify_authenticity_of_Ardor_installations|verify its signature]]. After downloading, check the SHA256 hash of the package for security. If you want to test the latest testnet-only version {{NRSVersionExperimental}} that includes the snapshotting and pruning functionality, refer to the Universal Zip Package.
#Open the MacOS terminal.
#Navigate to the Mac installer you just have downloaded.
#Execute the command <code>sudo xattr -c ardor-installer-{{NRSVersion}}.dmg</code>. Type your passphrase
#Run the installer package (Ardor's Mac installer comes packaged in .dmg format) and follow the instructions on screen
## Select the language [[File:MacInstaller_2.png|none|border|400px]]
## Click on 'Next' to begin with the installation [[File:MacInstaller_3.png|none|border|400px]]
## Accept the terms of the license agreement [[File:MacInstaller_4.png|none|border|400px]]
## Select the installation path [[File:MacInstaller_5.png|none|border|400px]]
## Select the packages you want to install [[File:MacInstaller_6.png|none|border|400px]]
## Check the options [[Tutorial_on_setting_up_the_ardor_testnet|See the tutorial for setting up the Ardor testnet]] [[File:MacInstaller_7.png|none|border|400px]]
## Once installed, click on finish [[File:MacInstaller_9.png|none|border|400px]]
#You can now run the Ardor software clicking on the "ardor.app" in Applications. If you already have created a Ardor account, click in 'Returning User' to introduce your passphrase. If you need to create your Ardor account, [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
</accordion>
</div>


<div class="accordion" id="accordion-linux">
<accordion parent="accordion-linux" heading="===Linux===">


Here is the guide to installing the Ardor Client on a Linux 64-bit platform. 32-bit installation instructions are very similar; you just might need to download the 32-bit version of Java instead of the 64-bit one.


You can use these instructions on your Linux VPS as well.

====Set up Java==== 
You can skip this step if you already have Java installed. Otherwise, you can install it via your distribution repository doing the following (for Ubuntu/Debian builds):


<pre>sudo apt update
sudo apt install openjdk-11-jre-headless</pre>


You can also use `openjdk-8-jre-headless` or any other Java 8+ compatible version.

====Install and run the Ardor Client==== 

=====Using the Unix installer===== 
You can execute the Unix installer executable compatible with most Linux distributions from [https://www.jelurida.com/ardor-client.sh ardor-client.sh] and follow the instructions.


<pre>wget https://www.jelurida.com/ardor-client.sh
sh ardor-client.sh
</pre>

=====Using the Universal Zip Package===== 
You can follow the more generic instructions as explained below:
#Change to your home folder and download the latest client (version {{NRSVersion}} or the experimental {{NRSVersionExperimental}}):<br /><code>cd ~</code><br /><code>wget {{NRSDownload}}</code><code>wget https://www.jelurida.com/ardor-client.zip.asc</code> and verify that the signature is correct: <code>gpg --with-fingerprint ardor-client.zip.asc</code>
#Unzip it:<br /><code>unzip ardor-client.zip</code><br /><code>cd ardor</code>

Using the experimental version is as follows:

<br /><code>cd ~</code><br /><code>wget {{NRSExperimentalDownload}}</code><code>wget https://www.jelurida.com/ardor-client-experimental.zip.asc</code> and verify that the signature is correct: <code>gpg --with-fingerprint ardor-client-experimental.zip.asc</code>

=====Run the Ardor client===== 


#Now it's time to start the software. You may start it by executing <code>./run.sh</code> or <code>./run.sh --daemon</code> for running the Ardor node in the background, which you will find in the ardor directory. The server will be active as soon as you see in the window a text similar to this: <br/><code>Ardor server {{NRSVersion}} started successfully.</code> This shell window will be running the Ardor server and print all the Ardor log messages, so it needs to stay running!<br />
#Open http://localhost:27876/ from a web browser to access the Ardor Client. Please note that, if it's the first time you run Ardor in your machine, the Ardor blockchain will need to be downloaded until it is up to date. Depending on your network connection speed, this may take a few hours. The Ardor Client will show you a progress bar as the blockchain downloads. Now you can visit the [[How_to_create_an_account_on_the_Ardor_Platform|click here for instructions to Create a New Ardor Account]].
#*NOTE: If you've installed the client on a dedicated server or VPS, you should change "localhost" to your Server/VPS IP.
</accordion>
</div>


<div class="accordion" id="accordion-pi">
<accordion parent="accordion-pi" heading="===Raspberry Pi===">


For installing the Ardor client on a Raspberry pi, you can refer to the description of [https://medium.com/@mrv_89306/solar-powered-ardor-blockchain-node-aa680a976c50 an implementation with the Ardor client powered by solar panels]
</accordion>
</div>


<div class="accordion" id="accordion-android">
<accordion parent="accordion-android" heading="===Android===">
Click on the [[Android_Full_Node|Android Full Node installation guide]] and follow the instructions.
</accordion>
</div>

<div class="accordion" id="accordion-docker">
<accordion parent="accordion-docker" heading="===Docker Image===">
There is an Ardor Node Docker image available in the Docker Hub: [https://hub.docker.com/r/jeluridaswiss/ardor Ardor Docker Image]. Deploying this image requires knowledge about docker and management of containers. Please refer to the tutorial [[Deploying_the_Ardor_Node_Docker_Image|Deploying the Ardor Node Docker Image]]
</accordion>
</div>

==='''Need help?'''=== 
Need help during the download or development process? Contact us on the [https://talk.jelurida.com Ardor & Nxt Technical forum], and take a look at the [[Faq|FAQ]]. You can also reach us by opening a ticket in our [https://desk.zoho.eu/portal/jelurida/home helpdesk]

==Lightweight Contracts documentation== 
Lightweight Contracts represent a framework for developing a layer of automation on top of the existing Ardor APIs, refer to the official documentation to read more about this feature:


<div class="noprint" style="float:none; border:1px solid black;width:95%;background-color:#F6F0F0;padding:2px;">
{| cellspacing="0"
| style="padding-left:50px;"| '''[[Lightweight_Contracts|Lightweight Contracts documentation]]'''
|}</div>
<noinclude>

==Login to Ardor== 
There are different ways to log in to Ardor to create an account. It is explained in the [[Login_Page_Tutorial|Login Page Tutorial]]

==Getting your first ARDR== 


With the Ardor client installed, it is now time to start transacting. To do that, we need to get some tokens, be it ARDR, IGNIS, or any other child chain. The Ardor mainnet is live and actual tokens are in circulation across numerous major exchanges.


Note the tokens we will be using in the next examples are from testnet. These tokens are not traded in exchanges and have no monetary value -- they exist only as a convenience for developers and those willing to experiment with the features.


To receive testnet tokens, ask for them in the [https://talk.jelurida.com/t/ardor-tesnet-tokens/1325 forum] or contact us on the [https://ardornxt.slack.com slack] channel #helpdesk.

=== Exchanges === 


* [https://www.jelurida.com/ardor/explorers Currently trading ARDR]

==Next steps== 


Learn how to use the Ardor platform by following the [[Basic_tutorials|basic tutorials]] or start reading about Ardor's extensive built-in [[Features]].

=== Staking === 


The process of staking in Ardor is called [[Forging_(f)|Forging]]. Once you have more than 1.000 ARDR you can start forging, thus earning the transaction fees when a block is generated by your node.


Furthermore, you can also opt-in the [[Node_Reward_Program|Node Reward Program]] by just setting up a node with both the API and peer ports open to the Internet and a public and static IP address.

==Feedback and errors== 


If an error in this documentation is found, we would love to be aware to correct it as soon as possible. Please write a question to [mailto:info@jelurida.com info@jelurida.com] and we will take care.


<accordion parent="accordion" heading="Latest documentation changes and updates">
{{Special:SimpleChanges/days=150,limit=100,bots,hideminor,namespace=0}}
</accordion>
</translate>

Exchange Integration of Assets

2021-01-12T07:40:20Z

Petko:

<languages />
<translate>
{{#seo:
|title=Exchange Integration of Assets
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, tutorials, advanced tutorials, how to, Exchange Integration of Assets, Asset exchange
|description=Guide that explains how to integrate Ignis Assets into a centralized exchange
}}
[[Category:Advanced_guides]]
__TOC__
==Introduction== 


The following page explains how to integrate [[Asset_exchange#Accessing_the_Asset_Exchange|Assets token]], the tokens of the Asset Exchange, into a crypto-currency exchange.


In addition to the explanation covered by the section [[Exchange_Integration_Ignis#Dealing_with_Assets_and_Currencies|Dealing with Assets and Currencies]], this guide gets deeper in the explanation and provides examples for such integration of Assets.


In this document we use assets to refer to the token assets, Ignis to refer to the main child chain and Ardor to refer to the platform in general.

==Prerequisites== 


Ardor node running 24/7 with fully synchronized blockchain.


It is also recommended to setup a testnet node for QA and testing purposes.


All examples in this document:


Use the 26876 testnet port. The mainnet port is 27876.


Use ARDOR accounts.


It is also supported numeric account ids from which the ARDOR account ids are derived. These numeric account ids has no error correction therefore we recommend that you'll never use it as any typo will lead to lost user funds.


An asset typically represents a share in an entity. Each asset is identified by the unique 64-bit transaction id of the asset issuance transaction, has a name, which is not necessarily unique, has a specific number of shares, which can be deleted and increased in the future. Asset quantities are divisible to between 0 to 8 decimal positions as specified by the asset issuance transaction.

==Accepting Asset Deposits or Transfers== 


Unlike Bitcoin's throw away addresses, Ardor addresses are somewhat expensive to maintain.


Each Ardor address and public key combination are maintained forever in the blockchain, however maintaining a completely empty account is less costly than maintaining an account with a non-zero balance.


Due to this, we do not recommend using a throwaway Ardor address per deposit as creating these addresses require higher fees payment.


Instead, we recommend creating at most one deposit address per user or even direct all deposits to the same address and maintain user identity using a message attached to the deposit transaction.


Deposits can be accepted using one of the following approaches:


# '''Message Based Deposits''' - Asset deposits are transferred to a single address, the user is identified by an attached message.
# '''Address per User''' - Asset is deposited to a new deposit address for each user.


Regardless of the method being used, always use a strong passphrase for the deposit account and protect the deposit account with a public key before accepting deposits.

===Message-Based Deposits=== 


Each transfer transaction of the assets can have an attached message, either in plain text or encrypted. This allows you to identify the user using a unique identifier such as the customer number or order number specified in the message. Which identifier you will use in the message to connect the payment to a specific user account is up to you and won’t be discussed in this document.


To monitor your account for new incoming payments, the [[Accounts#Get_Blockchain_Transactions|GetBlockchainTransactions]] API call is used with the parameter executedOnly=true (the executedOnly parameter filters out phased transactions which did not execute).


The API call takes the following parameters:


* '''chain''' - child chain identifier, use 2 for Ignis. It should be only accepted asset deposit and issue asset withdrawal on a specific child chain, preferably Ignis


* '''account''' - deposit account id

* '''timestamp''' - if specified, transactions should be newer than this block timestamp

* '''type''' - the type of transaction. For asset transfers this should be 2

* '''subtype''' - the transaction subtype. For asset transfers this should be 1

* '''firstIndex''' - for pagination purposes

* '''lastIndex''' - for pagination purposes

* '''executedOnly''' - set to true to filter out phased transactions which did not execute

To monitor a specific account for payment transactions use the following URL:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getBlockchainTransactions&
chain=2&
account=ARDOR-X8ZN-WUJ2-SXY3-FBUYC&
type=2&
subtype=1&
executedOnly=true&
includePhasingResult=true
</syntaxhighlight>


This is the JSON response:


<syntaxhighlight lang="json">
{
"requestProcessingTime": 4,
"transactions": [
{
"signature": "83b5f9f782b62ff25664010e2c11027944b9a850bff4aaf90ec247d9558e2f0b08d10d46ccc2466c4a834b74679a7f33b78954f0acac7c452c92d5f5a601c15a",
"transactionIndex": 1,
"type": 2,
"fxtTransaction": "7657558407516871755",
"phased": false,
"ecBlockId": "5657621390974142748",
"signatureHash": "1c86a29fd48f2727b1e9c59a61fb40d9124988ab4af4d468784b38cf9f024a00",
"attachment": {
"version.AssetTransfer": 1,
"quantityQNT": "1",
"asset": "9483630659743578360"
},
"senderRS": "ARDOR-X8ZN-WUJ2-SXY3-FBUYC",
"subtype": 1,
"amountNQT": "0",
"recipientRS": "ARDOR-3YLS-D9NM-84LE-2H9HP",
"block": "3243082432540174808",
"blockTimestamp": 69733158,
"deadline": 15,
"timestamp": 69733160,
"height": 4202046,
"senderPublicKey": "df21142bd38c04bd5c5c342c6ca36802f9de89b75b2a0a8cbd32d29dca481e5c",
"chain": 2,
"feeNQT": "1500000",
"confirmations": 195,
"fullHash": "a0566aa12fef8ee4688c82e613408f84dc5be5827470b93518dab12a424b5bd2",
"version": 1,
"sender": "15382970207090678772",
"recipient": "773756405444311640",
"ecBlockHeight": 3214500
},
... more transactions ...
]
}
</syntaxhighlight>


Loop over this array of transactions and process the transactions one by one. Note that this response includes both incoming and outgoing payment transactions. You should filter out your own (outgoing) assets transfers by looking at the senderRS account address.

The important information of a transaction response is:


* '''senderRS''' - the sender’s account id


* '''confirmations''' - the number of confirmations


* '''asset''' - The asset identifier

* '''quantityQNT''' - the asset QNT transferred in [[General_notes#Quantity_Units|Quants]]

* '''attachment.message''' - optional, an attached plain text message

* '''attachment.encryptedMessage''' - optional, an attached encrypted message

* '''timestamp''' - the time the transaction was made, in seconds since the genesis block

* '''blockTimestamp''' - the time of the block since the genesis block

* '''confirmations''' - number of confirmations received for the block in which the transaction is included


For most transactions, waiting for 10 confirmations should be enough. However, for transactions with large amount, special attention should be given to the transaction timestamp and deadline parameters, since blocks can become orphaned and transactions canceled as a result in case their deadline has passed.


When genesis time + timestamp + deadline * 60 is bigger than transaction.blockTime + 23 hours, a transaction can be accepted when the confirmations count reaches 10.


For phased transactions i.e. phased=true, verify that approved=true then check the block in which the transaction has executed not the block in which it was initially submitted using the executionHeight field. Another alternative is not to accept phased deposit transactions at all i.e. if phased=true do not credit the transaction, but then you'll have to deal with refunding this transaction manually and document that it is not allowed in the deposit dialog.


If genesis time + transaction.timestamp + transaction.deadline * 60 is smaller than transaction.blockTimestamp + 23 hours, you should wait until the transaction has 720 confirmations before crediting the user’s account. 720 blocks is the maximum depth a blockchain reorganization can go. By waiting that long, you ensure the transaction is always included. Transactions that only required 10 confirmations will be put back in the blockchain automatically due to their longer deadline time.


The default deadline in the client is 24 hours, which means that in 99% of the cases only 10 confirmations will be necessary before crediting the user’s account.


Genesis time for the Ardor blockchain is 1st of Jan, 2018 00:00:00 UTC.


To identify the user, you must look at the transaction attachment. If a plain text message is included, attachment.message is set and attachment.messageIsText is set to “true” (as string).


If an encrypted message was attached instead, attachment.encryptedMessage should exist instead. This is not just a string, but an object and contains two keys; data and nonce.


To decrypt the message use the [[Messages#Decrypt_From|decryptFrom]] API.


This API call takes the following parameters:


* '''account''' - account id that sent you the encrypted message

* '''data''' - the encrypted message data extracted from transaction.attachment.encryptedMessage.data

* '''nonce''' - the encrypted message nonce extracted from transaction.attachment.encryptedMessage.nonce

* '''decryptedMessageIsText''' - set to “true" if the message you’re trying to decrypt is text

* '''secretPhrase''' - passphrase of the account that received the encrypted message i.e. the deposit account

Example: to decrypt the message send the following request parameters:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=decryptFrom&
secretPhrase=[passphrase from account ARDOR-EVHD-5FLM-3NMQ-G46NR]&
account=ARDOR-XK4R-7VJU-6EQG-7R335&
data=9fd7a70625996990a4cf83bf9b1568830f557136044fb3209dd7343eec2ed96ec312457c4840dabaa8cbd8c1e9b8554b&
nonce=650ef2a8641c19b9fd90a9ef22a2d50af90aa3b0de3d7a28b5ff2ad193369e7a&
decryptedMessageIsText=true
</syntaxhighlight>


The response is:
<syntaxhighlight lang="json">
{
"decryptedMessage": "test message",
"requestProcessingTime": 2
}
</syntaxhighlight>


After you have decrypted the message, you can now credit the customer account with the asset amount specified in transaction.attachment.quantityQNT.


Note: If you wish you can show pending deposits to the user for the transaction which did not yet reach the required number of confirmations.


You could also check for new transactions since a specific block by specifying the last block’s timestamp+1 as the timestamp parameter:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?requestType=getBlockchainTransactions&...&timestamp=83099831
</syntaxhighlight>


To get the last block timestamp, you would look at the last processed transaction blockTimestamp, or use the getBlockchainStatus API described in the account-based deposits section.

====Preventing users from accidentally sending assets without message. ''nrs_recipient_ui_options'' properties functionality====
Refer to guide [[Account Setup for Message-based Deposits]] to set up the property <code>nrs_recipient_ui_options</code> that prevents users to send funds without a message.

===Account-Based Deposits=== 


As discussed above, Ardor accounts are an expensive resource and should not be treated like disposable Bitcoin addresses.


For account-based deposits, you basically generate a new random passphrase for each user. The passphrase should be very strong and at least 35 characters long.


Once you have this passphrase, you can get the account id and public key via the [[Accounts#Get_Account_Id|getAccountId]] API call.


* '''secretPhrase''' - account passphrase


* '''publicKey''' - account public

Note that you only need to specify one of the above parameters, not both. So in our case, you just specify the secretPhrase parameter.


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getAccountId&
secretPhrase=1234
</syntaxhighlight>


The response is:


<syntaxhighlight lang="json">
{"accountRS":"ARDOR-5WUN-YL5V-K29F-F43EJ","publicKey":"fddcda69eeca58e5d783ad1032d080d2758a4e427881b6a4a6fe43d9e7f4ac34", "account":"15577989544718496596"}
</syntaxhighlight>


On your site’s deposit page, you will need to show the account address extracted from the accountRS field i.e. '''ARDOR-5WUN-YL5V-K29F-F43EJ'''


If the account hasn’t yet had any incoming transactions, you will also need to display the publicKey to the user.


The public key doesn’t have to be displayed any more after it has had its first incoming transaction.


When a user sends funds to a new account, it needs to add the public key, so that an announcement of this key can be made. Once done, this is no longer needed.


Accounts without a public are only protected only by the 64-bit account address, not by the 256 public key.


Tracking New Account-Based Deposits


To track new asset deposits, it’s easiest to simply inspect all transactions in a block to see if any of them are to account addresses you generated. An alternative method would be to use the getBlockchainTransactions API detailed in message-based deposits.


(This is to be done in a loop)


Use the [[Server_info#Get_Blockchain_Status|getBlockchainStatus]] API to check if there is a new block. This API call has no parameters.


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?requestType=getBlockchainStatus
</syntaxhighlight>

The response includes lastBlock (block id) and numberOfBlocks (the height).


If numberOfBlocks is different from the previous execution of this API request, one or more new blocks have been generated. The transactions from the block which now has 10 confirmations have to be fetched. You should save in your database the height of the last block you processed.


Use the new getExecutedTransactions API to load all transactions executed at a given height either directly for non-phased transactions or indirectly for phased transactions applied at this height.


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getExecutedTransactions&
chain=2&
height=25117
</syntaxhighlight>

For each of the resulting transactions, see if the recipientRS field corresponds to one of the deposit accounts you generated for your users. If so, this is an incoming payment. Credit the user’s internal asset balance and send the money to your hot wallet.


Similarly to message-based deposits handling, special attention should be given to the transaction timestamp and deadline parameters


After all transactions of this block have been checked, see if you’ve processed the previous block before or not (previousBlock).


If not, traverse through the previous blocks chain until you reach the last processed block.

==Withdrawing / Sending Assets== 


When a user wants to withdraw assets to a specific account, you ask him for the account id he wants to withdraw to. When you receive this account id, you must first check if that account has a public key attached to it or not (i.e. if it’s new or not).


To do this, you must use the [[Accounts#Get_Account_Public_Key|getAccountPublicKey]] API. It takes 1 parameter, account.


* '''account''' - account you want the public key of


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getAccountPublicKey&
account=ARDOR-C6L6-UQ5W-RBJK-AWDSJ
</syntaxhighlight>

If the account does not have a public key, you will get this error:


<syntaxhighlight lang="json">
{ "errorCode": 5, "errorDescription": "Unknown account" }
</syntaxhighlight>

When you get this error, you should also ask the user for his public key or at least display a warning explaining the risk of using an account without a public key.


When you have both the account id and public key, you can verify that they are correct by comparing the given account id with the account id generated by the public key using the getAccountId API call.


* '''publicKey''' - account public key


We want to calculate only by publicKey so our request looks like this:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getAccountId&
publicKey=28f56a81e0f8555b07eacffd0e697b21cbbbdf3cf620db14522732b763564f13
</syntaxhighlight>


You’ll get back a response like this:


<syntaxhighlight lang="json">
{"accountRS":"ARDOR-C6L6-UQ5W-RBJK-AWDSJ","publicKey":"28f56a81e0f8555b07eacffd0e697b21cbbbdf3cf620db14522732b763564f13","requestProcessingTime":0,"account":"9827273118446850628"}
</syntaxhighlight>


Now compare the response accountRS to the account id the user provided. If they are equal, you can go ahead and perform the withdrawal.


Sending assets is done via the [[Asset_Exchange#Transfer_Asset|Transfer Asset]] API call. The relevant parameters are:


* '''chain''' - the chain identifier, use 2 for Ignis. It should be only accepted asset deposit and issue asset withdrawal on a specific child chain, preferably Ignis


* '''recipient''' - recipient’s account address

* '''asset''' - identifier of the asset being transferred


* '''quantityQNT''' - the asset QNT transferred in [[General_notes#Quantity_Units|Quants]]

* '''feeNQT''' - transaction fee for the transaction in NQT. In most cases set to -1 to let the receiving node calculate the minimum fee

* '''secretPhrase''' - sender’s account passphrase

* '''deadline''' - deadline for the transaction in minutes. Should be set to the maximum value of 1440

* '''recipientPublicKey''' - recipient public key as provided by the user, only needed if the user account has no public key yet (on first transaction)

At the moment (Ardor v2.0.4e) the recipientPublicKey is optional, however not specifying it, puts the user's funds at risk. The recipientPublicKey is mandatory in case you like to attach an encrypted message to the withdrawal transaction of a new account.


This request has to be sent using '''HTTP POST'''.


The response should look like this if everything went OK:


<syntaxhighlight lang="json">
{ "fullHash": “10788f7ad3f145b5209da6145327d7fed869…”, ... a lot more information ... }
</syntaxhighlight>

If there’s an error, you may get a response such as this (other errors may apply):


<syntaxhighlight lang="json">
{ "errorCode": 5, "errorDescription": "Unknown account" }
</syntaxhighlight>


A correctly executed response should always contain the "transaction" field which represents the newly created transaction id.

====Adding a Message To a (asset transfer) Transaction==== 


You can add messages to any kind of transaction.


To do so, specify the below parameters in your request:


* '''message''' - plain text message.

* '''messageIsText''' - should be set to the string “true” if text.

* '''messageToEncrypt''' - plain text message that should be encrypted.

* '''messageToEncryptIsText''' - should be set to the string "true" if text.

In case you want to attach a plain text message, specify the message, and set messageIsText to “true”.

If the account to which funds are withdrawn is configured for message-based deposits, you should prevent the user from sending funds without a message, or with incorrectly formatted message. See the [[Account_Setup_for_Message-based_Deposits|Account Setup for Message-based Deposits]] guide.


If you want to attach an encrypted message that can only be read by the recipient, specify messageToEncrypt and set messgaeToEncryptIsText to “true”.


Note that these are not mutually exclusive, you can add both a plain text and encrypted message in the same transaction.


Allowing the user to add a message on your withdrawal page is recommended so that you can coordinate with other services that use a message-based deposit system.

===Hot and Cold Wallets=== 


You should not keep all of your user’s deposits in a single hot wallet. A hot wallet is a wallet for which the passphrase is stored somewhere on your server, so that you can send money from it.


Instead, you should have both a hot and cold wallet. The cold wallet should hold most of the coins and not be accessible from any of your servers. Ideally, you’d manually send from your cold wallet to your hot wallet when more coins are needed for day-to-day operations.


So the best thing to do is to have money sent to your cold wallet address, and then send out to your hot wallet manually when needed.

===Additional information=== 

====Account Format==== 


The account id is stored internally as a 64 bit signed long variable. When used in APIs it is usually returned as both unsigned number represented as string and using alphanumeric Reed-Solomon representation starting with "ARDOR-" prefix.


For example: ARDOR-ER8M-SYV3-R7EK-EUF3L


In API request parameters and response JSON, you will find both representations, the numeric representation is typically displayed as account, sender, recipient. The alphanumeric representation is typically displayed as accountRS, senderRS, recipientRS (simply always add “RS”).
RS stands for Reed-Solomon. This form of address improves reliability by introducing redundancy that can detect and correct errors when entering and using Nxt account ID’s.

====Asset and currency QNT amounts==== 


Each Asset and Currency (generally referred to as "Holding") has a specific number of decimal positions to which this holding is divisible.
API requests and responses always expect the holding quantity to be specified as a whole number without decimal positions. We refer to this value as QNT.
For example, when transferring 12.34 units of holding XYZ which has 4 decimal positions, specify the QNT value as 123400.

====Minimum Fee and bundling==== 


All outgoing transactions require a fee paid in the child chain token. Since 0 is now a valid fee value for child chains, all CreateTransaction APIs will accept it, instead of using it as a request for the server to calculate
and use the minimum fee. To let the server calculate the child transaction fee, a value of feeNQT=-1 should be used, and a new feeRateNQTPerFXT parameter must be supplied, to indicate the exchange rate to use when calculating the fee (since minimum fees can only be calculated in the parent chain token ARDR). If feeRateNQTPerFXT is also set to -1, the server will query the currently known bundlers rates for this child chain, also subject to the minBundlerBalanceFXT limit on effective bundler account balance, and use the best one for the fee calculation.


A transaction fee in ARDR varies depending on the status of the recipient account, transferAsset to a new account will charge a higher fee than transferAsset to an existing account so don't make any assumption about the ARDR fee the bundler will have to pay to bundle your transactions, unless you check first if the recipient account is new.
One way to do this is to invoke the getAccount API on the recipient account and check for errorCode 5 in the response, then predict the fee according to the current minimum fee specifications.
A more robust approach is to submit the transaction when setting the broadcast parameter to false then read the minimumFeeFQT field from the response which indicates the minimum required fee in ARDR the bundler will pay for this transaction.


As bundlers' rates cannot be trusted blindly, the transaction will not be broadcasted in this case, the returned transaction JSON including the fees calculated should be reviewed by the user. The bundler rate used will be returned in the bundlerRateNQTPerFXT JSON field, -1 if no bundlers are known for the chain."
The way the Ardor wallet works is that it first asks the user to calculate the fee then provides the best available fee from all bundlers as default fee which can be changed manually.


Alternatively, you can develop your own bundling filter which will only bundle your withdrawal transactions.
You will need to implement an interface with a single Java method or reuse the available PersonalBundler.java example.


<syntaxhighlight lang="java">
public interface Filter {
boolean ok(Bundler bundler, ChildTransaction childTransaction);
}
</syntaxhighlight>


You then register this bundling filter using the following property in your nxt.properties file:
# When running Bundlers, only bundle transactions that satisfy this filter.
# Filter class must implement the nxt.Bundler.Filter interface, see
# nxt.addons.PersonalBundler for an example.
# nxt.bundlingFilter=nxt.addons.PersonalBundler


Our recommendation is that if you know that all your withdrawal transactions will be issued from a single account, also perform the bundling using this account and use the provided PersonalBundler filter to bundle only your own withdrawal transactions and ignore other transactions. This will provide you full control over the bundling process for your asset withdrawals, you will pay the fee in ARDR and receive back the child chain tokens (IGNIS in most cases) you charge from your customers as transaction fees. You can regularly adjust the bundling rate based on the IGNIS per ARDR rate on your exchange.
Bundler is started or updated using the startBundler API. Also see [[Bundling]]

====Account Properties Bundler==== 


A more flexible approach is to use the Account Property Bundler in order to designate several accounts whose transactions your bundler will bundle.


Add the property nxt.bundlingFilter=nxt.addons.AccountPropertyBundler to your nxt.properties file


Decide which account will perform the bundling (probably your Ardor deposit account which is guaranteed to contain Ardor to pay the fees), from this account submit a setAccountProperty transaction (better do it from the wallet under the dashboard --> Account Properties menu) set the recipient account to the account which will submit the asset transfer transactions and the name of the property to "bundling", the value of the property is unimportant at the moment. Submit these transactions from the IGNIS chain, chain "2".


Wait for the set account properties transactions to confirm, then start a bundler from the property setter account (Ardor account) and set the bundling parameters as usual. In most cases, it makes sense to allow 0 fee transactions but it's not required.


As a result, only transactions submitted by accounts on which you set the "bundling" property will be bundled by your bundler.
</translate>

Exchange Integration Ardor

2021-01-12T07:39:29Z

Petko:

<languages />
<translate>
{{#seo:
|title=Exchange Integration Ardor
|titlemode=replace
|keywords=ardor learning hub, ardor documentation, blockchain, proof of stake, ardor, ignis, jelurida, development, ardor wiki, wiki, tutorials, advanced tutorials, how to, Exchange Integration Ardor
|description=This guide explains how to integrate Ardor into a currency exchange platform
}}
[[Category:Advanced_guides]]
__TOC__
==Introduction== 


The following page explains how to integrate Ardor into a currency exchange platform

==Prerequisites== 


Ardor node running 24/7 with fully synchronized blockchain.


It is also recommended to setup a testnet node for QA and testing purposes.


All examples in this document:


Use the 26876 testnet port. The mainnet port is 27876.


Ardor also supports numeric account ids from which the ARDOR account ids are derived. These numeric account ids have no error correction therefore we recommend that you'll never use it as any typo will lead to lost user funds.

==Accepting Deposits== 


Unlike Bitcoin's throw away addresses, Ardor addresses are somewhat expensive to maintain.


Each Ardor address and public key combination are stored forever in the blockchain, however, maintaining a completely empty account is less costly than maintaining an account with non zero balance.


Due to this, we do not recommend using a throw-away Ardor address per deposit since creating these addresses need to pay a higher fee.


Instead, we recommend creating at most one deposit address per user or even direct all deposits to the same address and maintain user identity using a message attached to the deposit transaction.


Deposits can be accepted using one of the following approaches:


1. Message-Based Deposits - Ardor deposits are sent to a single address, the user is identified by an attached message.


2. Address per User - Ardor is deposited to a new deposit address for each user.


When using both methods, always use a strong passphrase for the deposit account.

===Message-Based Deposits=== 


Each payment transaction in Ardor can have an attached message, either in plain text or encrypted. This allows you to identify the customer using an identifier provided by the exchange that the user will enter when making a deposit.


Which identifier you will use in the message to connect the payment to a specific user account is up to you and won’t be discussed in this document.


To monitor your account for new incoming payments, the [[Accounts#Get_Blockchain_Transactions|GetBlockchainTransactions]] API call is used


The API call takes the following parameters:


* '''chain''' - set to 1 to identify the Ardor chain


* '''account''' - deposit account id

* '''timestamp''' - if specified, transactions should be newer than this block timestamp

* '''type''' - the type of transaction. For Ardor payments this should be -2

* '''subtype''' - the transaction subtype. For payments, this should be 0 as well


* '''numberOfConfirmations''' - only load transactions with this number of confirmations

* '''firstIndex''' - for pagination purposes

* '''lastIndex''' - for pagination purposes

To monitor a specific account for payment transactions use the following URL:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getBlockchainTransactions&
chain=1&
account=ARDOR-XK4R-7VJU-6EQG-7R335&
type=-2&
subtype=0&
numberOfConfirmations=10
</syntaxhighlight>


This is a sample JSON response (irrelevant fields omitted):


<syntaxhighlight lang="json">
{
"transactions": [
{
"signature": "acbe6720b1a7e13e6af7cdc2dc42e448b5aafb1fa3a481bac08cf150ab9db90842a9d231abb41c280c489f2cca1a122a186048aa6f41dca66663644b6f4e4588",
"transactionIndex": 0,
"type": -2,
"phased": false,
"ecBlockId": "1318911886063902233",
"signatureHash": "a85066e35731f1ee34be7326a16e92cbf703c650d0487b88a947a3c83fe1719e",
"attachment": {
"version.FxtPayment": 0,
"version.PrunablePlainMessage": 1,
"messageIsText": true,
"messageHash": "f8ed492c51010998ab9a8b8909d36cf0e792565e61048cd040fe406c0d519a75",
"message": "{\"chain\":2,\"fullHash\":\"2bf7716b0867c743e3bf630360b852b98dc6559d33a22ede437d690db51fc5a4\"}"
},
"senderRS": "ARDOR-EVHD-5FLM-3NMQ-G46NR",
"subtype": 0,
"amountNQT": "10000000000",
"recipientRS": "ARDOR-XK4R-7VJU-6EQG-7R335",
"block": "4144059555451144178",
"blockTimestamp": 8018267,
"deadline": 1440,
"timestamp": 8018209,
"height": 135271,
"senderPublicKey": "0b4e505972149e7ceb51309edc76729795cabe1f2cc42d87688138d0966db436",
"chain": 1,
"feeNQT": "100000000",
"confirmations": 55607,
"fullHash": "e33ccc4648786cba42bbb052796fb5be45c48e25c3c9b4908b773ff2295272f3",
"version": 1,
"sender": "16992224448242675179",
"recipient": "5873880488492319831",
"ecBlockHeight": 0,
"transaction": "13433244040360115427"
},
{
"signature": "393fc5bf120734468bd2f1d1dfcab6483c32167d6c6a008e4fc386c27985ce02f1e51499900c3c6b3a16e38e21ecd81062e734532b62754b73b2e7e2909dcaa7",
"transactionIndex": 0,
"type": -2,
"phased": false,
"ecBlockId": "7136116332013816990",
"signatureHash": "a1d7c6d14e66572b7a0c2e5567a6ae60420654c8155694d37fbf1e9afa287662",
"attachment": {
"version.FxtPayment": 0
},
"senderRS": "ARDOR-XK4R-7VJU-6EQG-7R335",
"subtype": 0,
"amountNQT": "1000000000000",
"recipientRS": "ARDOR-ZQW8-EKSR-UX8K-CJ6DD",
"block": "17515962222690505699",
"blockTimestamp": 7530374,
"deadline": 15,
"timestamp": 7530360,
"height": 127214,
"senderPublicKey": "112e0c5748b5ea610a44a09b1ad0d2bddc945a6ef5edc7551b80576249ba585b",
"chain": 1,
"feeNQT": "100000000",
"confirmations": 63664,
"fullHash": "2888abfe72b97a3599933de52337578cdb4d77f18fc02c1ceffcc152eb7ad4dc",
"version": 1,
"sender": "5873880488492319831",
"recipient": "11938075473327676294",
"ecBlockHeight": 17000,
"transaction": "3853596334718945320"
}
]
}
</syntaxhighlight>


Loop over this array of transactions and process the transactions one by one. Note that this response includes both incoming and outgoing payment transactions. You should filter out your own (outgoing) payments by looking at the senderRS account address.

The important information of a transaction response is:


* '''chain''' - should always equal 1 to identify Ardor


* '''senderRS''' - the sender’s account id


* '''amountNQT''' - the amount sent in [[API#Quantity_Units_amountNQT.2C_QNT_and_priceNQTPer.28Share.2C_Coin.2C_Unit.2C_etc..29|NQT form]]

* '''attachment.message''' - optional, an attached plain text message

* '''attachment.encryptedMessage''' - optional, an attached encrypted message

* '''timestamp''' - the time the transaction was made, in seconds since the genesis block

* '''blockTimestamp''' - the time of the block since the genesis block

* '''confirmations''' - number of confirmations received for the block in which the transaction is included


For most transactions, waiting for 10 confirmations should be enough. For very large amounts you may want to wait up to 720 which is the maximum possible fork height.


To identify the user, you must look at the transaction attachment. If a plain text message is included, attachment.message is set and attachment.messageIsText is set to “true” (as string).


If an encrypted message was attached instead, attachment.encryptedMessage should exist instead. This is not just a string, but an object and contains two keys; data and nonce.


To decrypt the message use the [[Messages#Decrypt_From|decryptFrom]] API.


This API call takes the following parameters:


* '''account''' - account id that sent you the encrypted message

* '''data''' - the encrypted message data extracted from transaction.attachment.encryptedMessage.data

* '''nonce''' - the encrypted message nonce extracted from transaction.attachment.encryptedMessage.nonce

* '''decryptedMessageIsText''' - set to “true" if the message you’re trying to decrypt is text

* '''secretPhrase''' - passphrase of the account that received the encrypted message i.e. the deposit account

Example: to decrypt the message sent by testnet transaction 12700027308938063138 send the following request parameters:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=decryptFrom&
secretPhrase=[passphrase from account ARDOR-EVHD-5FLM-3NMQ-G46NR]&
account=ARDOR-XK4R-7VJU-6EQG-7R335&
data=9fd7a70625996990a4cf83bf9b1568830f557136044fb3209dd7343eec2ed96ec312457c4840dabaa8cbd8c1e9b8554b&
nonce=650ef2a8641c19b9fd90a9ef22a2d50af90aa3b0de3d7a28b5ff2ad193369e7a&
decryptedMessageIsText=true
</syntaxhighlight>


The response is:
<syntaxhighlight lang="json">
{
"decryptedMessage": "test message",
}
</syntaxhighlight>


After you have decrypted the message, you can now credit the customer account with the amount specified in transaction.amountNQT.


Note: If you wish you can show pending deposits to the user for transactions that did not yet reach the required number of confirmations.


You could also check for new transactions since a specific block by specifying the last block’s timestamp+1 as the timestamp parameter:


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getBlockchainTransactions&
chain=1&
account=ARDOR-XK4R-7VJU-6EQG-7R335&
type=-2&
subtype=0&
timestamp=8018267
</syntaxhighlight>


To get the last block timestamp, you would look at the last processed transaction blockTimestamp, or use the getBlockchainStatus API described in the account-based deposits section.

====Preventing users from accidentally sending ARDR without message. ''nrs_recipient_ui_options'' properties functionality====
Refer to guide [[Account Setup for Message-based Deposits]] to set up the property <code>nrs_recipient_ui_options</code> that prevents users to send funds without a message.

===Account-Based Deposits=== 


As discussed above, Ardor accounts are an expensive resource and should not be treated like disposable Bitcoin addresses.


For account-based deposits, you basically generate a new random passphrase for each user. The passphrase should be very strong and at least 35 characters long.


Once you have this passphrase, you can get the account id and public key via the [[Accounts#Get_Account_Id|getAccountId]] API call.


* '''secretPhrase''' - account passphrase


* '''publicKey''' - account public

Note that you only need to specify one of the above parameters, not both. So in our case, you just specify the secretPhrase parameter.


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getAccountId&
secretPhrase=1234
</syntaxhighlight>


The response is:


<syntaxhighlight lang="json">
{
"accountRS": "ARDOR-5WUN-YL5V-K29F-F43EJ",
"publicKey": "fddcda69eeca58e5d783ad1032d080d2758a4e427881b6a4a6fe43d9e7f4ac34",
"requestProcessingTime": 2,
"account": "15577989544718496596"
}
</syntaxhighlight>


On your site’s deposit page, you will need to show the account address extracted from the accountRS field i.e. '''ARDOR-5WUN-YL5V-K29F-F43EJ'''

====Tracking New Account-Based Deposits==== 


To track new deposits, it’s easiest to simply inspect all transactions in a block to see if any of them are to account addresses you generated. An alternative method would be to use the getBlockchainTransactions API detailed in message-based deposits.


(This is to be done in a loop)


Use the [[Server_info#Get_Blockchain_Status|getBlockchainStatus]] API to check if there is a new block. This API call has no parameters.


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getBlockchainStatus
</syntaxhighlight>


The response includes lastBlock (block id) and numberOfBlocks (the height).


If numberOfBlocks is different from the previous execution of this API request, one or more new blocks have been generated. The transactions from the block which now has 10 confirmations have to be fetched. You should save in your database the height of the last block you processed.


Use the [[Blocks#Get_Block|getBlock]] API to get the block at the height of 10 blocks ago (10 confirmations).


Pass it the numberOfBlocks parameter from the getBlockchainStatus API response after subtracting 11 from this value, since blocks start at height 0


* '''height''' - height of the block, zero-based.


* '''includeTransactions''' - set to true to return the array of transactions included in the block


<syntaxhighlight lang="bash">
http://localhost:26876/nxt?
requestType=getBlock&
height=135271&
includeTransactions=true
</syntaxhighlight>


Loop over the "transactions" array


For each transaction, see if the recipientRS field corresponds to one of the deposit accounts you generated for your users. If so, this is an incoming payment. Credit the user’s internal balance and send the money to your hot wallet.


Similarly, for message-based deposits, special attention should be given to the transaction timestamp and deadline parameters.


After all transactions of this block have been checked, see if you’ve processed the previous block before or not (previousBlock).


If not, traverse through the previous blocks chain until you reach the last processed block.

==Withdrawing / Sending Money== 


When a user wants to withdraw to a specific account, you ask him for the ARDOR account id he wants to withdraw to.


Sending Ardor is done via the [[Accounts#Send_Money|sendMoney]] API call. The relevant parameters are:


* '''chain''' - set to 1 to identify the Ardor chain


* '''recipient''' - recipient’s account address

* '''amountNQT''' - amount of Ardor (in NQT (also called FQT in Ardor) i.e. 1^(10-8))

* '''feeNQT''' - transaction fee for the transaction in NQT. The minimum value is 100000000 FQT (1 Ardor) but if you are withdrawing to a new account you need to pay 2 Ardor (use the getAccount API to check if the account already exists)

* '''secretPhrase''' - sender’s account passphrase

* '''deadline''' - deadline for the transaction in minutes. Should be set to the maximum value of 1440

The sendMoney request has to use HTTP POST.


The response should look like this if everything went OK:


<syntaxhighlight lang="json">
{ "fullHash": “10788f7ad3f145b5209da6145327d7fed869…”, ... a lot more information ... }
</syntaxhighlight>


If there’s an error, you may get a response such as this (other errors may apply):


<syntaxhighlight lang="json">
{ "errorCode": 5, "errorDescription": "Unknown account" }
</syntaxhighlight>


A correctly executed response should always contain the "transaction" field which represents the newly created fullHash field which represents the unique transaction identifier.

====Adding a Message To a (Payment) Transaction==== 


You can add messages to any kind of transaction.


To do so, specify the below parameters in your request:


* '''message''' - plain text message.

* '''messageIsText''' - should be set to the string “true” if text.

* '''messageToEncrypt''' - plain text message that should be encrypted.

* '''messageToEncryptIsText''' - should be set to the string "true" if text.

In case you want to attach a plain text message, specify message, and set messageIsText to "true".

If the account to which funds are withdrawn is configured for message-based deposits, you should prevent the user from sending funds without a message, or with incorrectly formatted message. See the [[Account_Setup_for_Message-based_Deposits|Account Setup for Message-based Deposits]] guide.


If you want to attach an encrypted message that can only be read by the recipient, specify messageToEncrypt and set messgaeToEncryptIsText to “true”.


Note that these are not mutually exclusive, you can add both a plain text and encrypted message in the same transaction.


Allowing the user to add a message on your withdrawal page is recommended so that you can coordinate with other services that use a message-based deposit system.

===Hot and Cold Wallets=== 


You should not keep all of your user’s deposits in a single hot wallet. A hot wallet is a wallet for which the passphrase is stored somewhere on your server, so that you can send money from it.


Instead, you should have both a hot and cold wallet. The cold wallet should hold most of the coins and not be accessible from any of your servers. Ideally, you’d manually send from your cold wallet to your hot wallet when more coins are needed for day-to-day operations.


So the best thing to do is to have money sent to your cold wallet address, and then send out to your hot wallet manually when needed.

===Additional information=== 

====Ardor Account Format==== 


The Ardor account ID is stored internally as a 64 bit signed long variable. When used in APIs it is usually returned as both unsigned number represented as string and using alphanumeric Reed-Solomon representation starting with "ARDOR-" prefix.


For example: '''ARDOR-ER8M-SYV3-R7EK-EUF3L'''


In API request parameters and response JSON, you will find both representations, the numeric representation is typically displayed as account, sender, recipient. The alphanumeric representation is typically displayed as accountRS, senderRS, recipientRS (simply always add “RS”).
RS stands for Reed-Solomon. This form of address improves reliability by introducing redundancy that can detect and correct errors when entering and using Ardor account ID’s.
Therefore always use the RS address format in your user interface.

====ARDR and FQT Amounts==== 


All Ardor amounts should be converted to FQT format (same as NQT) to be used in API calls.
FQT is the name given to 0.00000001 ARDR (or 10^(-8) in mathematical shorthand). The FQT to ARDR ratio is equivalent to the Satoshi to Bitcoin ratio.
Simply put, 1 ARDR is 100000000 FQT, therefore to convert ARDR to FQT, simply multiply by 100000000.

====Minimum Fee==== 


All outgoing transactions require a fee of at least 1 ARDR. In API calls, this must be represented as 100000000 FQT.

====Time Calculations==== 


Genesis time for the Ardor blockchain is 01 JAN, 2018 00:00:00 UTC.
</translate>

File:Account setup for Message-based deposits - 3.jpg

2021-01-11T21:43:43Z

Petko:

File:Start forging dialog.png

2019-10-11T12:25:48Z

Petko:

Start forging dialog

File:Save forging screen.png

2019-10-11T12:17:42Z

Petko:

Save_forging_screen

File:Ardor control screen started sever.png

2019-10-11T11:33:27Z

Petko: Petko uploaded a new version of File:Ardor control screen started sever.png

The control screen of the Ardor app for Android when the server is started

File:Ardor server launcheer.png

2019-10-08T13:41:38Z

Petko:

Ardor Server launcher

File:Android unknown app warning.png

2019-10-08T13:18:15Z

Petko:

Android unknown app warning

File:Ardor Android Configuration Screen.png

2019-09-25T04:26:05Z

Petko:

Configuration screen of Android app

File:Ardor control screen server not started.png

2019-09-23T20:13:14Z

Petko: Petko uploaded a new version of File:Ardor control screen server not started.png

The control screen of the Ardor app for Android before the server is started

Template:BundlerFilters

2019-06-14T09:37:17Z

Petko:

{| class="wikitable"
!Name
!Description
!Parameter
|-
|PersonalBundler
|Only bundle the transactions of the bundler account
|
|-
|PropertyBundler
|Only bundle transactions sent by accounts which have the "bundling" property set on them by the bundler account
|
|-
|AssetBundler
|Bundles only transactions for asset with ID provided as parameter
|Asset ID (numeric)
|-
|CurrencyBundler
|Bundles only transactions for MS currency with ID provided as parameter
|Currency ID (numeric). This is '''not''' the currency code
|-
|PurchaseBundler
|Bundles only purchases of digital goods sold by an account provided as parameter
|Account ID (numeric or RS format)
|-
|QuotaBundler
|Bundles transaction until the quota per account and transaction type is reached. The quota is provided as parameter.
|Max number of transactions per account and transaction type that will be accepted by the rule
|-
|TransactionTypeBundler
|Bundles only transaction types provided as parameter.
|Comma separated string, which contains the <type>:<subtype> pairs specifying the "type" and "subtype" identifier of the whitelisted transaction types. The "type" and "subtype" identifiers can be found in the transactionSubTypes field of the getConstants result. E.g. "7:1,7:2" bundles only ShufflingRegistration and ShufflingProcessing transactions.
|}