1/18 Quick Start

Quick Start

This document contains instructions for setting up a Utopia p2p host in order to automate certain
actions: making and receiving payments, and ordering goods and services by email or via personal
messages. The consumers of such services may include, e.g., a cryptocurrency exchange, an exchange
service, an advertising agency, a support bot, and other services.

To launch the Utopia p2p network client with API support, you need to complete a number of actions:

– Install the application

– Set up and enable API mode support

– Verify that settings are correct

All necessary operations are described in detail below.

Installation

The installation process varies depending on the OS.

Windows

To run the application, you need Windows 7, 8 or 10.

We recommend using the 64-bit version of the OS.

Installation distribution is available here:

[Link]

The installation process is very easy - all you need to do is follow the steps of the Install Wizard. We
recommend that you don’t run the application at the last stage (uncheck the application launch box).

MacOS

To run the application, you need to use the operating system version 10.12 or later.

Installation distribution is available here:

[Link]

The dmg file installation process is standard for MacOS.

Linux

Only 64-bit OSs are supported. The bit depth of the OS can be verified using the following command:

uname -r
1/18 Quick Start
 2/18 Quick Start

If the response to this command is xxxxx.x86_64, then this a 64-bit OS.

The list of supported OSs, RPM-like:

OS Name Verification Command Sample OS Response

Red Hat Enterprise Linux Server release 7.6
RHEL сat /etc/redhat-release or cat /etc/issue
(Maipo)
CentOS cat /etc/centos-release or cat /etc/issue CentOS Linux release 7.6.1810 (Core)
Fedora сat /etc/fedora-release or cat /etc/issue Fedora release 10 (Cambridge)
SUSE cat /etc/SuSE-release or cat /etc/issue SUSE Linux Enterprise Server 12 (x86_64)

DEB-like OSs:

OS Name Verification Command Sample OS Response

Ubuntu cat /etc/debian_version or cat /etc/issue 9.5 or Debian GNU/Linux 9
Debian сat /etc/lsb-release or cat /etc/issue DISTRIB_ID=Ubuntu

To run the application, you need to:

1. Install the following group of additional packages:

rpm-like distributions:

yum install -y libxkbcommon-x11 mesa-libGL pulseaudio-libs-glib2 fontconfig

+ all the dependencies that will be offered during the installation process

deb-like distributions:

apt-get install libx11-xcb1 libgl1-mesa-glx libpulse-mainloop-glib0

libfontconfig

+ all the dependencies that will be offered during the installation process

2. Download the latest Utopia client version

rpm-like distributions:

wget [Link]

deb-like distributions:

wget [Link]

3. Install the client using the command:

rpm -ivh utopia-1.0-XXXX.x86_64.rpm

or

dpkg -i [Link]
2/18 Quick Start
 3/18 Quick Start

Setting Up and Enabling API Mode

Support

Depending on the configuration used and the display availability on your machine, as well as depending
on personal preferences, the application can be launched in the graphical interface mode or in the
headless mode.

Important: Your Utopia p2p host must stay on all the time when working with the API. To ensure
stable operation of the service, running multiple applications from the same IP address is not
allowed.

We strongly recommend that you keep your Utopia p2p host on all the time.

Using Graphical Interface (GUI)

1. Launch the application

2. Create a new cryptocontainer

Follow the on-screen wizard instructions to create a new cryptocontainer.

How to create an account in Utopia Network?

Run Utopia application.

Click "Create new account" button
At the "Create Your Utopia Account" page enter your Nickname. Optionally,
you may enter your first and last names. Please note that your Nickname and
first/last names (if entered) will be visible to your authorized contacts.
Click "Next"
Leave the default path, but take note of it. This is the path to your
Encrypted Container that will be created on your computer. The purpose of
the Encrypted Container is to store your Utopia data, such as your private
key, uMails, files, uWallet, chat history, contacts and transactions history
in encrypted form. You may select any folder on your computer if you wish.
Enter the password to your Encrypted Container twice. Make sure that you
have chosen a strong password. Be sure to remember your password and never
store it in plain text at your computer. Lost passwords cannot be recovered,
resulting in the permanent lost of access to your Utopia account.
Important: Make sure that you backup your Encrypted Container regularly and
store your password somewhere safe, as loss of the container or password will
result in the permanent loss of your Utopia account data and account access.
Click "Next" button to proceed to the next step.
Familiarize yourself with information on mining within the Utopia ecosystem.
By default mining is enabled, however you may disable it by unchecking the
"Enable Mining" checkbox. Click "Finish".
Your new Utopia account has been created.

3/18 Quick Start

 4/18 Quick Start

Specify the location for saving the cryptocontainer and enter a strong password. Typical

cryptocontainer storage location:

On Windows, the file is located in:

C:\Users\%username%\AppData\Roaming\Utopia\Utopia Client\db

Linux:

home\%username%\.local\share\Utopia\Utopia Client\db

MacOS:

home\%username%\Library\Application Support\Utopia\Utopia Client\db

3. Configure working with the API

Go to Tools→Settings→API.

Check the Enable API box.

Depending on your preferences, enable communication via the http and/or https protocol and set
the desired port.

To increase the connection security, you can specify the address from which the connection to your
Utopia host will be established in order to run automated scripts. In this case, set the allowed address
in the Listen IP field; otherwise leave [Link] to allow connections from any IP address.

An example of the correct settings is shown in the screenshot below.

The last step is to get a token to be able to execute API requests.

Click the Add token button and then specify your token name, scope, and lifetime, if necessary.

An example of the correct settings is shown in the screenshot below.

4/18 Quick Start

 5/18 Quick Start

Headless Mode

This mode enables launching (for example, via ssh) the client p2p functionality in a non-display
configuration with API support.

You can use the keys to launch the application with the base, password and headless mode indicated.
Example:

cd /opt/utopia/messenger/Utopia && ./utopia --db /root/[Link] --pwd

merchant_password --headless

where the keys are:

--db indicating the path to the cryptocontainer
--pwd indicating the cryptocontainer password

If the base is not created, you can create it using the following command:

cd /opt/utopia/messenger/Utopia && ./utopia --headless --create --

db=/path/to/db/[Link] --pwd 123

For convenience, the application can be launched using a configuration file, e.g.:

5/18 Quick Start

 6/18 Quick Start

# Database password
userPassword=123

# Database path
userDatabase=/path/to/db

# List of API tokens separated by commas

apiUserTokens=AB3FF5AFCCC85347F43AB6350193D87E

# Enable API
apiEnabled=true
apiHTTPEnabled=true
apiHTTPSEnabled=true

# API HTTP port

apiPort=10010

# API HTTPS port

apiSslPort=10100

# API interactive help enabled (/api/help)

apiHelpEnabled=true

# Path to SSL certificate for HTTPS API

# apiCertificatePath=/path/to/[Link]
# apiPrivateKeyPath=/path/to/[Link]

# API listen address

#apiListenAddress=[Link]

The apiUserTokens key allows you to explicitly create a token without any restrictions for completing
all types of API requests. Use the HEX string format that is 32 characters long.

Launching the application using the configuration file:

cd /opt/utopia/messenger/Utopia && ./utopia --headless --

configPath=/path/to/с[Link]

You should create and save a backup copy of your cryptocontainer regardless of how you use the
application. You can do this by simply copying the .db file.

6/18 Quick Start

 7/18 Quick Start

Verifying Correct Settings

If you are using the application with a graphical interface, go to Tools→Settings→API.

Enable API Help mode.

Click on the link to the right of the checkbox.

A window will open in the browser selected in your system by default. You can use it to get
information about all the available methods and the format of requests and returned responses. Use
the created non-expired token to ensure correct operation.

If using headless mode, specify the following in the configuration file or the application launch key:

apiHelpEnabled=true

A page with information on the available methods can be accessed via http or https with the specified
port at:

%protocol%://[Link]:%port%/api/help
e.g.: [Link]

Another option for checking the functionality of the specified settings is to send a POST request to:

7/18 Quick Start

 8/18 Quick Start

%protocol%://[Link]:%port%/api/1.0
e.g.: [Link]

Sample request

{
"method": "getSystemInfo",
"token": "3A2E92F178084F5ACEFDFE209DC35792"
}

Sample response

{
"result": {
"buildAbi": "x86_64-little_endian-llp64",
"buildCpuArchitecture": "x86_64",
"build_number": "1.0.5958",
"currentCpuArchitecture": "x86_64",
"netCoreRate": 25,
"networkCores": 4,
"networkEnabled": true,
"numberOfConnections": 4,
"packetCacheSize": 52740,
"uptime": "[Link]"
},
"resultExtraInfo": {
"elapsed": "0"
}
}

Congratulations! Setup mode completed successfully.

Examples of Typical User Scenarios

User library description and usage examples

A description of the Utopia Client API user library along with the examples of using the implemented
calls with Python can be found below.

Initializing a Utopia class object

APIURL - Socket for working with API

PASSWORD - Token used

interval - Delay between consecutive executions of requests

8/18 Quick Start

 9/18 Quick Start

import api
u=[Link](APIURL, PASSWORD, interval=1)

General information on called methods

Calling a Utopia class method returns the status of the completed request and the request response data
structure.

status, data = [Link]()

if status:
#some data processing
print(data)

Most methods allow implicitly obtaining the following arguments:

sortBy - indicates the need to sort the output Format used:

propertyName1:sortingorder,propertyName2:sortingorder offset - offsets the
output, prunes the specified N of initial results limit - limits the output

Example of setting and resetting filters:

[Link]("name", 5, 100)

[Link]()

Sample Codes

Finance

Getting system information

Displaying the version number of the application used

status, data = [Link]()

if status:
print(data["build_number"])

Getting data on the current account balance

status, data = [Link]()

if status:
print("You balance: " + str(data))

Getting information on existing cards

status, cards = [Link]()

if status:

9/18 Quick Start

 10/18 Quick Start

for card in cards :

print("Card name is: " + card["name"] + "\n")

Transferring cryptons

if [Link]("AnyPublicKey", 3.141592653):
print("Success")

Creating a voucher

if [Link](3.141592653, "MyCardId"):
print("Success")

Using a voucher with funds credited to the specified card

if [Link]("VoucherId", "MyCardId"):
print("Success")

Deleting a voucher with funds credited to the specified card

if [Link]("VoucherId", "MyCardId"):
print("Success")

Getting information on vouchers issued

status, vouchers= [Link]()

if status:
print("Total "+ str(len(vouchers))+" vouchers codes: ")
for voucher in vouchers:
print(voucher ["voucherid"]+"\n")

Getting invoice information

status, invoices= [Link]()

if status:
print("Total "+ str(len(invoices))+" invoices: ")
for invoice in invoices:
print("Id: " + invoice ["invoiceid"] + " amount: " + str(invoice
["amount"]) + "\n")

Sending an invoice

if [Link]("AnyCardId", 1.00, "Some comment"):

print("Success")

Paying an invoice

if [Link]("AnyInvoiceId"):
print("Success")

10/18 Quick Start

 11/18 Quick Start

Rejecting an invoice

if [Link]("AnyInvoiceId"):
print("Success")

Canceling an invoice

if [Link]("AnyInvoiceId"):
print("Success")

Get a portion of financial transaction history

status, transactions = [Link]("ALL_VOUCHERS", "0", ""):

if status:
for transaction in transactions:
print("Transaction type: " + transaction["name"] + "\n")

Add card

if [Link]("#77f442", "name", "a1b2"):

print("Success\n")

Delete card

if [Link]("A0950072D9261480"):
print("Success\n")

Get information on the financial system

status, data = [Link]()

if status:
print(data)

Communications

Getting a list of contacts

status, contacts= [Link]("uto") # any nick like uto_pia

if status:
print("Total "+ str(len(contacts))+" contacts: ")
for contact in contacts:
print("Nick: " + contact ["nick"] + " is your friend: " +str(contact
["isFriend"]) + "\n")

11/18 Quick Start

 12/18 Quick Start

Send authorization request

if [Link]("PublicKey"):
print("Success\n")

Accept authorization request

if [Link]("PublicKey"):
print("Success\n")

Cancel authorization request

if [Link]("PublicKey"):
print("Success\n")

Delete contact

if [Link]("PublicKeyOrNick"):
print("Success\n")

Change contact group assignment

if [Link]("PublicKey", "GroupName"):
print("Success\n")

Change contact nickname

if [Link]("PublicKey", "NewNick"):
print("Success\n")

Sending a chat message

if [Link]("AnyNick", "Hi"):
print("Success\n")

Get message list

status, messages = [Link]("PK", limit, offset):

if status:
for message in messages:
print(message)

Get email list

status, mails = [Link](FolderType, ""):

if status:
for mail in mails:
print("mail id:"+str(mail) )

12/18 Quick Start

 13/18 Quick Start

Get email information

status, mail = [Link]("SomeEmailId"):
if status:
print(mail["subject"])

Forward email

if [Link](Emailid, "Hello!", "AnyUserNick"):

print("Success\n")

Reply by email

if [Link](Emailid, "Hello!", "AnyUserNick"):

print("Success\n")

Delete email

if [Link]("SomeEmailId"):
print("Success\n")

Sending emails to multiple recipients

if [Link](["AnyNick","AnotherNick"], "e-mail subject", "Hello

from API =)"):
print("Success\n")

Joining a channel

if [Link]("ChannelId", "ChannelPassword"):
print("Success\n")

Sending a channel message

if [Link]("ChannelId"):
print("Success\n")

Leaving a channel

if [Link]("ChannelId"):
print("Success\n")

Notifications

Notifications for all types of events (finances, IM, emails, channel messages and others) are received
using the WebSocket mechanism.

The process of enabling and setting the priority port for listening is as follows:

status, port=[Link]("true", 12348)

13/18 Quick Start

 14/18 Quick Start

The result is the returned port selection status and, if the ordered port is already taken, the port to which
it was possible to bind.

Sample code for listening to notifications:

[Link](True)
ws =
[Link]("[Link]
="
+ token, on_message = on_message, on_error = on_error, on_close = on_close,
on_open = on_open)
ws.on_open = on_open
ws.run_forever()
on_message on_error on_close and on_open functions must be defined by the user.

Working with History and Force Update of Operations History

Enable auto update mining block history *

if [Link](1)
print("Success\n")

Get sync operation status

status = [Link]()

Possible operation statuses

0 = STATE_EMPTY
1 = STATE_IN_PROGRESS
2 = STATE_RECEIVED_RESPONSE

Get information on mining blocks

status, blocks = [Link]()

Get a portion of financial transaction history

status, transactions = [Link]("ALL_VOUCHERS", "", "", "", "",

0.0001, 100):
if status:
for transaction in transactions:
print("Transaction type: " + transaction ["name"] + "\n")

List of available filters:

ALL_CARDS
INCOMING_CARDS

14/18 Quick Start

 15/18 Quick Start

OUTGOING_CARDS
CREATED_CARDS
DELETED_CARDS
ALL_TRANSFERS
INCOMING_TRANSFERS
OUTGOING_TRANSFERS
ALL_REQUESTS
AWAITING_REQUESTS
AUTHORIZED_REQUESTS
DECLINED_REQUESTS
CANCELED_REQUESTS
EXPIRED_REQUESTS
ALL_APPROVED_REQUESTS
CREATED_VOUCHERS
CREATED_VOUCHERS_BATCH
ACTIVATED_VOUCHERS
DELETED_VOUCHERS
ALL_VOUCHERS
ALL_MINING
ALL_POS
ALL_FEE
ALL_UNS_RECORDS
UNS_UNS_REGISTRATION
UNS_UNS_CHANGED
UNS_UNS_TRANSFERRED
UNS_UNS_DELETED
ALL_TRANSACTIONS

Filters can be combined with a comma: "ALL_CARDS,ALL_FEE"

Usecases

The most popular are operations of depositing or withdrawing funds. Let’s look at them in more detail.

Deposit

Minimal

Used when funds are not deposited frequently to the main account and/or the deposit amount is known
in advance.

status, balance = [Link]()

print(balance)

# wait some operations

15/18 Quick Start

 16/18 Quick Start

status, newbalance = [Link]()

print(newbalance)

if (newbalance > balance):

print("Deposit\n")

Normal

Used in the usual mode when the payment can be identified by pk or by adding a special comment
to the payment. In this case, you can get a history of recent operations. In the example below,
transactions sorted by creation date are filtered and only the last 1 is displayed as a result.

The financial history is used with the incoming transactions filter. Filters can be combined. The analysis is
based on the PK address of the funds’ sender or the content of the comment regarding transaction ID.

[Link]("created:desc", 0, 1)
status, transactionHistory = [Link]("INCOMING_TRANSFERS",
"","","","","","")

# check value of transactionHistory[0]["source_pk"]

# or check value of transactionHistory[0]["comments"] for some transaction
id

Maximum

The mode involves the maximum division of funds accounting.

An invoice is issued for a specific payer using their card. Payment is tracked using the
transaction ReferenceNumber.

status, refnumber = [Link] ("id", "B7EB00274D1585F7", 0.5)

print(refnumber)

# wait for payment of the invoice

status, invoiceinfo = [Link](refnumber)

print(invoiceinfo)
if (invoiceinfo["status"] == "Authorized"):
print(invoiceinfo["amount"])

The division of the above examples into minimal-normal-maximum is conditional. You can combine the
proposed options or use your own.

Withdrawal

In the withdrawal mode, you need to transfer funds and then make sure that the transaction was
accepted by the network.

16/18 Quick Start

 17/18 Quick Start

Minimal

The simple mode involves transferring funds and checking for the transfer confirmation by the network.

status, paymentid =
[Link]("77D1832EBB35F233A1BB4B4AD9ECC7774F8F2000733EAA81F615A9173A487
A52", "id", "", 0.8)
print(paymentid)

# wait for network confirmation

[Link]("created:desc", 0, 1)
status, transactionHistory = [Link]("OUTGOING_TRANSFERS",
"","","","","","")
print(transactionHistory)

Normal

The mode involves transferring funds by card number or the recipient’s PK, possibly with the
indication of transaction ID in the comments, and the subsequent verification of transfer
confirmation by the network.

status, paymentid = [Link]("", "id", "cardid", 0.8)

print(paymentid)

# wait for network confirmation

status, transactionHistory =
[Link]("", paymentid,"","","","","")
print(transactionHistory)

Maximum

The mode involves working with cards tied to payers’ accounts. The invoice is received from the payee
and the data is analyzed (for example, by the operation ID in the comment or the PK that requested
the invoice, by date and other information). If everything is correct, the invoice is paid and the
payment status is checked.

[Link]("created:desc", 0, 1)

17/18 Quick Start

 18/18 Quick Start

status, invoices = [Link]("299C0011032F258C","",

"","","Awaiting","","","")

invoiceid=invoices[0]["invoiceid"]
status, refid= [Link](invoiceid)

# wait for network confirmation

status, transactionHistory =
[Link]("", paymentid,"","","","","")
print(transactionHistory)

The proposed scenarios are not the only ones that are true. For example, you can choose to issue a
voucher and transfer its code to the funds’ recipient. Or you can combine the proposed approaches
as you like.

List of Available API Libraries

To execute API requests, you can use the raw format for transmitting json data using the POST
method, or use the available official libraries:

API python
API perl
API asp classic
API php
API curl
API ruby

18/18 Quick Start