Skip to main content

QRL API - walletd-rest-proxy

Interaction with wallet functions is simplified with the use of the walletd-rest-proxy, allowing typical REST API calls to be made to the QRL node.

This proxy eliminates any need to interact with the GRPC functions, allowing typical CURL calls to be utilized making interaction with wallet functions simple.

Automatic Slave transactions

The wallets-rest-proxy provides an automatic slave system, where new slaves are generated under a root_slave with a 3rd layer of recursion of Merkle trees under a single private key.

This allows a nearly unlimited amount of outgoing transactions, where new slaves are automatically generated when all previous tier 3 slave OTS keys are used.

Automatic Slave Transaction Diagram

auto slave tree system diagram

Any walletd-rest-proxy function that utilizes slaves will use this automatic slave system. The address will need to be initially setup using the AddNewAddressWithSlaves function.

tip

The qrl_walletd API is available with the base QRL Python package install. This system also uses the QRL walletd-rest-proxy to make automatic wallet management simple.

walletd-rest-proxy General Info

By default the walletd-rest-proxy expects there to be a QRL node running on the localhost with default ports available.

  • Wallet API on 19010
  • Node API on 19009

These configuration settings can be overridden. See the node configuration documentation for information on setting these to a different port in your local node.

  • self.public_api_server = "127.0.0.1:19009"
  • self.wallet_api_port = 19010

The wallet daemon will by default create the wallet file at ~/.qrl/walletd.json.

Requirements

  • QRL Node, fully synced.
  • QRL Walletd-RestProxy
  • golang v1.8 or greater
tip

The qrl_walletd API is installed with the base QRL Node. Follow this guide to install the tools and get started.

Getting Started

Running the wallet daemon is simple. Once you have met the requirements above, follow the steps below, ensuring the wallet-rest-proxy stays running as this will allow interaction with the GRPC node.

Run the QRL Wallet Daemon qrl_walletd

qrl_walletd

Install the walletd-rest-proxy

GO Install

go install github.com/theqrl/walletd-rest-proxy/generated@latest

Manual Install

Clone walletd-rest-proxy from the repo hosted at https://github.com/theQRL/walletd-rest-proxy

git clone github.com/theQRL/walletd-rest-proxy
cd walletd-rest-proxy
go build

Start the wallet-rest-proxy

./walletd-rest-proxy -serverIPPort 127.0.0.1:5359 -walletServiceEndpoint 127.0.0.1:19010

This will expose port 5359 for typical REST connections.

info

The QRL wallet Daemon loads the walletd.json file into memory. To use another wallet file, the qrl_walletd daemon must be restarted with the correct file located in the ~/.qrl/walletd.json location.

Install the walletd-rest-proxy

Install the package using the golang tools or manually by cloning the repository.

GO Install

go install github.com/theqrl/walletd-rest-proxy/generated@latest

Manual Install

Clone walletd-rest-proxy from the repo hosted at https://github.com/theQRL/walletd-rest-proxy

git clone github.com/theQRL/walletd-rest-proxy

Enter the directory and build the package.

cd walletd-rest-proxy
go build

Start the wallet-rest-proxy

This will expose port 5359 for typical REST connections, connecting the the wallet API running on port 19010 from the QRL node.

~/go/bin/walletd-rest-proxy -serverIPPort 127.0.0.1:5359 -walletServiceEndpoint 127.0.0.1:19010

OR

./walletd-rest-proxy -serverIPPort 127.0.0.1:5359 -walletServiceEndpoint 127.0.0.1:19010
info

Running the wallet-rest-proxy in a screen session is a simple way to run the proxy on a Unix system, allowing one to disconnect from the console leaving the proxy running.

screen -Sdm wallet-rest-proxy ./walletd-rest-proxy -serverIPPort 127.0.0.1:5359 -walletServiceEndpoint 127.0.0.1:19010

AddNewAddress

Adds new randomly generated address to the wallet located at ~/.qrl/walletd.json.

AddNewAddress Request

ParameterTypeDescription
heightUInt64Height of the newly generated XMSS tree
hash_functionStringHash function for XMSS. Possible values are shake128, shake256

AddNewAddress Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

AddNewAddress Response Data

ParameterTypeDescription
addressStringReturn the newly added QRL address

This function will create a single address with no slave keys. For use when outgoing transactions will not exceed addresses tree height. By default this will generate a new address with:

  • OTS key height {"height": 10} or 1,0241,024 outgoing transactions
  • Using the {"hash_function": "shake_128"}

Code examples below use the default values, change as needed.

curl -XPOST http://127.0.0.1:5359/api/AddNewAddress \
-d '{"height": 10, "hash_function": "shake128"}'

The newly generated address will be added to the ~/.qrl/walletd.json file. This file will be created if not existing.

info

This address is limited to the initial OTS height given in optional configuration parameters when generated.

Optional Configurations

ConfigurationDefaultNotes
height10Min: 6, Max: 18
hash_functionshake128Options: shake128, sha256, sha2_256
note

Higher tree heights may take longer to generate.



AddNewAddressWithSlaves

Adds a new address into the ~/.qrl/walletd.json wallet file, generates and transmits slave transaction to the chain.

Automatic OTS Key System

When used with a wallet API transaction that utilizes slave OTS keys, like RelayTransferTxnBySlave the API will generate new slave keys when needed using the RelaySlaveTxnBySlave function.

info

Use this function to generate an address to use the automatic OTS key system.

This command will create an unlimited address, re-generating slave keys as needed. Additionally the system will preserve 5 OTS keys from each slave to ensure there are no lost funds with this system.

AddNewAddressWithSlaves Request

ParameterTypeDescription
heightUInt64Height of the newly generated XMSS tree (Min 6)
number_of_slavesUInt64Number of slaves to be generated (Max 100, Default 3)
hash_functionStringHash function for XMSS. Possible values are shake128, shake256, sha2_256.

AddNewAddressWithSlaves Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

AddNewAddressWithSlaves Response Data

ParameterTypeDescription
addressStringReturn the newly added QRL address

The examples below are using the default address values. Change as needed.

info

This address and slave keys will be added to the ~/.qrl/walletd.json file, this file will be created if not existing.

curl -XPOST http://127.0.0.1:5359/api/AddNewAddressWithSlaves \
-d '{"height": 10, "number_of_slaves": 3, "hash_function": "shake128" }'
ConfigurationDefaultNotes
height10{Min: 6, Max: 18} outgoing transactions per slave
number_of_slaves3{Min: 1, Max: 100} Number of slaves to generate
hash_functionshake128Options: shake128, sha256, sha2_256
Account Recovery

The first five slave OTS keys will be preserved, beginning at {"index": 5}. Keys {0 - 4} are saved for backup or recovery for each slave generated.



IsValidAddress

Check if a QRL address is valid. Returns {"valid": "True"} if the QRL Address is valid.

IsValidAddress Request

ParameterTypeDescription
addressStringQRL Address

IsValidAddress Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

IsValidAddress Response Data

ParameterTypeDescription
validStringReturns True for valid QRL address otherwise False.

Validates the public address given meets all requirements and is valid to be used as recipient of a transaction.

Example code below. Enter details for the address to lookup {"address": ""}.

curl -XPOST http://127.0.0.1:5359/api/IsValidAddress \
-d '{"address": "Q010500dacbf29a83ef6832bcf16f0592adb15313836228a873a7b8eed1c354c4414a206ad38728"}'
note

IsValidAddress expects a Q hex address format, example: Q0103006fa2d29c4acb9bc192581694a616d394f7ef2f35dd5ab5a4dddd865740a3f3293e54c560



ListAddresses

Lists all addresses located in the ~/.qrl/walletd.json file loaded into the walletd-rest-proxy.

ListAddresses Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

ListAddresses Response Data

ParameterTypeDescription
addressesStringReturn list of addresses added into your wallet

Returns an array of public addresses found in the walletd.json wallet file.

curl -XGET http://127.0.0.1:5359/api/ListAddresses
note

This function will return results from the walletd.json file located in the default location when the walletd-rest-proxy was started. Any manual changes to this file will require the proxy to be restarted to pickup the changes.



RemoveAddress

Permanently remove a given address, including all private and slave keys, from the walletd.json file.

This action is irreversible and potentially destructive!

Backup the address keys prior file to removing using the GetRecoverySeeds function.

RemoveAddress Request

ParameterTypeDescription
addressStringQRL address to be removed from the wallet

RemoveAddress Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

Removes given address from the the walletd.json wallet file. Requires a QRL address that exists in the ~/.qrl/walletd.json file.

note

Replace the {"address": ""} with the address to be removed. This action is permanent.

curl -XPOST http://127.0.0.1:5359/api/RemoveAddress \
-d '{"address": "Q010500dacbf29a83ef6832bcf16f0592adb15313836228a873a7b8eed1c354c4414a206ad38728"}'

Required Data

ConfigurationDefaultNotes
addressN/AProvide QRL address in QQ Hex format


EncryptWallet

Encrypts the QRL wallet using the passphrase given.

Secure the walletd.json file by encrypting it using the EncryptWallet function which will result in an AES encrypted /home/$USER/.qrl/walletd.json file.

Further interaction with the wallet will require the file is decrypted first using the Unlock Wallet Function and by Locking locking it after complete, rendering it encrypt ed again, removing the passphrase from memory.

EncryptWallet Request

ParameterTypeDescription
passphraseStringPassphrase to encrypt the wallet

EncryptWallet Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

See the code examples below.

curl -XPOST http://127.0.0.1:5359/api/EncryptWallet \
-d '{"passphrase": "demo123"}'

Required Data

ConfigurationDefaultNotes
passphraseN/AProvide passphrase in string format


LockWallet

Lock a previously encrypted wallet file.

LockWallet Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

Using the previously set encryption passphrase, lock the wallet and remove stored passphrase from memory.

curl -XGET http://127.0.0.1:5359/api/LockWallet
note

After locking the wallet, the passphrase will be required to unlock.



UnlockWallet

Unlock an encrypted, and locked wallet using the encryption passphrase established with the EncryptWallet function.

UnlockWallet Request

ParameterTypeDescription
passphraseStringPassphrase to unlock the wallet

UnlockWallet Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

Using the previously set encryption passphrase, unlock the wallet allowing transactions to be signed using addresses in the wallet.

curl -XPOST http://127.0.0.1:5359/api/UnlockWallet \
-d '{"passphrase": "demo123"}'

Required Data

ConfigurationDefaultNotes
passphraseN/AProvide passphrase in string format


GetRecoverySeeds

Print out the recovery seeds, or secret keys for the given QRL address.

note

The address must exist in the wallet.

GetRecoverySeeds Request

ParameterTypeDescription
addressStringQRL Address

GetRecoverySeeds Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetRecoverySeeds Response Data

ParameterTypeDescription
hexseedStringHexseed for the given address
mnemonicStringMnemonic words for the given address

Returns the backup or recovery seeds for the address given.

curl -XPOST http://127.0.0.1:5359/api/GetRecoverySeeds \
-d '{"address": "Q01050047fb1286d6e02afcf014b367ac00fb944235ee814bca26c82665631367fe583d17198f59"}'

Required Data

ConfigurationDefaultNotes
addressN/AProvide QRL address in QQ Hex format


GetWalletInfo

Print info on the wallet.

GetWalletInfo Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetWalletInfo Response Data

ParameterTypeDescription
versionUInt32Wallet version number
address_countUInt64Number of addresses into the wallet
is_encryptedBooleanTrue if wallet is already encryptedFalse if wallet is not encrypted

Returns JSON array of information on the wallet located at /home/$USER/.qrl/walletd.json

curl -XGET http://127.0.0.1:5359/api/GetWalletInfo


RelayTransferTxn

Send or Transfer funds from a QRL address in the wallet to another QRL address. This function will use the root OTS keys for the address.

note

For a more flexible address allowing additional levels of OTS slave keys, use an address created with the AddNewAddressWithSlaves and the RelayTransferTxnBySlave function.

RelayTransferTxn Request

ParameterTypeDescription
addresses_toStringArray of receiver's addresses
amountsUInt64Array of amounts in Shor to be received by receiver. Must be in same order as of addresses_to
feeUInt64Transaction Fee in Shor
master_addressStringThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressStringQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexUInt64One Time Signature Index to be used to sign the transaction.

RelayTransferTxn Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTransferTxn Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Use this function to send QRL from an address contained in the /home/$USER/.qrl/walletd.json file to another QRL address given, up to 100 recipients per transaction.

You must provide the ots_index for the transaction, keeping track of keys that have already been used to avoid any attempted key reuse.

curl -XPOST http://127.0.0.1:5359/api/RelayTransferTxn \
-d '{"addresses_to": ["Q0103007f44eb8e11de8a0a6d69c21088245951bdb77637a082b713abbf9bdf35f13ac2c8d58d55", "Q010300010e65015a34e2711c3ffc9bde650f7361fde192c5845df991da56940ff411cfd155ddaf"],
"amounts": [10000, 100000],
"fee": 10000,
"master_address": "",
"signer_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187",
"ots_index": 1
}'

Required Data

ConfigurationDefaultNotes
addressN/AProvide QRL address in QQ Hex format to send transaction from
addresses_toN/ARecipient QRL addresses array
amountsN/AAmount for each address in an array
feeN/AFee to pay for transaction
signer_addressN/AAddress that is signing and sending the transaction
ots_indexN/AUnused OTS key index to sign the transaction


RelayTransferTxnBySlave

Transfer QRL from an address with slave keys to another QRL address.

Automatic Slave Key Transaction

Use this function to send nearly infinite number of outgoing transactions. Address must be created using the AddNewAddressWithSlaves function.

RelayTransferTxnBySlave Request

ParameterTypeDescription
addresses_toStringArray of receiver's addresses
amountsUInt64Array of amounts in Shor to be received by receiver. Must be in same order as of addresses_to
feeUInt64Transaction Fee in Shor
master_addressStringQRL address whose slave will be signing the transaction. QRL Address must exist in the wallet.

RelayTransferTxnBySlave Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTransferTxnBySlave Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Use this function to send QRL from an address with slave keys contained in the /home/$USER/.qrl/walletd.json file to another QRL address given, up to 100 recipients per transaction.

curl -XPOST http://127.0.0.1:5359/api/RelayTransferTxnBySlave \
-d '{"addresses_to": ["Q0103007f44eb8e11de8a0a6d69c21088245951bdb77637a082b713abbf9bdf35f13ac2c8d58d55", "Q010300010e65015a34e2711c3ffc9bde650f7361fde192c5845df991da56940ff411cfd155ddaf"],
"amounts": [10000000, 1000000],
"fee": 100000,
"master_address": "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4"}'

Required Data

ConfigurationDefaultNotes
addresses_toN/ARecipient QRL addresses array
amountsN/AAmount for each address in an array
feeN/AFee to pay for transaction
master_addressN/AMaster Address that is signing and sending the transaction using next slave OTS


RelayMessageTxn

Transmit a message transaction onto the chain.

tip

This function can be used to notarize data or for any free form data. See the message encoding documentation for information on established encoding formats.

RelayMessageTxn Request

ParameterTypeDescription
messageStringString Message of maximum 80 bytes.
feeUInt64Transaction Fee in Shor
master_addressStringThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressStringQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexUInt64One Time Signature Index to be used to sign the transaction.

RelayMessageTxn Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayMessageTxn Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Relay up to 80 bytes of a message onto the network from given address.

Message length must be validated prior to submitting to the node or an OTS key will be consumed and the transaction will fail.

curl -XPOST http://127.0.0.1:5359/api/RelayMessageTxn \
-d '{"message": "Hello World!!!",
"fee": 1000000000,
"signer_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187",
"ots_index": 1}'

Required Data

ConfigurationDefaultNotes
messageN/AMessage string
feeN/AFee to pay for transaction
signer_addressN/AAddress that is signing and sending the transaction
ots_indexN/AUnused OTS key index to sign the transaction


RelayMessageTxnBySlave

Relay message transaction to the QRL network using slave address found in the /home/$USER/.qrl/walletd.json file.

Address must have been created using the AddNewAddressWithSlaves function.

tip

This function can be used to notarize data or for as any free form data. See the message encoding documentation for information on established encoding formats.

RelayMessageTxnBySlave Request

ParameterTypeDescription
messageStringString Message of maximum 80 bytes.
feeUInt64Transaction Fee in Shor
master_addressStringQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.

RelayMessageTxnBySlave Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayMessageTxnBySlave Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Relay up to 80 bytes of a message onto the network from given address using slave keys for signing.

Message length must be validated prior to submitting to the node or an OTS key will be consumed and the transaction will fail.

curl -XPOST http://127.0.0.1:5359/api/RelayMessageTxnBySlave \
-d '{"message": "Hello World!!!",
"fee": 1000000000,
"master_address": "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4"}'

Required Data

ConfigurationDefaultNotes
messageN/AMessage string
feeN/AFee to pay for transaction
master_addressN/AAddress that is signing and sending the transaction


RelayTokenTxn

Create a new token on the blockchain associated with the address given as owner, with token transferred to the addresses listed in the addresses array.

info

More information can be found in the QRL Token Documentation

Token Quantity

The total token quantity distribution is calculated by taking the amounts and multiplying it by the decimal place, distributed to the addresses given.

Say you have a token with a "decimals": 2 and "amounts": [100] minted tokens, creating a whole token that can be divided into 100 sub-token derivatives to the second decimal place.

100×0.01=1 token (divisible by 100)100 \times 0.01=1\text{ token (divisible by 100)}

RelayTokenTxn Request

ParameterTypeDescription
symbolStringSymbol of the token to be created symbol_max_length=10 bytes
nameStringName of the token to be created name_max_length=30 bytes
ownerStringQRL Address of the token owner (does not need to be the same as the creator or holder addresses)
decimalsUInt64Maximum supported decimals 19
addressesStringList of address to whom initial token will be assigned
amountsUInt64Array of amounts in Shor of token to be assigned to addresses. Must be in same count as addresses array. Max amount 999,999,999,999,999,999
feeUInt64Transaction Fee in Shor
master_addressStringThis is an optional field, only need to be filled with QRL address if the transaction is signed from a slave address.
signer_addressStringQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexUInt64One Time Signature (OTS) Index to be used to sign the transaction.

RelayTokenTxn Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTokenTxn Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

This function generates a new colored token on the QRL blockchain, originating from the signer address. The initial token balance will be sent to the QRL addresses listed in the addresses array.

In the code examples given, each address will receive one whole token, with 2 tokens created in total.

curl -XPOST http://127.0.0.1:5359/api/RelayTokenTxn \
-d '{ "symbol": "TEST",
"name": "TEST TOKEN",
"owner": "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4",
"decimals": 0,
"addresses": ["Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187", "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4"],
"amounts": [1, 1],
"fee": 1000000000,
"signer_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187",
"ots_index": 1}'

Required Data

ConfigurationDefaultNotes
symbolN/ASymbol of the token to be created symbol_max_length=10 bytes
nameN/AName of the token to be created name_max_length=30 bytes
ownerN/AQRL Address of the token owner (does not need to be the same as the creator or holder addresses)
decimalsN/AMaximum supported decimals 19
addressesN/AList of address to whom initial token will be assigned
amountsN/AArray of amounts in Shor of token to be assigned to addresses. Must be in same count as addresses array. Max amount 999,999,999,999,999,999
feeN/ATransaction Fee in Shor
master_addressN/AThis is an optional field, only need to be filled with QRL address if the transaction is signed from a slave address.
signer_addressN/AQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexN/AOne Time Signature (OTS) Index to be used to sign the transaction.


RelayTokenTxnBySlave

Create a new token on the blockchain associated with the address given as owner, with token transferred to the addresses listed in the addresses array using the master addresses slave keys for transaction signing.

Token Quantity

The total token quantity distribution is calculated by taking the amounts and multiplying it by the decimal place, distributed to the addresses given.

Say you have a token with a "decimals": 2 and "amounts": [100] minted tokens, creating a whole token that can be divided into 100 sub-token derivatives to the second decimal place.

100×0.01=1 token (divisible by 100)100 \times 0.01=1\text{ token (divisible by 100)}
tip

Use this function with an address generated with the AddNewAddressWithSlaves function for a nearly unlimited outgoing address utilizing the automatic slave key generation tools. Recommended for automated systems that need to send a large volume of transactions from the same address.

RelayTokenTxnBySlave Request

ParameterTypeDescription
symbolStringSymbol of the token
nameStringName of the token
ownerStringQRL Address of the token owner
decimalsUInt64Maximum supported decimals
addressesStringList of address to whom initial token will be assigned
amountsUInt64Array of amounts of token to be assigned to addresses. Must be in same order as of addresses
feeUInt64Transaction Fee in Shor
master_addressStringQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.

RelayTokenTxnBySlave Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTokenTxnBySlave Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

This function generates a new colored token on the QRL blockchain, originating from the master_address, using slave keys for signing functions. The initial token balance will be sent to the QRL addresses listed in the addresses array.

info

More information can be found in the QRL Token Documentation

In the code examples given, each address will receive one whole token, with 2 tokens created in total.

curl -XPOST http://127.0.0.1:5359/api/RelayTokenTxnBySlave \
-d '{"symbol": "TEST",
"name": "TEST TOKEN",
"owner": "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4",
"decimals": 0,
"addresses": ["Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4", "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187"],
"amounts": [100000, 100000],
"fee": 1000000000,
"master_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187"}'

Required Data

ConfigurationDefaultNotes
symbolN/ASymbol of the token
nameN/AName of the token
ownerN/AQRL Address of the token owner
decimalsN/AMaximum supported decimals
addressesN/AList of address to whom initial token will be assigned
amountsN/AArray of amounts of token to be assigned to addresses. Must be in same order as of addresses
feeN/ATransaction Fee in Shor
master_addressN/AQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.


RelayTransferTokenTxn

Send a token transfer to another QRL address consuming a root OTS key from the address.

RelayTransferTokenTxn Request

ParameterTypeDescription
token_txhashStringToken transaction hash is the transaction hash by which the token has been created. This is used to uniquely identify each created token in QRL network.
addresses_toStringArray of receiver's addresses
amountsUInt64Array of amounts to be received by receiver. Must be in same order as of addresses_to
feeUInt64Transaction Fee in Shor
master_addressStringThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressStringQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexUInt64One Time Signature Index to be used to sign the transaction.

RelayTransferTokenTxn Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTransferTokenTxn Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

This function is used to transfer a token from a holding address to another address. The RelayTransferTokenTxn will consume an OTS key from the address used to send the token.

curl -XPOST http://127.0.0.1:5359/api/RelayTransferTokenTxn \
-d '{ "addresses_to": ["Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4"],
"amounts": [1],
"token_txhash": "d099c08ce243c6356d1807eb3e76ef5f8e61c8c398b4e666db3381af0a6b2fa7",
"fee": 100000,
"signer_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187",
"ots_index": 1}'

Required Data

ConfigurationDefaultNotes
token_txhashN/AToken transaction hash is the transaction hash by which the token has been created. This is used to uniquely identify each created token in QRL network.
addresses_toN/AArray of receiver's addresses
amountsN/AArray of amounts to be received by receiver. Must be in same order as of addresses_to
feeN/ATransaction Fee in Shor
master_addressN/AThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressN/AQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexN/AOne Time Signature Index to be used to sign the transaction.


RelayTransferTokenTxnBySlave

Send a token transfer to another QRL address using the automatic slave key system.

User the Automatic OTS Key System

RelayTransferTokenTxnBySlave Request

ParameterTypeDescription
token_txhashStringToken transaction hash is the transaction hash by which the token has been created. This is used to uniquely identify each created token in QRL network.
addresses_toStringList of receiver's address
amountsUInt64List of Amounts to be received by receiver. Must be in same order as of addresses_to
feeUInt64Transaction Fee in Shor
master_addressStringQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.

RelayTransferTokenTxnBySlave Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelayTransferTokenTxnBySlave Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

This function is used to transfer a token from a holding address to another address. The RelayTransferTokenTxnBySlave function will consume an OTS key from the addresses automatic slave tree for addresses that have been created with slave keys.

curl -XPOST http://127.0.0.1:5359/api/RelayTransferTokenTxnBySlave \
-d '{ "addresses_to": ["Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187"],
"amounts": [1],
"token_txhash": "b87ec4667e038994c8981ae540526f67f908d98ce685f8c6d036d49a5b4f5816",
"fee": 100000,
"master_address": "Q010500e26037717191572726f1cab7c98f98db2e80b4465edc8700e1dfd6000cad0713356be6b4"}'

Required Data

ConfigurationDefaultNotes
token_txhashN/AToken transaction hash is the transaction hash by which the token has been created. This is used to uniquely identify each created token in QRL network.
addresses_toN/AList of receiver's address
amountsN/AList of Amounts to be received by receiver. Must be in same order as of addresses_to
feeN/ATransaction Fee in Shor
master_addressN/AQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.


RelaySlaveTxn

Relay slave public keys authorized for use by the master address. Links the slave key OTS trees to the master address from which the transaction is sent.

RelaySlaveTxn Request

ParameterTypeDescription
slave_pksBytesList of Base64 encoded Public Keys which are allowed to act as slave
access_typesUInt64Current supported access_type is 0
feeUInt64Transaction Fee in Shor
master_addressStringThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressStringQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexUInt64One Time Signature Index to be used to sign the transaction.

RelaySlaveTxn Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelaySlaveTxn Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Will sign and relay the transaction onto the chain. This requires that the slave Public Keys be passed to the command.

Generate slave trees and pass the public keys and the access type to the function to sign and send the transaction to the network.

curl -XPOST http://127.0.0.1:5359/api/RelaySlaveTxn \
-d '{ "slave_pks": ["AQYAPYdez4/TrVmOUecaVLlpZnn1a+ltrfzMPCtQnhZzBtBxEEmp4/Qk199XQs0NMRcttHJ3JSI4qs5XSxEUKbXzWQ=="],
"access_types": [0],
"fee": 100000,
"signer_address": "Q0103001330b82645e43fa1cc0aa1e00f269c2aa8ec76cce87175b7e4099723913d50f7d87e9187",
"ots_index": 16 }'

Required Data

ConfigurationDefaultNotes
slave_pksN/AList of Base64 encoded Public Keys which are allowed to act as slave
access_typesN/ACurrent supported access_type is 0
feeN/ATransaction Fee in Shor
master_addressN/AThis is an optional field, only need to be filled with QRL address, if the transaction is signed from slave address.
signer_addressN/AQRL Address signing the transaction. QRL Address must be already added into wallet.
ots_indexN/AOne Time Signature Index to be used to sign the transaction.


RelaySlaveTxnBySlave

Creates the signed slave transaction using one of the slaves and relay it to the network. Master Address must exist into wallet. It may relay a slave transaction if the remaining slave OTS key are less than 100.

RelaySlaveTxnBySlave Request

ParameterTypeDescription
slave_pksBytesList of Base64 encoded Public Keys which are allowed to act as slave
access_typesUInt64Current supported access_type is 0
feeUInt64Transaction Fee in Shor
master_addressStringQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.

RelaySlaveTxnBySlave Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

RelaySlaveTxnBySlave Response Data

ParameterTypeDescription
txTransactionReturn the transaction that has been relayed to the network.

Will sign and relay the transaction onto the chain. This requires that the slave Public Keys be passed to the command.

Generate slave trees and pass the public keys and the access type to the function to sign and send the transaction to the network.

curl -XPOST http://127.0.0.1:5359/api/RelaySlaveTxnBySlave \
-d '{"slave_pks": ["AQYAPYdez4/TrVmOUecaVLlpZnn1a+ltrfzMPCtQnhZzBtBxEEmp4/Qk199XQs0NMRcttHJ3JSI4qs5XSxEUKbXzWQ=="],
"access_types": [0],
"fee": 100000,
"master_address": "Q010500aba127bfb010f63334fc772be860a8cfb4706d5d4c91b51d7fe1988bef4ce46db7974781"}'

Required Data

ConfigurationDefaultNotes
slave_pksN/AList of Base64 encoded Public Keys which are allowed to act as slave
access_typesN/ACurrent supported access_type is 0
feeN/ATransaction Fee in Shor
master_addressN/AQRL address whose slave will be signing the transaction. QRL Address must exist into wallet.


ChangePassphrase

Change the passphrase that encrypts the wallet.

ChangePassphrase Request

ParameterTypeDescription
oldPassphraseStringOld Passphrase
newPassphraseStringNew Passphrase

ChangePassphrase Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

Change the passphrase of an already encrypted wallet. For initial encryption use the EncryptWallet function.

This will completely remove any old passphrase and reassign the passphrase given with this command.

curl -XPOST http://127.0.0.1:5359/api/ChangePassphrase \
-d '{"oldPassphrase": "demo123",
"newPassphrase": "demo234"}'

Required Data

ConfigurationDefaultNotes
oldPassphraseN/AOld Passphrase
newPassphraseN/ANew Passphrase


GetTransactionsByAddress

Get transactions hash and other details for a given address.

GetTransactionsByAddress Request

ParameterTypeDescription
addressStringQRL address

GetTransactionsByAddress Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetTransactionsByAddress Response Data

ParameterTypeDescription
mini_transactionsMiniTransactionList of MiniTransations which includes, transaction_hash, amount and out.
balanceUInt64Total balance

Retrieve all transaction information from the address given. This command will return all address information in one json array.

curl -XPOST http://127.0.0.1:5359/api/GetTransactionsByAddress \
-d '{"address": "Q01050028a8c31dd626a457cd74f4e86464ad308e2d41b7876bee67bb4fed03b54b91aa40bac36b"}'

Required Data

ConfigurationDefaultNotes
addressN/AQRL address
note

This may return significant information depending on the address queried and amount of transactions.



GetTransaction

Get transaction details for a given transaction hash.

GetTransaction Request

ParameterTypeDescription
tx_hashStringTransaction hash

GetTransaction Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetTransaction Response Data

ParameterTypeDescription
txTransactionTransaction Details
confirmationsUInt64The number of confirmations if any

Retrieve information for the transaction hash given.

This command will return transaction information in a json array.

curl -XPOST http://127.0.0.1:5359/api/GetTransaction \
-d '{"tx_hash": "7cd4ac054e60ecc0957032577bcde91dae0d5615534ec6b9d4692cba8f399368"}'

Required Data

ConfigurationDefaultNotes
tx_hashN/ATransaction hash


GetBalance

Retrieve balance information for the address given.

GetBalance Request

ParameterTypeDescription
addressStringQRL Address

GetBalance Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetBalance Response Data

ParameterTypeDescription
balanceUInt64Balance in Shor

Retrieve balance information for the address given.

curl -XPOST http://127.0.0.1:5359/api/GetBalance \
-d '{"address": "Q01050028a8c31dd626a457cd74f4e86464ad308e2d41b7876bee67bb4fed03b54b91aa40bac36b"}'

Required Data

ConfigurationDefaultNotes
addressN/AQRL Address


GetTotalBalance

Get total balance of all addresses found in wallet.

GetTotalBalance Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetTotalBalance Response Data

ParameterTypeDescription
balanceStringTotal Balance in Shor

Retrieve balance information for the walletd.json file loaded. Includes balances from all addresses contained in the wallet.

curl -XGET http://127.0.0.1:5359/api/GetTotalBalance


GetOTS

Retrieve next unused OTS key for the address given

GetOTS Request

ParameterTypeDescription
addressStringQRL Address

GetOTS Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetOTS Response Data

ParameterTypeDescription
next_unused_ots_indexUInt64Next Unused OTS Index

The GetOTS function will return the lowest unused OTS key from the network.

While a transaction is pending the next OTS will remain the same. Ensure proper OTS key tracking is performed in addition to the bitfield returned from the chain.

curl -XPOST http://127.0.0.1:5359/api/GetOTS \
-d '{"address": "Q01050028a8c31dd626a457cd74f4e86464ad308e2d41b7876bee67bb4fed03b54b91aa40bac36b"}'

Required Data

ConfigurationDefaultNotes
addressN/AQRL Address


GetHeight

Returns the connected node's blockheight.

note

This will return the connected node's blockheight, consensus with additional nodes to ensure the node is fully synced is recommended.

GetHeight Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.
heightUInt64Current Height of the blockchain

Queries the local node for it's greatest blockheight.

curl -XGET http://127.0.0.1:5359/api/GetHeight


GetBlock

Retrieve block information from a given block headerhash.

GetBlock Request

ParameterTypeDescription
header_hashStringBlock Header Hash

GetBlock Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetBlock Response Data

ParameterTypeDescription
blockBlockBlock Details

Given correct headerhash will return information on specified block.

curl -XPOST http://127.0.0.1:5359/api/GetBlock -d '{"header_hash": "72fd6f1d03c73a89c88fa9a62fa529b625fa24a2137b228029a24f5bb3fd0800"}'

Required Data

ConfigurationDefaultNotes
header_hashN/ABlock hash header


GetBlockByNumber

Return block information for a given block number.

GetBlockByNumber Request

ParameterTypeDescription
block_numberUInt64Block Number

GetBlockByNumber Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetBlockByNumber Response Data

ParameterTypeDescription
blockBlockBlock Details

Returns all block information by block number given.

curl -XPOST http://127.0.0.1:5359/api/GetBlockByNumber -d '{"block_number": "114714"}'

Required Data

ConfigurationDefaultNotes
block_numberN/ABlock number


GetAddressFromPK

Get QRL address for a given public key.

GetAddressFromPK Request

ParameterTypeDescription
pkBytesPublic key

GetAddressFromPK Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

GetAddressFromPK Response Data

ParameterTypeDescription
addressStringQRL Address

Given an addresses extended public key, return the QQ public QRL hex address.

curl -XPOST http://127.0.0.1:5359/api/GetAddressFromPK \
-d '{"pk": "0103009debb7b4a26c0a3d928e9fd9ba6868eff7ff0046c06211f339f40b6c9e8dc7fa8310ce74c502026f52929c5b4c895d6617e5cb7e927e883c40070d06390cc0c0"}'

Required Data

ConfigurationDefaultNotes
pkN/APublic key


GetNodeInfo

Returns information from the connected node.

GetNodeInfo Response

ParameterTypeDescription
codeUInt32Error Code. Only appears if any exception is triggered.
errorStringError Message. Only appears if any exception is triggered.

Will return information related to the connected node including:

  • version
  • num_connections
  • num_known_peers
  • uptime
  • block_height
  • block_last_hash
  • network_id
curl -XGET http://127.0.0.1:5359/api/GetNodeInfo