2015-06-14 14:53:53 +03:00
---
layout: static_page
title: "Wallet RPC documentation"
2016-03-12 06:33:52 +02:00
title-pre-kick: "Developer Guide: "
2015-06-14 14:53:53 +03:00
title-kick: "Wallet RPC documentation "
title-post-kick: ""
kick-class: "green-kicks"
icon: "icon_client"
attribution: "<!-- Icon is based on work by Freepik (http://www.freepik.com) and is licensed under Creative Commons BY 3.0 --> "
---
2016-03-12 07:17:09 +02:00
## Introduction
This is a list of the simplewallet RPC calls, their inputs and outputs, and examples of each.
All simplewallet methods use the same JSON RPC interface. For example:
IP=127.0.0.1
PORT=18082
METHOD="make_integrated_address"
PARAMS="{\"payment_id\":\"1234567890123456789012345678900012345678901234567890123456789000\"}"
curl \
-X POST http://$IP:$PORT/json_rpc \
-d '{"jsonrpc":"2.0","id":"0","method":"'$METHOD'","params":'"$PARAMS"'}' \
-H 'Content-Type: application/json'
2016-03-12 19:54:33 +02:00
Note: In the following guide, "atomic units" refer to the smallest fraction of 1 Monero according to the bitmonerod and simplewallet implementation. **1 XMR = 1e12 atomic units.**
2016-03-12 19:54:04 +02:00
### Index of JSON RPC Methods:
2016-03-12 07:17:09 +02:00
* [getbalance ](#getbalance )
* [getaddress ](#getaddress )
* [getheight ](#getheight )
* [transfer ](#transfer )
2016-03-12 19:54:04 +02:00
* [transfer_split ](#transfersplit )
* [sweep_dust ](#sweepdust )
2016-03-12 07:17:09 +02:00
* [store ](#store )
2016-03-12 19:54:04 +02:00
* [get_payments ](#getpayments )
* [get_bulk_payments ](#getbulkpayments )
* [incoming_transfers ](#incomingtransfers )
* [query_key ](#querykey )
* [make_integrated_address ](#makeintegratedaddress )
* [split_integrated_address ](#splitintegratedaddress )
* [stop_wallet ](#stopwallet )
2016-03-12 07:17:09 +02:00
---
2016-03-12 19:54:04 +02:00
## JSON RPC Methods:
2016-03-12 07:17:09 +02:00
### getbalance
Return the wallet's balance.
Inputs: *None* .
Outputs:
2016-03-12 19:54:04 +02:00
* *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.
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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
}
}
2016-03-12 07:17:09 +02:00
### getaddress
Return the wallet's address.
Inputs: *None* .
Outputs:
2016-03-12 19:54:04 +02:00
* *address* - string; The 95-character hex address string of the simplewallet in session.
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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"
}
}
2016-03-12 07:17:09 +02:00
### getheight
Returns the wallet's current block height.
Inputs: *None* .
Outputs:
2016-03-12 19:54:04 +02:00
* *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.
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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
}
}
2016-03-12 07:17:09 +02:00
### transfer
Send monero to a number of recipients.
Inputs:
2016-03-12 19:54:04 +02:00
* *destinations* - array of destinations to receive XMR:
* *amount* - unsigned int; Amount to send to each destination, in atomic units.
* *address* - string; Destination public address.
2016-03-12 07:17:09 +02:00
* *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).
2016-03-12 19:54:04 +02:00
* *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.
2016-03-12 07:17:09 +02:00
Outputs:
* *tx_hash* - array of: string
2016-03-12 19:54:04 +02:00
* *tx_key* -
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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": "< 29d933789db5483fa63694ed2560d3829dbf0b945fdea3c42fbfa4d381e7ac22> ",
"tx_key": "< c228dff7aa455d770f8cf71b9d319d2055a125cfbac1ca9485aeb1a107604d0d> "
}
}
2016-03-12 07:17:09 +02:00
### transfer_split
Same as transfer, but can split into more than one tx if necessary.
Inputs:
2016-03-12 19:54:04 +02:00
* *destinations* - array of destinations to receive XMR:
* *amount* - unsigned int; Amount to send to each destination, in atomic units.
* *address* - string; Destination public address.
2016-03-12 07:17:09 +02:00
* *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).
2016-03-12 19:54:04 +02:00
* *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.
2016-03-12 07:17:09 +02:00
* *new_algorithm* - boolean; True to use the new transaction construction algorithm, defaults to false.
Outputs:
2016-03-12 19:54:04 +02:00
* *tx_hash_list* - array of: string
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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": ["< fb39c42cb5ff231ee9e8b381bb8734fd655b6ca28a23cbd82aa9422aa870e91b> "]
}
}
2016-03-12 07:17:09 +02:00
### sweep_dust
Send all dust outputs back to the wallet's, to make them easier to spend (and mix).
Inputs: *None* .
Outputs:
* *tx_hash_list* - list of: string
2016-03-12 19:54:04 +02:00
Example (In this example, `sweep_dust` returns an error due to insufficient funds to sweep):
2016-03-12 07:17:09 +02:00
2016-03-12 19:54:04 +02:00
{:.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"
}
2016-03-12 07:17:09 +02:00
### store
Save the blockchain.
Inputs: *None* .
2016-03-12 19:54:04 +02:00
Outputs: *None* .
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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": {
}
}
2016-03-12 07:17:09 +02:00
### get_payments
Get a list of incoming payments using a given payment id.
Inputs:
* *payment_id* - string
Outputs:
* *payments* - list of:
* *payment_id* - string
* *tx_hash* - string
* *amount* - unsigned int
* *block_height* - unsigned int
* *unlock_time* - unsigned int
Example:
2016-03-12 19:54:04 +02:00
{:.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
}]
}
}
2016-03-12 07:17:09 +02:00
### get_bulk_payments
2016-03-12 19:54:04 +02:00
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.
2016-03-12 07:17:09 +02:00
Inputs:
* *payment_ids* - array of: string
* *min_block_height* - unsigned int; The block height at which to start looking for payments.
Outputs:
* *payments* - list of:
* *payment_id* - string
* *tx_hash* - string
* *amount* - unsigned int
* *block_height* - unsigned int
* *unlock_time* - unsigned int
Example:
2016-03-12 19:54:04 +02:00
{:.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
}]
}
}
2016-03-12 07:17:09 +02:00
### incoming_transfers
Return a list of incoming transfers to the wallet.
Inputs:
* *transfer_type* - string; "all": all the transfers, "available": only transfers which are not yet spent, OR "unavailable": only transfers which are already spent.
Outputs:
* *transfers* - list of:
* *amount* - unsigned int
* *spent* - boolean
* *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
2016-03-12 19:54:04 +02:00
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": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"tx_size": 5870
},{
"amount": 300000000000,
"global_index": 794232,
"spent": false,
"tx_hash": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"tx_size": 5870
},{
"amount": 50000000000,
"global_index": 213659,
"spent": false,
"tx_hash": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"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": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"tx_size": 5870
},{
"amount": 300000000000,
"global_index": 794232,
"spent": false,
"tx_hash": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"tx_size": 5870
},{
"amount": 50000000000,
"global_index": 213659,
"spent": false,
"tx_hash": "< c391089f5b1b02067acc15294e3629a463412af1f1ed0f354113dd4467e4f6c1> ",
"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": {
}
}
2016-03-12 07:17:09 +02:00
### query_key
Return the spend or view private key.
Inputs:
2016-03-12 19:54:04 +02:00
* *key_type* - string; Which key to retrieve: "mnemonic" - the mnemonic seed (older wallets do not have one) OR "view_key" - the view key
2016-03-12 07:17:09 +02:00
Outputs:
2016-03-12 19:54:04 +02:00
* *key* - string; The view key will be hex encoded, while the mnemonic will be a string of words.
2016-03-12 07:17:09 +02:00
2016-03-12 19:54:04 +02:00
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 ..."
}
}
2016-03-12 07:17:09 +02:00
### make_integrated_address
Make an integrated address from the wallet address and a payment id.
Inputs:
* *payment_id* - string; hex encoded; can be empty, in which case a random payment id is generated
Outputs:
* *integrated_address* - string
2016-03-12 19:54:04 +02:00
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"
}
}
2016-03-12 07:17:09 +02:00
### split_integrated_address
Retrieve the standard address and payment id corresponding to an integrated address.
Inputs:
* *integrated_address* - string
Outputs:
* *standard_address* - string
* *payment* - string; hex encoded
Example:
2016-03-12 19:54:04 +02:00
{:.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": "< 420fa29b2d9a49f5> ",
"standard_address": "427ZuEhNJQRXoyJAeEoBaNW56ScQaLXyyQWgxeRL9KgAUhVzkvfiELZV7fCPBuuB2CGuJiWFQjhnhhwiH1FsHYGQGaDsaBA"
}
}
2016-03-12 07:17:09 +02:00
### stop_wallet
Stops the wallet, storing the current state.
Inputs: *None* .
2016-03-12 19:54:04 +02:00
Outputs: *None* .
2016-03-12 07:17:09 +02:00
Example:
2016-03-12 19:54:04 +02:00
{:.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": {
}
}
2015-12-05 16:55:57 +02:00