EDL Wallet RPC documentation


INTRODUCTION

This is a list of the edollar-wallet-rpc calls, their inputs and outputs, and examples of each. The program edollar-wallet-rpc replaced the rpc interface that was in edollar-wallet-cli. All edollar-wallet-rpc methods use the same JSON RPC interface. Note: "atomic units" refer to the smallest fraction of 1 EDL according to the edollard implementation. 1 EDL = 1000000000 (1e9) atomic units.

Start rpc wallet

./edollar-wallet-rpc --wallet-dir mydirectory --rpc-bind-port 8888
We can also specify which wallet to open
./edollar-wallet-rpc --wallet-file mywallet --rpc-bind-port 8888
And enable/disable rpc login
./edollar-wallet-rpc --wallet-file mywallet --rpc-bind-port 8888 --disable-rpc-login
./edollar-wallet-rpc --wallet-file mywallet --rpc-bind-port 8888 --rpc-login username:password
In case of enable rpc login, each rpc call needs to provide username:password like this

curl -u username:password --digest -X POST http://127.0.0.1:8888/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}' -H 'Content-Type: application/json'

For simplicity, we disable rpc login in all following examples

Wallet Notification

We can get transaction notification and block notification if run wallet-rpc with following flag
./edollar-wallet-rpc --notify-transaction syscall_command
./edollar-wallet-rpc --notify-pool-transaction syscall_command
./edollar-wallet-rpc --notify-block syscall_command
syscall_command is the system command that will be exected, the first argument is the txid/block_hash
  • --notify-transaction: call syscall_command when wallet received money (transaction has been added to block), first argument is txid of transaction
  • --notify-pool-transaction: call syscall_command when wallet received money but transaction is still in the mempool (transaction is waiting to be mined), first argument is txid of transaction
  • --notify-block: call syscall_command whenever new block generated, first argument is the block hash
Example ./edollar-wallet-rpc --wallet-file mywallet --rpc-bind-port 8888 --notify-transaction /home/ubuntu/tx_notify.sh
Where tx_notify.sh looks like
  
      #!/bin/bash 
      #remember to add the shabeng above
      txid=$1
      echo "Wallet received money, txid = $txid" >> transaction.txt
  
  
This will write txid to transaction.txt file everytime wallet received money

Note that the wallet notification is available on exchange-spport branch only. The pre-build wallet does not have this feature


Index of JSON RPC Methods



create_wallet

Create a new wallet. You need to have set the argument "–wallet-dir" when launching edollar-wallet-rpc to make this work.

Inputs:

  • filename - string;
  • password - string;
  • language - string; Language for your wallets' seed.

Outputs: none

Example:



curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"create_wallet","params":{"filename":"mytestwallet","password":"mytestpassword","language":"English"}}' \
-H 'Content-Type: application/json'


open_wallet

Open a wallet. You need to have set the argument "–wallet-dir" when launching edollar-wallet-rpc to make this work

Inputs:

  • filename - string;
  • password - string;

Outputs: none

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"open_wallet","params":{"filename":"mytestwallet","password":"mytestpassword"}}' \
-H 'Content-Type: application/json'


stop_wallet

Stops the wallet, storing the current state.

Inputs: None

Outputs: None

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"stop_wallet"}' -H 'Content-Type: application/json'


create_account

Create new sub account

Inputs:

  • label - label of account. It can be null

Outputs:

  • account_index- index of sub account
  • address - sub account address

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"create_account","params":{"label":"user1"}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "account_index": 1,
    "address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11"
  }
}

get_accounts

Get all accounts from wallet

Inputs: None

Outputs: List of account with following information

  • account_index- index of sub account
  • balance - balance of account
  • base_address - base address (address at index 0)
  • label - label of account
  • unlocked_balance - unlocked balance

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"get_accounts"}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "subaddress_accounts": [{
      "account_index": 0,
      "balance": 0,
      "base_address": "edrWdXoWoqbBxD5brMnL6Nj3cKM5RNjZo7DofP5HFrfCg6vrAdyoGbvfTpqtfKF3joi77LWckBgqidqygYv6wyyu2LcqrfcSQ",
      "label": "Primary account",
      "unlocked_balance": 0
    },{
      "account_index": 1,
      "balance": 20000000000,
      "base_address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11",
      "label": "user1",
      "unlocked_balance": 20000000000
    },{
      "account_index": 2,
      "balance": 30000000000,
      "base_address": "es2r3QrSj3mag61DfsuprD7CqjueCx8wxLNmseTu1PdpdSh2yNtmmAXbm72tuagLEQGnMJrFFawXvG1w9L8mVQEK2oEv13aH2",
      "label": "user2",
      "unlocked_balance": 30000000000
    }],
    "total_balance": 50000000000,
    "total_unlocked_balance": 50000000000
  }
}

create_address

Create new sub address

Inputs:

  • account_index - index of sub account that address will belong to
  • label - label of sub address. It can be null

Outputs:

  • address - sub address
  • address_index- index of sub address

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"create_address","params":{"account_index": 1,"label":"user1 first sub address"}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "address": "es1mKBK2N7jH8E9e1etpLC9ytYugEbXAiGCGJfaZr2h24xsMYdHXQWsVHkG7YtTrLECXpvy76tVXBFyy73GRX51S28PxAqc5Y",
    "address_index": 1
  }
}

getaddress

Get all address from account

Inputs:

  • account_index - index of sub account

Outputs:

  • address - Main address of account (address at index 0)
  • addresses- List of sub address with detail information

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"getaddress","params":{"account_index": 1}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11",
    "addresses": [{
      "address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11",
      "address_index": 0,
      "label": "user1",
      "used": false
    },{
      "address": "es1mKBK2N7jH8E9e1etpLC9ytYugEbXAiGCGJfaZr2h24xsMYdHXQWsVHkG7YtTrLECXpvy76tVXBFyy73GRX51S28PxAqc5Y",
      "address_index": 1,
      "label": "user1 first sub address",
      "used": false
    }]
  }
}

verify_address

Send edollar to a number of recipients.

Inputs

  • address - string, the address need to be verified

Outputs

  • valid - bool, true if address is valid, otherwise false

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"verify_address","params":{"address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11"}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "valid": true
  }
}


transfer

Send edollar to a number of recipients.

Inputs

  • account_index - unsigned int, index of account to be spent
  • subaddr_indices - Array of sub address index to be spent. If not specified, all sub address may be used
  • destinations - array of destinations to receive EDL
    • amount - unsigned int, Amount to send to each destination, in atomic units.
    • address - string, Destination public address.
  • mixin - unsigned int, Number of outputs from the blockchain to mix (dafault: 4)
  • unlock_time - unsigned int, Number of blocks before the EDL can be spent (0 to not add a lock).
  • get_tx_key - boolean, (Optional) Return the transaction key after sending
  • priority - unsigned int, Set a priority for the transaction. Accepted Values are: 0-3 for: default, unimportant, normal, elevated, priority.
  • do_not_relay - boolean, (Optional) If true, the newly created transaction will not be relayed to the edollar network. (Defaults to false)
  • get_tx_hex - boolean, Return the transaction as hex string after sending

Outputs

  • fee - Integer value of the fee charged for the txn.
  • tx_hash - String for the publically searchable transaction hash
  • tx_key - String for the transaction key if get_tx_key is true, otherwise, blank string.
  • tx_blob - Transaction as hex string if get_tx_hex is true

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"transfer","params":{"account_index": 1, "destinations":[{"amount":5000000000,"address":"edqKUGWa84y752hbSMyzQU268JQW7NdJ4ZgT4WTWChjBhhpeYHKTDBi3KrhRbQGk3qBHWnG3UyWpk66ea7AJLmUY2iqTozWX4"},{"amount":2000000000,"address":"es3a5YwWNKWSPHwxX9XEcvFWpdfGZE8LKYnZ4stKdscYG4jJP51RQTZ9G14AHojtTEQVyLCxxr6eQQDNxbQyyEHR31jqBYBkn"}], "get_tx_key": true}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "fee": 18400000,
    "tx_blob": "",
    "tx_hash": "9bac9dc9e5dcc1372b78790cccfcd173bf0bb14f781f8778dd1c307d517b2ec8",
    "tx_key": "4d531c1ac2b464e59b036943b125a02fce66ce00d512521fec094dea3ca63406"
  }
}


sweep_all

Send all unlocked balance to an address.

Inputs

  • account_index - unsigned int, index of account to be spent
  • subaddr_indices - Array of sub address index to be spent. If not specified, all sub address may be used
  • address - string, Destination public address.
  • mixin - unsigned int, Number of outputs from the blockchain to mix (dafault: 4)
  • unlock_time - unsigned int, Number of blocks before the EDL can be spent (0 to not add a lock).
  • get_tx_keys - boolean, (Optional) Return the transaction keys after sending
  • priority - unsigned int, Set a priority for the transaction. Accepted Values are: 0-3 for: default, unimportant, normal, elevated, priority.
  • do_not_relay - boolean, (Optional) If true, the newly created transaction will not be relayed to the edollar network. (Defaults to false)
  • get_tx_hex - boolean, Return the transaction as hex string after sending

Outputs

  • tx_hash_list - array of string
  • tx_key_list - array of string
  • tx_blob_list - array of string

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"sweep_all","params":{"account_index": 2, "address":"edqKUGWa84y752hbSMyzQU268JQW7NdJ4ZgT4WTWChjBhhpeYHKTDBi3KrhRbQGk3qBHWnG3UyWpk66ea7AJLmUY2iqTozWX4", "get_tx_keys": true}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "tx_hash_list": ["5bc8f4ed0c890a49f6ac7817c17f0fa1cc694b7c742d2f57c76508b3e73b0114"],
    "tx_key_list": ["b850a3399b14599e2fecf0bb2a92d8d49363be4a5f915cfd6ce6f0154e31fc05"]
  }
}


rescan_spent

Rescan the blockchain for spent outputs.

Inputs: None.

Outputs: None.

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"rescan_spent"}' -H 'Content-Type: application/json'



getbalance

Return the wallet's balance.

Inputs:

  • account_index - unsigned int; index of account

Outputs:

  • balance - unsigned int, The total balance of the account
  • unlocked_balance - unsigned int, Total unlocked balance of account
  • per_subaddress - array, Array of sub address balance (show only sub address with balance > 0)

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"getbalance", "params":{"account_index": 1}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "balance": 12981600000,
    "per_subaddress": [{
      "address": "es2tZAJogQa97dUJg4DjM9QWYEHD4JXmphJRVKRySVgrXP2FbdYvFCFgVwfPJR43skJKmJNg4ERs4Buj4jEG9hUf1tSb5hS11",
      "address_index": 0,
      "balance": 12981600000,
      "label": "user1",
      "num_unspent_outputs": 1,
      "unlocked_balance": 12981600000
    }],
    "unlocked_balance": 12981600000
  }
}


get_total_balance

Return the total wallet's balance.

Inputs: None

Outputs:

  • balance - unsigned int, The total balance of wallet
  • unlocked_balance - unsigned int, Total unlocked balance wallet

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"get_total_balance", "params":{}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "balance": 21000000000,
    "unlocked_balance": 21000000000
  }
}


incoming_transfers

Get received transaction

Return a list of incoming transfers to the wallet.

Inputs:

  • account_index - unsigned int, index of account we want to get transfers
  • transfer_type string, "all": all the transfers, "available": only transfers which are not yet spent, OR "unavailable": only transfers which are already spent.
  • subaddr_indices - list of sub address we want to get incoming transfer

Outputs: transfers - list of:

  • amount - unsigned int
  • spent - boolean, indicate that transaction has been spent or not
  • subaddr_index - index of sub address
  • global_index - unsigned int; Mostly internal use, can be ignored by most users.
  • tx_hash - string; Several incoming transfers may share the same hash if they were in the same transaction.
  • tx_size - unsigned int

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"incoming_transfers","params":{"account_index": 1, "transfer_type":"all"}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "transfers": [{
      "amount": 20000000000,
      "global_index": 464034,
      "spent": true,
      "subaddr_index": 0,
      "tx_hash": "8f9870611d98ad65e223902b1e2061e53a0a0747d6fb1ccf6ca32ebee5ebed62",
      "tx_size": 336
    },{
      "amount": 12981600000,
      "global_index": 464494,
      "spent": false,
      "subaddr_index": 0,
      "tx_hash": "9bac9dc9e5dcc1372b78790cccfcd173bf0bb14f781f8778dd1c307d517b2ec8",
      "tx_size": 286
    }]
  }
}

get_transfers

Returns a list of received/sent/pending/pool transaction.

Inputs:

  • account_index - unsigned int, index of sub account we want to get transfers
  • in - boolean, If set to true, return a list of incomming transaction to this account_index
  • out - boolean, If set to true, return a list of outgoing transaction from this account_index
  • pending - boolean, If set to true, return a list of pending transaction sent from this account_index
  • pool - boolean, If set to true, return a list of received transaction in mempool to this account_index
  • filter_by_height - boolean; If set to true, result will be filtered from min_height to max_height
  • min_height - unsigned int;
  • max_height - unsigned int;

Outputs:

  • in - array of incoming transaction (received transaction)
  • out - array of outgoing transaction (sent transaction)
  • pending - array of pending transaction (sent transaction with no confirmation)
  • pool - array of pool transaction (received transaction in mempool)
  • txid - string, transaction id
  • height - unsigned int, block height
  • timestamp - unsigned int, timestamp
  • amount - unsigned int;
  • fee - unsigned int;
  • note - string
  • subaddr_index - object of:
    • major - unsigned int, The sub account index. It is the account_index in input
    • minor - unsigned int, The sub address index of current account
  • destinations - array of recipients in format {address, amount} (outgoing transaction only)
  • type - string
    • in - incoming transaction (received transaction)
    • out - outgoing transaction (sent transaction)
    • pending - pending transaction (sent transaction with no confirmation)
    • pool - transaction in mempool (received transaction in mempool)

Example: Get all incoming and outgoing transaction of account at index 1


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"get_transfers","params":{"account_index": 1, "in": true, "out":true}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "in": [{
      "amount": 20000000000,
      "fee": 0,
      "height": 44333,
      "note": "",
      "subaddr_index": {
        "major": 1,
        "minor": 0
      },
      "timestamp": 1519362383,
      "txid": "8f9870611d98ad65e223902b1e2061e53a0a0747d6fb1ccf6ca32ebee5ebed62",
      "type": "in",
      "unlock_time": 0
    }],
    "out": [{
      "amount": 7000000000,
      "destinations": [{
        "address": "edqKUGWa84y752hbSMyzQU268JQW7NdJ4ZgT4WTWChjBhhpeYHKTDBi3KrhRbQGk3qBHWnG3UyWpk66ea7AJLmUY2iqTozWX4",
        "amount": 5000000000
      },{
        "address": "es3a5YwWNKWSPHwxX9XEcvFWpdfGZE8LKYnZ4stKdscYG4jJP51RQTZ9G14AHojtTEQVyLCxxr6eQQDNxbQyyEHR31jqBYBkn",
        "amount": 2000000000
      }],
      "fee": 18400000,
      "height": 44413,
      "note": "",
      "subaddr_index": {
        "major": 1,
        "minor": 0
      },
      "timestamp": 1519373697,
      "txid": "9bac9dc9e5dcc1372b78790cccfcd173bf0bb14f781f8778dd1c307d517b2ec8",
      "type": "out",
      "unlock_time": 0
    }]
  }
}

get_transfer_by_txid

Show information about a transfer of txid

Inputs:

  • txid - string, transaction id

Outputs: transfer - JSON object containing following information:

  • amount - unsigned int, total amount of transfer
  • destinations - array of recipients in format {address, amount} (in outgoing transaction only)
  • fee - unsigned int, transaction fee (in outgoing transaction only)
  • height - unsigned int, block height
  • note - string, a note of this transaction
  • subaddr_index - object of:
    • major - unsigned int, The sub account index
    • minor - unsigned int, The sub address index of current account
  • timestamp - unsigned int, timestamp
  • txid - string, transaction id
  • type - string
    • in - incoming transaction (received transaction)
    • out - outgoing transaction (sent transaction)
    • pending - pending transaction (sent transaction with no confirmation)
    • pool - transaction in mempool (received transaction in mempool)

Example:


curl -X POST http://127.0.0.1:8888/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"get_transfer_by_txid","params":{"txid":"9bac9dc9e5dcc1372b78790cccfcd173bf0bb14f781f8778dd1c307d517b2ec8"}}' \
-H 'Content-Type: application/json'

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "transfer": {
      "amount": 7000000000,
      "destinations": [{
        "address": "edqKUGWa84y752hbSMyzQU268JQW7NdJ4ZgT4WTWChjBhhpeYHKTDBi3KrhRbQGk3qBHWnG3UyWpk66ea7AJLmUY2iqTozWX4",
        "amount": 5000000000
      },{
        "address": "es3a5YwWNKWSPHwxX9XEcvFWpdfGZE8LKYnZ4stKdscYG4jJP51RQTZ9G14AHojtTEQVyLCxxr6eQQDNxbQyyEHR31jqBYBkn",
        "amount": 2000000000
      }],
      "fee": 18400000,
      "height": 44413,
      "note": "",
      "subaddr_index": {
        "major": 1,
        "minor": 0
      },
      "timestamp": 1519373697,
      "txid": "9bac9dc9e5dcc1372b78790cccfcd173bf0bb14f781f8778dd1c307d517b2ec8",
      "type": "out",
      "unlock_time": 0
    }
  }
}