diff --git a/resources/developer-guides/wallet-rpc.md b/resources/developer-guides/wallet-rpc.md index ab6c73a5..1943e27e 100644 --- a/resources/developer-guides/wallet-rpc.md +++ b/resources/developer-guides/wallet-rpc.md @@ -46,15 +46,35 @@ Note: "atomic units" refer to the smallest fraction of 1 XMR according to the mo * [transfer](#transfer) * [transfer_split](#transfersplit) * [sweep_dust](#sweepdust) +* [sweep_all](#sweepall) * [store](#store) * [get_payments](#getpayments) * [get_bulk_payments](#getbulkpayments) * [get_transfers](#gettransfers) +* [get_transfer_by_txid](#gettransferbytxid) * [incoming_transfers](#incomingtransfers) * [query_key](#querykey) * [make_integrated_address](#makeintegratedaddress) * [split_integrated_address](#splitintegratedaddress) * [stop_wallet](#stopwallet) +* [make_uri](#makeuri) +* [parse_uri](#parseuri) +* [rescan_blockchain](#rescanblockchain) +* [set_tx_notes](#settxnotes) +* [get_tx_notes](#gettxnotes) +* [sign](#sign) +* [verify](#verify) +* [export_key_images](#exportkeyimages) +* [import_key_images](#importkeyimages) +* [get_address_book](#getaddressbook) +* [add_address_book](#addaddressbook) +* [delete_address_book](#deleteaddressbook) +* [rescan_spent](#rescanspent) +* [start_mining](#startmining) +* [stop_mining](#stopmining) +* [get_languages](#getlanguages) +* [create_wallet](#createwallet) +* [open_wallet](#openwallet) --- @@ -116,7 +136,7 @@ Inputs: *None*. Outputs: -* *height* - string; The current monero-wallet-rpc's blockchain height. If the wallet has been offline for a long time, it may need to catch up with the daemon. +* *height* - unsigned int; The current monero-wallet-rpc's blockchain height. If the wallet has been offline for a long time, it may need to catch up with the daemon. Example: @@ -145,6 +165,7 @@ Inputs: * *unlock_time* - unsigned int; Number of blocks before the monero can be spent (0 to not add a lock). * *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: * *fee* - Integer value of the fee charged for the txn. @@ -224,6 +245,32 @@ Example (In this example, `sweep_dust` returns an error due to insufficient fund "jsonrpc": "2.0" } +### sweep_all + +Send all unlocked balance to an address. + +Inputs: + +* *address* - string; Destination public address. +* *priority* - unsigned int; (Optional) +* *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; (Optional) Random 32-byte/64-character hex string to identify a transaction. +* *get_tx_keys* - boolean; (Optional) Return the transaction key after sending. +* *below_amount* - unsigned int; (Optional) +* *do_not_relay* - boolean; (Optional) +* *get_tx_hex* - boolean; (Optional) + +Outputs: + +* *tx_hash_list* - array of string; +* *tx_key_list* - array of string; + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"sweep_all","params":{"address":"9sS8eRU2b5ZbN2FPSrpkiab1bjbHE5XtL6Ti6We3Fhw5aQPudRfVVypjgzKDNkxtvTQSPs122NKggb2mqcqkKSeMNVu59S","mixin":2,"unlock_time":0,"get_tx_keys":true}}' -H 'Content-Type: application/json' + ### store Save the blockchain. @@ -370,6 +417,46 @@ Example: } } +### get_transfer_by_txid + +Show information about a transfer to/from this address. + +Inputs: + +* *txid* - string + +Outputs: + +* *transfer* - JSON object containing parment information: + * *amount* - unsigned int + * *fee* - unsigned int + * *height* - unsigned int + * *note* - string + * *payment_id* - string + * *timestamp* - unsigned int + * *txid* - string + * *type* - string + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_transfer_by_txid","params":{"txid":"f2d33ba969a09941c6671e6dfe7e9456e5f686eca72c1a94a3e63ac6d7f27baf"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "transfer": { + "amount": 10000000000000, + "fee": 0, + "height": 1316388, + "note": "", + "payment_id": "0000000000000000", + "timestamp": 1495539310, + "txid": "f2d33ba969a09941c6671e6dfe7e9456e5f686eca72c1a94a3e63ac6d7f27baf", + "type": "in" + } + } +} ### incoming_transfers @@ -588,7 +675,7 @@ 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":"make_uri","params":{"address":"44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A","amount":10,"payment_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","tx_description":"Testing out the make_uri function.","recipient_name":"Monero Project donation address"}}' -H 'Content-Type: application/json' +<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_uri","params":{"address":"44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A","amount":10,"payment_id":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","tx_description":"Testing out the make_uri function.","recipient_name":"Monero Project donation address"}}' -H 'Content-Type: application/json' { "id": 0, "jsonrpc": "2.0", @@ -598,7 +685,7 @@ Example: } -## parse_uri +### parse_uri Parse a payment URI to get payment information. @@ -608,7 +695,7 @@ Inputs: Outputs: -* *uri* - JSON object containing parment information: +* *uri* - JSON object containing payment information: * *address* - wallet address string * *amount* - the decimal amount to receive, in **coin** units (0 if not provided) * *payment_id* - 16 or 64 character hexadecimal payment id string (empty if not provided) @@ -618,7 +705,7 @@ 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":"parse_uri","params":{"uri":"monero:44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A?tx_payment_id=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef&tx_amount=0.000000000010&recipient_name=Monero%20Project%20donation%20address&tx_description=Testing%20out%20the%20make_uri%20function."}}' -H 'Content-Type: application/json' +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://127.0.0.1:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"parse_uri","params":{"uri":"monero:44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsaBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A?tx_payment_id=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef&tx_amount=0.000000000010&recipient_name=Monero%20Project%20donation%20address&tx_description=Testing%20out%20the%20make_uri%20function."}}' -H 'Content-Type: application/json' { "id": 0, "jsonrpc": "2.0", @@ -632,3 +719,388 @@ Example: } } } + +### rescan_blockchain + +Rescan blockchain from scratch. + +Inputs: *None*. + +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":"rescan_blockchain" -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### set_tx_notes + +Set an arbitrary string notes for transactions. + +Inputs: + * *txids* - - array of string; transaction ids + * *notes* - - array of string; notes for the transactions + +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":"set_tx_notes","params":{"txids":["6a1a100c079c236e2cbf36f7760e8ef1a9e8357c434aa790a8c78de653ec4cf2"],"notes":["This is an example"]}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### get_tx_notes + +Get a string note for a transaction. + + +Inputs: + +* *txids* - array of: string; transaction ids + +Outputs: + +* *notes* - array of: string; notes for the transactions + +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_tx_notes","params":{"txids":["6a1a100c079c236e2cbf36f7760e8ef1a9e8357c434aa790a8c78de653ec4cf2"]}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "notes": ["This is an example"] + } +} + +### sign + +Sign a string. + +Inputs: + +* *data* - string; + +Outputs: + +* *signature* - 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":"sign","params":{"data":"This is sample data to be signed"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "signature": "SigV1Xp61ZkGguxSCHpkYEVw9eaWfRfSoAf36PCsSCApx4DUrKWHEqM9CdNwjeuhJii6LHDVDFxvTPijFsj3L8NDQp1TV" + } +} + +### verify + +Verify a signature on the contents of a string. + +Inputs: + +* *data* - string; +* *address* - string; +* *signature* - string; + +Outputs: + +* *good* - boolean; + +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":"verify","params":{"data":"This is sample data to be signed","address":"9sS8eRU2b5ZbN2FPSrpkiab1bjbHE5XtL6Ti6We3Fhw5aQPudRfVVypjgzKDNkxtvTQZSPs122NKggb2mqcqkKSeMNVu59S","signature":"SigV1Xp61ZkGguxSCHpkYEVw9eaWfRfSoAf36PCsSCApx4DUrKWHEqM9CdNwjeuhJii6LHDVDFxvTPijFsj3L8NDQp1TV"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "good": true + } +} + +### export_key_images + +Export a signed set of key images. + +Inputs: *None*. + +Outputs: + +* *signed_key_images* - array of signed key images: + * *key_image* - string; + * *signature* - string; + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"export_key_images"}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "signed_key_images": [{ + "key_image": "62b83df78baad99e23b5ad3f667bc6f8d388a13d9e84c7bb6c223a556dfd34af", + "signature": "b87b7e989aa85aa3a2a7cd8adcb3a848d3512ff718b168e15217ff3e5da29c0183c0328b97cc052fcb5ee3548aa5e41e530ba9d854199ea19d7ddaf6a54a4c0a" + }] + } +} + +### import_key_images + +Import signed key images list and verify their spent status. + +Inputs: + +* *signed_key_images* - array of signed key images: + * *key_image* - string; + * *signature* - string; + +Outputs: + +* *height* - unsigned int; +* *spent* - unsigned int; +* *unspent* - unsigned int; + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"import_key_images", "params":{"signed_key_images":[{"key_image":"63b83df78cafd99e23b5ad3f667bc6f8d38813d9e84c7bb6c223a556dfd34af","signature":"b87b7e989aa86aa2a7a7cd8adcb3a848d3512ff718b168e15217ff3e5da29c0183c0328b97cc052fcb5ee3548aa5e41e530ba9d854199ea19d7ddaf6a54a4c0a"},{"key_image":"44ec12fbc56c533a30b09de8ae26febd515528c4957dfe875430377a7e212b4e","signature":"91105f15be0b25bc2a94bd78a7e261608974d6d888080b9f1815655b98af190340325ea1a0840a5951dacf913d4de1b2bd33ea59c1cb7bce1b6648afa7133d03"}]}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "height": 986050, + "spent": 10000100000000, + "unspent": 4979852760000 + } +} + +### get_address_book + +Retrieves entries from the address book. + +Inputs: + +* *entries* - array of unsigned int; indices of the requested address book entries + +Outputs: + +* *entries* - array of entries: + * *address* - string; + * *description* - string; + * *index* - unsigned int; + * *payment_id* - string; + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_address_book","params":{"entries":[1,2]}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "entries": [{ + "address": "A135xq3GVMdU5qtAm4hN7zjPgz8bRaiSUQmtuDdjZ6CgXayvQruJy3WPe95qj873JhK4YdTQjoR39Leg6esznQk8PckhjRN", + "description": "", + "index": 1, + "payment_id": "0000000000000000000000000000000000000000000000000000000000000000" + },{ + "address": "A135xq3GVMdU5qtAm4hN7zjPgz8bRaiSUQmtuDdjZ6CgXayvQruJy3WPe95qj873JhK4YdTQjoR39Leg6esznQk8PckhjRN", + "description": "", + "index": 2, + "payment_id": "0000000000000000000000000000000000000000000000000000000000000000" + }] + } +} + +### add_address_book + +Add an entry to the address book. + +Inputs: + +* *address* - string; +* *payment_id* - (optional) string, defaults to "0000000000000000000000000000000000000000000000000000000000000000"; +* *description* - (optional) string, defaults to ""; + +Outputs: + +* *index* - unsigned int; The index of the address book entry. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"add_address_book","params":{"address":"44AFFq5kSiGBoZ4NMDwYtN18obc8AemS33DBLWs3H7otXft3XjrpDtQGv7SqSsBYBb98uNbr2VBBEt7f2wfn3RVGQBEP3A","description":"Donation address for the Monero project"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "index": 2 + } +} + +### delete_address_book + +Delete an entry from the address book. + +Inputs: + +* *index* - unsigned int; The index of the address book entry. + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"delete_address_book","params":{"index":0}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### rescan_spent + +Rescan the blockchain for spent outputs. + +Inputs: *None*. + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"rescan_spent"}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### start_mining + +Start mining in the Monero daemon. + +Inputs: + +* *threads_count* - unsigned int; Number of threads created for mining +* *do_background_mining* - boolean; +* *ignore_battery* - boolean; + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"start_mining","params":{"threads_count":1,"do_background_mining":true,"ignore_battery":true}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} +### stop_mining + +Stop mining in the Monero daemon. + +Inputs: *None*. + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"stop_mining"}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### get_languages + +Get a list of available languages for your wallet's seed. + +Inputs: *None*. + +Outputs: + +* *languages* - array of string; List of available languages + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"get_languages"}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + "languages": ["Deutsch","English","Español","Français","Italiano","Nederlands","Português","русский язык","日本語","简体中文 (中国)","Esperanto"] + } +} + +### create_wallet + +Create a new wallet. You need to have set the argument "--wallet-dir" when launching monero-wallet-rpc to make this work. + +Inputs: + +* *filename* - string; +* *password* - string; +* *language* - string; Language for your wallets' seed. + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"create_wallet","params":{"filename":"mytestwallet","password":"mytestpassword","language":"English"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +} + +### open_wallet + +Open a wallet. You need to have set the argument "--wallet-dir" when launching monero-wallet-rpc to make this work. + +Inputs: + +* *filename* - string; +* *password* - string; + +Outputs: *None*. + +Example: + +{:.cli-code} +<span style="color: cyan;">[ monero->~ ]$</span> curl -X POST http://localhost:18082/json_rpc -d '{"jsonrpc":"2.0","id":"0","method":"open_wallet","params":{"filename":"mytestwallet","password":"mytestpassword"}}' -H 'Content-Type: application/json' +{ + "id": "0", + "jsonrpc": "2.0", + "result": { + } +}