Introduction

List of RPC calls

• getbalance

  Retrieves current wallet balance: total and unlocked.

  Inputs:
  None.

  Outputs:
  balance — unsigned integer; total amount of funds the wallet has (unlocked and locked coins).
  unlocked_balance — unsigned integer; unlocked funds, i.e. coins that are stored deep enough in the blockchain to be considered relatively safe to spend. Only this amount of coins are immediately spendable.
  unlocked_balance is always less or equal to balance.

  Examples

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"getbalance"}'

  {
   "id": "3",
   "jsonrpc": "2.0",
   "result": {
     "balance": 4631800000,
     "unlocked_balance": 4431900000
   }
  }

• getaddress

  Obtains wallet public address.

  Inputs:
  None.

  Outputs:
  address — string; standard public address of the wallet

  Examples

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"getaddress"}'

  {
   "id": "3",
   "jsonrpc": "2.0",
   "result": {
     "address": "HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7"
   }
  }

• transfer

  Creates a transaction and broadcasts it to the network.

  Inputs:
  destinations — list of transfer_destination objects (see below); list of recipients with corresponding amount of coins for each.
  fee — unsigned int; transaction fee in atomic units. Minimum 10⁵ atomic units, recommended 10⁶ or 10⁷.
  mixin — unsigned int; number of foreign outputs to be mixed in with each input. Increases untraceability. Use 0 for direct and traceable transfers.
  payment_id — string; hex-encoded payment id. Can be empty if payment id is not required for this transfer.

  transfer_destinationobject fields:
  address — string; standard or integrated address of a recipient.
  amount — unsigned int; amount of coins to be sent;

  Outputs:
  tx_hash — string; hash identifier of the transaction that was successfully sent.

  Examples

  Not enough money

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[{"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":10000000000000}]}}'

  {
   "error": {
     "code": -4,
     "message": "NOT_ENOUGH_MONEY"
   },
   "id": "5",
   "jsonrpc": "2.0"
  }

  Fee is too small

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[{"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":100000000}], "fee":10}}'

  {
   "error": {
     "code": -4,
     "message": "transaction was rejected by daemon"
   },
   "id": "5",
   "jsonrpc": "2.0"
  }

  Correct request

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[ {"address":"h9MPDxJCbEvHNSXkykzXzy7imqgsunmgn3KoHa1qn3PjEtcySfCTB6ea8YTCrXxZzS9aGBUSGTw1W5XFJGwJXjwUb7wdQ4c9dXM3Bz4ow4dD", "amount":100000000}, {"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":200000000}], "fee":1000000, "mixin":0}}'

  {
   "id": "5",
   "jsonrpc": "2.0",
   "result": {
     "tx_hash": "<138ba717c200167634a444b25a9f30251cbfd049052cfbcc63f31367d644d1f0>"
   }
  }

• store

  Saves wallet update progress into a wallet file. Although progress is always saved upon graceful wallet application termination, with this call a user can manually trigger saving process. Otherwise, in a case of abnormal wallet application termination the progress won’t be saved and it will take some time to synchronize on the next launch.

  Inputs:
  None.

  Outputs:
  None.

  Examples

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"store"}'

  {
   "id": "3",
   "jsonrpc": "2.0",
   "result": {
   }
  }

• get_payments

  Gets list of incoming transfers by a given payment id.

  Inputs:
  payment_id — string; hex-encoded payment id.

  Outputs:
  result — list of payments object.

  payments object fields:

  • amount — unsigned int; amount of coins in atomic units.
  • block_height — unsigned int; height of the block containing corresponding transaction.
  • block_height — unsigned int; height of the block containing corresponding transaction.
  • tx_hash — string; transaction hash.
  • unlock_time — unsigned int; if non-zero — unix timestamp after which this transfer coins can be spent. If it is less than 500000000, the value is treated as a minimum block height at which this transfer coin can be spent.

  Examples

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"get_payments", "params":{"payment_id":"6162636465"}'

  {
    "id": "5",
    "jsonrpc": "2.0",
    "result": {
    "payments": [{
      "amount": 100000000000000,
      "block_height": 131944,
      "payment_id": "aaaa",
      "tx_hash": "176416cb542884e10f826627f87df6cf45a16039f913deb2e41f5f2d0647a96d",
      "unlock_time": 0
    }]
    }
  }

• sweep_below

  Attempts to merge all outputs with amount less than specified and transfer it to a given address. RPC will try to collect as many outputs as possible thus a user may be required to run this RPC more than once in order to transfer all funds which meet amount criteria. On success generates one transaction.

  Inputs:
  address — string; funds transfer destination. Integrated addresses are allowed if payment_id_hex is empty or unspecified.
  amount — unsigned integer; upper boundary for output amount. Outputs with less amount than specified value are considered as candidates to be included into the transaction.
  fee — unsigned integer; transaction fee.
  payment_id_hex — string (optional); payment identifier of the transaction.
  mixin — unsigned integer (optional); number of fake outputs to be mixed in with real ones for better untraceability. Default is zero.
  unlock_time — unsigned integer (optional); timestamp or block height in the future when generated transaction becomes spendable. Default if zero (no lock time).
  

  Outputs:
  amount_swept — unsigned integer; sum of output amounts that were actually swept, i.e. transferred to the given address.
  amount_total — unsigned integer; total sum of all output amounts satisfying amount criteria that were present in the wallet prior to this operation.
  outs_swept — unsigned integer; number of outputs that were actually swept, i.e. transferred to the given address.
  outs_total — unsigned integer; total number of all outputs satisfying amount criteria that were present in the wallet prior to this operation. If outs_swept equals to outs_total it means that all such outputs were successfully swept. Otherwise a user may want to call this method again to take care of left outputs..
  tx_hash — string; hash identifier of generated transaction.

  Examples

  Using only required inputs

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"sweep_below", "params" : {"address" : "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm", "fee":10000000, "amount":10000000000000}}'

  {
    "id": "3",
    "jsonrpc": "2.0",
    "result": {
      "amount_swept": 233274242000000,
      "amount_total": 59050073447000000,
      "outs_swept": 266,
      "outs_total": 65288,
      "tx_hash": "81850227ea4c96ed88b47bca954213098f97db94118e2289e9ace7eac27e1db5"
    }
  }

  Using all inputs

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"sweep_below", "params" : {"address" : "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm", "fee":10000000, "amount":10000000000000, "mixin": 1, "payment_id_hex":"aabbcc", "unlock_time":110000}}'

  {
    "id": "3",
    "jsonrpc": "2.0",
    "result": {
      "amount_swept": 137561033000000,
      "amount_total": 58820073437000000,
      "outs_swept": 133,
      "outs_total": 65029,
      "tx_hash": "1c3cc18ad5aa3434d85e265507dd0edceca52a7349e31c97dae79b5221b38142"
    }
  }

  Error (blockchain doesn’t contain enough outputs for mixing in)

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"sweep_below", "params" : {"address" : "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm", "fee":10000000, "amount":10000000000000, "mixin": 10}}'

  {
    "error": {
      "code": -4,
      "message": "not enough outputs to mix"
    },
    "id": "3",
    "jsonrpc": "2.0"
  }

  Error (there are no such outputs in the wallet)

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"sweep_below", "params" : {"address" : "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm", "fee":10000000, "amount":1000}}'

  {
    "error": {
      "code": -4,
      "message": "No spendable outputs meet the criterion"
    },
    "id": "3",
    "jsonrpc": "2.0"
  }

• get_bulk_payments

  Gets list of incoming transfers by given payment IDs.

  Inputs:
  payment_ids — array of strings; hex-encoded payment IDs.
  min_block_height — integer; minimum block height.

  Outputs:
  payments — list of payment_details object.
  min_block_height — integer; minimum block height.
  
  Fields of payment_details object:
  payment_id — string; hex-encoded payment ID.
  tx_hash — string; transaction hash identifier.
  amount — integer; transfer amount.
  block_height — integer; height of a block containing corresponding transaction.
  unlock_time — integer; transaction unlock time.

  Example

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"get_bulk_payments", "params":{"payment_ids":["aaaa", "bbbb"]}'

  {
    "id": "5",
    "jsonrpc": "2.0",
    "result": {
    "payments": [{
      "amount": 100000000000000,
      "block_height": 131944,
      "payment_id": "aaaa",
      "tx_hash": "176416cb542884e10f826627f87df6cf45a16039f913deb2e41f5f2d0647a96d",
      "unlock_time": 0
    }]
    }
  }

• get_transfers

  Retrieves filtered list of transfers.

  Inputs:
  in — boolean; if true then incoming transactions will be taken into account.
  out — boolean; if true then outgoing transactions will be taken into account.
  pending — boolean; not supported yet, will be ignored.
  failed — boolean; not supported yet, will be ignored.
  pool — boolean; if true then unconfirmed in/out txs will be taken into account.
  filter_by_height — boolean; if true then transfers will be filtered by block height.
  min_height — integer; minimum block height (including).
  max_height — integer; maximum block height (including).

  Outputs:
  in — list of wallet_transfer_info objects, corresponding to incoming transactions;
  out — list of wallet_transfer_info objects, corresponding to outgoing transactions.
  pool — list of wallet_transfer_info objects, corresponding to unconfirmed transactions.
  
  Fields of wallet_transfer_info object:
  amount — integer; transfer amount.
  timestamp — integer; transaction timestamp.
  tx_hash — string; transaction identifier.
  height — integer; corresponding block height (zero means unconfirmed).
  unlock_time — integer; transaction unlock time.
  tx_blob_size — integer; transaction size in bytes.
  payment_id — string; hex-encoded payment ID.
  destinations — string; destination address or addresses.
  destination_alias — string; destination alias that was used (if any).
  is_income — boolean; true if this transfer is an incoming transfer.
  fee — integer; transaction fee.
  td — object of wallet_transfer_info_details object (see below).
  
  wallet_transfer_info_details fields:
  rcv — list of integers; indices of received transfers.
  spn — list of integers; indices of spent transfers.

  Example

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"get_transfers", "params":{"out":True}'

  {
    "id": "5",
    "jsonrpc": "2.0",
    "result": {
    "out": [{
      "amount": 1000000000000,
      "destination_alias": "",
      "destinations": "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm",
      "fee": 0,
      "height": 90050,
      "is_income": false,
      "payment_id": "",
      "td": {
        "spn": [1000000000000]
      },
      "timestamp": 1538121147,
      "tx_blob_size": 264,
      "tx_hash": "52668b38d70e5456ff578d29749ac141beac7e4410935941d86d1761e4615901",
      "unlock_time": 0
    }]
    }
  }
  

• convert_address

  Converts standard address into an integrated address and vica versa.

  Inputs and outputs:
  address_str — string; standard address.
  payment_id_hex — string; hex-encoded payment id.
  integrated_address_str — string; integrated address.
  

  This RPC does conversion both ways:

  1) if address_str and payment_id_hex are both given they are combined into integrated_address_str.
  2) if integrated_address_str is given it's split into address_str and payment_id_hex.
  
  

  Examples
  Standard address and payment ID into an integrated address

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"convert_address", "params":{"address_str":"1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm", "payment_id_hex":"aabbcc"}}'

  {
    "id": "5",
    "jsonrpc": "2.0",
    "result": {
    "address_str": "",
    "integrated_address_str": "bbRAmEkwnXj4UdFUPFAPE64EBsvTz2MGwWbuWoxdjyJKaXnuR4rd2jNfhpiBgBX6aYXmEw7XtWQpEVSh35jrfUUfdVsutRe5o6TAm9",
    "payment_id_hex": ""
    }
  }
  

  Integrated address into a standard address and payment ID

  $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"convert_address", "params":{"integrated_address_str":"bbRAmEkwnXj4UdFUPFAPE64EBsvTz2MGwWbuWoxdjyJKaXnuR4rd2jNfhpiBgBX6aYXmEw7XtWQpEVSh35jrfUUfdVsutRe5o6TAm9"}}'

  {
    "id": "5",
    "jsonrpc": "2.0",
    "result": {
    "address_str": "1LHWBr8ZJL7QYSupDzdzkSRPiVp7n5brhDWHcWPjSifGcRKHYCQuG1S7XedbS1vQrn7GC3u2HbUL3SWcd5rbKY2FT32Vtkm",
    "integrated_address_str": "",
    "payment_id_hex": "aabbcc"
    }
  }