From 32ba7ea352e8d1f14125b1bfa7979c1c39bb8167 Mon Sep 17 00:00:00 2001
From: Mike C <micro-machine@users.noreply.github.com>
Date: Sat, 12 Mar 2016 10:54:04 -0700
Subject: [PATCH] revamped wallet-rpc dev guide

---
 knowledge-base/developer-guides/wallet-rpc.md | 294 ++++++++++++++++--
 1 file changed, 261 insertions(+), 33 deletions(-)

diff --git a/knowledge-base/developer-guides/wallet-rpc.md b/knowledge-base/developer-guides/wallet-rpc.md
index 4ae61a65..fde78b37 100644
--- a/knowledge-base/developer-guides/wallet-rpc.md
+++ b/knowledge-base/developer-guides/wallet-rpc.md
@@ -24,25 +24,28 @@ All simplewallet methods use the same JSON RPC interface. For example:
         -d '{"jsonrpc":"2.0","id":"0","method":"'$METHOD'","params":'"$PARAMS"'}' \
         -H 'Content-Type: application/json'
 
-### JSON RPC Methods:
+
+### Index of JSON RPC Methods:
 
 * [getbalance](#getbalance)
 * [getaddress](#getaddress)
 * [getheight](#getheight)
 * [transfer](#transfer)
-* [transfer_split](#transfer_split)
-* [sweep_dust](#sweep_dust)
+* [transfer_split](#transfersplit)
+* [sweep_dust](#sweepdust)
 * [store](#store)
-* [get_payments](#get_payments)
-* [get_bulk_payments](#get_bulk_payments)
-* [incoming_transfers](#incoming_transfers)
-* [query_key](#query_key)
-* [make_integrated_address](#make_integrated_address)
-* [split_integrated_address](#split_integrated_address)
-* [stop_wallet](#stop_wallet)
+* [get_payments](#getpayments)
+* [get_bulk_payments](#getbulkpayments)
+* [incoming_transfers](#incomingtransfers)
+* [query_key](#querykey)
+* [make_integrated_address](#makeintegratedaddress)
+* [split_integrated_address](#splitintegratedaddress)
+* [stop_wallet](#stopwallet)
 
 ---
 
+## JSON RPC Methods:
+
 ### getbalance
 
 Return the wallet's balance.
@@ -51,11 +54,22 @@ Inputs: *None*.
 
 Outputs:
 
-* *balance* - unsigned int
-* *unlocked_balance* - unsigned int
+* *balance* - unsigned int; The total balance of the current simplewallet in session.
+* *unlocked_balance* - unsigned int; Unlocked funds are those funds that are sufficiently deep enough in the Monero blockchain to be considered safe to spend.
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "balance": 140000000000,
+    "unlocked_balance": 50000000000
+  }
+}
+
 
 ### getaddress
 
@@ -65,10 +79,20 @@ Inputs: *None*.
 
 Outputs:
 
-* *address* - string
+* *address* - string; The 95-character hex address string of the simplewallet in session.
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getaddress"}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "address": "427ZuEhNJQRXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQGaDsaBA"
+  }
+}
+
 
 ### getheight
 
@@ -78,10 +102,20 @@ Inputs: *None*.
 
 Outputs:
 
-* *height* - string
+* *height* - string; The current simplewallet's blockchain height. If the wallet has been offline for a long time, it may need to catch up with the daemon.
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"getheight"}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "height": 994310
+  }
+}
+
 
 ### transfer
 
@@ -89,20 +123,32 @@ Send monero to a number of recipients.
 
 Inputs:
 
-* *destinations* - array of:
-  * *amount* - unsigned int
-  * *address* - string
+* *destinations* - array of destinations to receive XMR:
+  * *amount* - unsigned int; Amount to send to each destination, in atomic units.
+  * *address* - string; Destination public address.
 * *fee* - unsigned int; Ignored, will be automatically calculated.
 * *mixin* - unsigned int; Number of outpouts from the blockchain to mix with (0 means no mixing).
 * *unlock_time* - unsigned int; Number of blocks before the monero can be spent (0 to not add a lock).
-* *payment_id* - string
-
+* *payment_id* - string; (Optional) Random 32-byte/64-character hex string to identify a transaction.
+* *get_tx_key* - boolean; (Optional) Return the transaction key after sending.
 Outputs:
 
 * *tx_hash* - array of: string
+* *tx_key* - 
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"transfer","params":{"destinations":[{"amount":10000000000000,"address":"427ZuEhNJQRXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQGaDsaBA"},{"amount":200000000000,"address":"49VtwYXDbbh7hq57wwkLH36x4D6XV6Tr2P93ANnBi9qFGyYZbx8SXWPUHC9V1o7N41b4c3WJ1kubkffRfPTPfMuB8QUqFD5"}],"fee":150000000000,"mixin":3,"unlock_time":0,"payment_id":"001f181e2a2e076e8451e9dd7b5fe8fbd2b204cd6a20cb3e21b9a2a42b0ce03c","get_tx_key":true}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "tx_hash": "&lt;29d933789db5483fa63694ed2560d3829dbf0b945fdea3c42fbfa4d381e7ac22&gt;",
+    "tx_key": "&lt;c228dff7aa455d770f8cf71b9d319d2055a125cfbac1ca9485aeb1a107604d0d&gt;"
+  }
+}
+
 
 ### transfer_split
 
@@ -110,21 +156,32 @@ Same as transfer, but can split into more than one tx if necessary.
 
 Inputs:
 
-* *destinations* - array of:
-  * *amount* - unsigned int
-  * *address* - string
+* *destinations* - array of destinations to receive XMR:
+  * *amount* - unsigned int; Amount to send to each destination, in atomic units.
+  * *address* - string; Destination public address.
 * *fee* - unsigned int; Ignored, will be automatically calculated.
 * *mixin* - unsigned int; Number of outpouts from the blockchain to mix with (0 means no mixing).
 * *unlock_time* - unsigned int; Number of blocks before the monero can be spent (0 to not add a lock).
-* *payment_id* - string
+* *payment_id* - string; (Optional) Random 32-byte/64-character hex string to identify a transaction.
+* *get_tx_key* - boolean; (Optional) Return the transaction key after sending.
 * *new_algorithm* - boolean; True to use the new transaction construction algorithm, defaults to false.
 
 Outputs:
 
-* *tx_hash* - array of: string
+* *tx_hash_list* - array of: string
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"transfer_split","params":{"destinations":[{"amount":2000000000000,"address":"427ZuEhNJQRXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQGaDsaBA"},{"amount":3000000000000,"address":"49VtwYXDbbh7hq57wwkLH36x4D6XV6Tr2P93ANnBi9qFGyYZbx8SXWPUHC9V1o7N41b4c3WJ1kubkffRfPTPfMuB8QUqFD5"}],"mixin":3,"unlock_time":0,"payment_id":"a29602cc261fecbc93c22a152a942cc791ca6112cffe201c3e809945c9da672f","get_tx_key":true,"new_algorithm":true}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "tx_hash_list": ["&lt;fb39c42cb5ff231ee9e8b381bb8734fd655b6ca28a23cbd82aa9422aa870e91b&gt;"]
+  }
+}
+
 
 ### sweep_dust
 
@@ -136,8 +193,18 @@ Outputs:
 
 * *tx_hash_list* - list of: string
 
-Example:
+Example (In this example, `sweep_dust` returns an error due to insufficient funds to sweep):
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"sweep_dust"}' -H 'Content-Type: application/json'
+{
+  "error": {
+    "code": -4,
+    "message": "not enough money"
+  },
+  "id": "0",
+  "jsonrpc": "2.0"
+}
 
 ### store
 
@@ -145,10 +212,19 @@ Save the blockchain.
 
 Inputs: *None*.
 
-Outputs:
+Outputs: *None*.
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"store"}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+  }
+}
+
 
 ### get_payments
 
@@ -169,10 +245,26 @@ Outputs:
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_payments","params":{"payment_id":"4279257e0a20608e25dba8744949c9e1caff4fcdafc7d5362ecf14225f3d9030"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "payments": [{
+      "amount": 10350000000000,
+      "block_height": 994327,
+      "payment_id": "4279257e0a20608e25dba8744949c9e1caff4fcdafc7d5362ecf14225f3d9030",
+      "tx_hash": "c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1",
+      "unlock_time": 0
+    }]
+  }
+}
+
 
 ### get_bulk_payments
 
-Get a list of incoming payments using a given payment id, or a list of payments ids, from a given height.
+Get a list of incoming payments using a given payment id, or a list of payments ids, from a given height. This method is the preferred method over `get_payments` because it has the same functionality but is more extendable. Either is fine for looking up transactions by a single payment ID.
 
 Inputs:
 
@@ -190,6 +282,22 @@ Outputs:
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_bulk_payments","params":{"payment_ids":["4279257e0a20608e25dba8744949c9e1caff4fcdafc7d5362ecf14225f3d9030"],"min_block_height":990000}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "payments": [{
+      "amount": 10350000000000,
+      "block_height": 994327,
+      "payment_id": "4279257e0a20608e25dba8744949c9e1caff4fcdafc7d5362ecf14225f3d9030",
+      "tx_hash": "c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1",
+      "unlock_time": 0
+    }]
+  }
+}
+
 
 ### incoming_transfers
 
@@ -208,7 +316,76 @@ Outputs:
   * *tx_hash* - string; Several incoming transfers may share the same hash if they were in the same transaction.
   * *tx_size* - unsigned int
 
-Example:
+Example (Return "all" transaction types):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"incoming_transfers","params":{"transfer_type":"all"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "transfers": [{
+      "amount": 10000000000000,
+      "global_index": 711506,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    },{
+      "amount": 300000000000,
+      "global_index": 794232,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    },{
+      "amount": 50000000000,
+      "global_index": 213659,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    }]
+  }
+}
+
+Example (Return "available" transactions):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"incoming_transfers","params":{"transfer_type":"available"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "transfers": [{
+      "amount": 10000000000000,
+      "global_index": 711506,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    },{
+      "amount": 300000000000,
+      "global_index": 794232,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    },{
+      "amount": 50000000000,
+      "global_index": 213659,
+      "spent": false,
+      "tx_hash": "&lt;c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1&gt;",
+      "tx_size": 5870
+    }]
+  }
+}
+
+Example (Return "unavailable" transaction. Note that this particular example returns 0 unavailable transactions):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"incoming_transfers","params":{"transfer_type":"unavailable"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+  }
+}
 
 
 ### query_key
@@ -217,13 +394,35 @@ Return the spend or view private key.
 
 Inputs:
 
-* *key_type* - string; which key to retrieve: "mnemonic" - the mnemonic seed (older wallets do not have one) OR "view_key" - the view key
+* *key_type* - string; Which key to retrieve: "mnemonic" - the mnemonic seed (older wallets do not have one) OR "view_key" - the view key
 
 Outputs:
 
-* *key* - string; the view key will be hex encoded
+* *key* - string; The view key will be hex encoded, while the mnemonic will be a string of words.
 
-Example:
+Example (Query view key):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"query_key","params":{"key_type":"view_key"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "key": "7e341d..."
+  }
+}
+
+Example (Query mnemonic key):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"query_key","params":{"key_type":"mnemonic"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "key": "adapt adapt nostril ..."
+  }
+}
 
 
 ### make_integrated_address
@@ -238,7 +437,17 @@ Outputs:
 
 * *integrated_address* - string
 
-Example:
+Example (Payment ID is empty, use a random ID):
+
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"make_integrated_address","params":{"payment_id":""}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "integrated_address": "4BpEv3WrufwXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQQ8H2RRJveAtUeiFs6J"
+  }
+}
 
 
 ### split_integrated_address
@@ -256,6 +465,17 @@ Outputs:
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"split_integrated_address","params":{"integrated_address": "4BpEv3WrufwXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQQ8H2RRJveAtUeiFs6J"}}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+    "payment_id": "&lt;420fa29b2d9a49f5&gt;",
+    "standard_address": "427ZuEhNJQRXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQGaDsaBA"
+  }
+}
+
 
 ### stop_wallet
 
@@ -263,8 +483,16 @@ Stops the wallet, storing the current state.
 
 Inputs: *None*.
 
-Outputs:
+Outputs: *None*.
 
 Example:
 
+{:.cli-code}
+<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"stop_wallet"}' -H 'Content-Type: application/json'
+{
+  "id": "0",
+  "jsonrpc": "2.0",
+  "result": {
+  }
+}
 
-- 
GitLab