meta/api/lightwallet_rest.md

Lightwallet API

This document describes a reference standard specification for the Monero lightwallet server/client API. It’s implemented by OpenMonero, MyMonero, and the official Monero project, and is maintained with the purpose of organizing and recording the consensus of Monero lightwallet API projects, and to support alternate implementations.

Modifications to this specification should only be made with consensus of the projects which participate by implementing the specification.

Encoding Schemes

JSON

JSON is the original and required encoding scheme used for the API. Binary values (public keys, hashes, etc) are sent as an ascii-hex string. Some integers, that may exceed 2^53, are sent as strings. This is to due to the limitation within Javascript where all integers are double floating point values.

Transport Layers

HTTP-REST

When calling an API method, the client must use HTTP POST to a path with the method name. As an example, to invoke the get_address_txs method, the client sends a POST message to /get_address_txs where the body contains the JSON request object associated with that method name. If the requested method does not exist, a HTTP 404 "Not Found" error must be returned. If the request type is not POST, the server shall return a HTTP 405 "Method Not Allowed" error. If the server is unable to complete a request temporarily due to load, then the server shall return a HTTP 503 "Service Unavailable" error to indicate to the client that the request may be serviceable later.

Servers must support the JSON encoding scheme. The client must send the HTTP field Content-Type: application/json; if the server is not provided that content type from the client then the server shall respond with a HTTP 415 "Unsupported Media Type" error.

This transport layer does not use HTTP authentication, and instead uses the view_key field for authorization. Documentation for a specific method will indicate whether view_key is required. When it is not necessary, anyone can invoke the method.

Schema

The ascii name of the field is used as a key in JSON encoding. If a field has a * indicator, that means the field is optional. If * is used next to the type, the value can be "null" or a value valid according to the type.

Types

binary

A hex-ascii string in JSON. This is generally some irreducible cryptographic concept - a public key or hash.

base58-address

A standard Monero public address encoded as a string in JSON.

output object

Information needed to spend an output.

Field	Type	Description
tx_id	uint64	Index of tx in blockchain
amount	uint64-string	XMR value of output
index	uint16	Index within vout vector
global_index	uint64-string	Index within amount
rct	binary	Bytes of ringct data
tx_hash	binary	Bytes of tx hash
tx_prefix_hash	binary	Bytes of tx prefix hash
public_key	binary	Bytes of output public key
tx_pub_key	binary	Bytes of the tx public key
spend_key_images	array of binary objects	Bytes of key images
timestamp	timestamp	Timestamp of containing block
height	uint64	Containing block height

tx_id is determined by the monero daemon. It is the offset that a transaction appears in the blockchain from the genesis block.

global_index is determined by the monero daemon. It is the offset from the first time the amount appeared in the blockchain. After ringct, this is the order of outputs as they appear in the blockchain.

tx_hash and tx_prefix_hash are determined by how monerod computes the hash.

rct is, for ringct outputs, a 96-byte blob containing the concatenation of the public commitment, then the ringct mask value, and finally the ringct amount value. For ringct coinbase outputs, the mask is always the identity mask and the amount is zero; for non-coinbase ringct outputs, the mask and amount are the respective raw encrypted values, which must be decrypted by the client using the view secret key. For non-ringct outputs, this field is nil.

rates object

Field	Type	Description
AUD *	float32	AUD/XMR exchange rate
BRL *	float32	BRL/XMR exchange rate
BTC *	float32	BTC/XMR exchange rate
CAD *	float32	CAD/XMR exchange rate
CHF *	float32	CHF/XMR exchange rate
CNY *	float32	CNY/XMR exchange rate
EUR *	float32	EUR/XMR exchange rate
GBP *	float32	GBP/XMR exchange rate
HKD *	float32	HKD/XMR exchange rate
INR *	float32	INR/XMR exchange rate
JPY *	float32	JPY/XMR exchange rate
KRW *	float32	KRW/XMR exhcnage rate
MXN *	float32	MXN/XMR exchange rate
NOK *	float32	NOK/XMR exchange rate
NZD *	float32	NZD/XMR exchange rate
SEK *	float32	SEK/XMR exchange rate
SGD *	float32	SGD/XMR exchange rate
TRY *	float32	TRY/XMR exchange rate
USD *	float32	USD/XMR exchange rate
RUB *	float32	RUB/XMR exchange rate
ZAR *	float32	ZAR/XMR exchange rate

If an exchange rate is unavailable, the server field shall omit the field from the JSON object.

spend object

Field	Type	Description
amount	uint64-string	XMR possibly being spent
key_image	binary	Bytes of the key image
tx_pub_key	binary	Bytes of the tx public key
out_index	uint16	Index of source output
mixin	uint32	Mixin of the spend

out_index is a zero-based offset from the original received output. The variable within the monero codebase is the vout array, this is the index within that. It is needed for correct computation of the key_image.

mixin does not include the real spend - this is the number of dummy inputs.

timestamp

A string in JSON. The string format is "YYYY-HH-MM-SS.0-00:00". Monero blockchain timestamps do not have sub-seconds.

transaction object

Field	Type	Description
id	uint64	Index of tx in blockchain
hash	binary	Bytes of tx hash
timestamp *	timestamp	Timestamp of block
total_received	uint64-string	Total XMR received
total_sent	uint64-string	XMR possibly being spent
unlock_time	uint64	Tx unlock time field
height *	uint64	Block height
spent_outputs	array of spend objects	List of possible spends
payment_id *	binary	Bytes of tx payment id
coinbase	boolean	True if tx is coinbase
mempool	boolean	True if tx is in mempool
mixin	uint32	Mixin of the receive

id is determined by the monero daemon. It is the offset that a transaction appears in the blockchain from the genesis block.

timestamp and height are not sent when mempool is true.

hash is determined by how the monero core computes the hash.

spent_outputs is the list of possible spends in this transaction only.

payment_id is omitted if the transaction had none. It is decrypted when the encrypted form is used. The decryption may be incorrect - if the transaction was TO another address, then this will be random bytes. This happens frequently with outgoing payment ids; the received XMR in the transaction is change and the payment id is for the real recipient.

mixin does not include the real spend - this is the number of dummy inputs.

uint16 / uint32 / uint64

Sent as a standard decimal encoded number in JSON. The JSON decoder must reject number values that exceed the specified bit-width.

uint64-string

A uint64 encoded as a decimal string value in JSON. Used when a value may exceed 2^53 - all numbers are 64-bit floats in JavaScript.

random_output object

Field	Type	Description
global_index	uint64-string	Index within amount
public_key	bytes	Bytes of output public key
rct	bytes	Bytes containing ringct commitment

global_index is determined by the monero daemon. It is the offset from the first time the amount appeared in the blockchain. After ringct, this is the order of outputs as they appear in the blockchain.

random_outputs object

Randomly selected outputs for use in a ring signature.

Field	Type	Description
amount	uint64-string	XMR amount, 0 if ringct
outputs *	array of random_output objects	Selected outputs

outputs is omitted by the server if the amount does not have enough mixable outputs.

Methods

get_address_info

Returns the minimal set of information needed to calculate a wallet balance. The server cannot calculate when a spend occurs without the spend key, so a list of candidate spends is returned.

Request object

Field	Type	Description
address	base58-address	Address to retrieve
view_key	binary	View key bytes for authorization

If address is not authorized, the server must return a HTTP 403 "Forbidden" error.

Response object

Field	Type	Description
locked_funds	uint64-string	Sum of unspendable XMR
total_received	uint64-string	Sum of received XMR
total_sent	uint64-string	Sum of possibly spent XMR
scanned_height	uint64	Current tx scan progress
scanned_block_height	uint64	Current scan progress
start_height	uint64	Start height of response
transaction_height	uint64	Total txes sent in Monero
blockchain_height	uint64	Current blockchain height
spent_outputs	array of spend objects	Possible spend info
rates *	rates	Current exchange rates

rates is omitted if unavailable.

get_address_txs

Returns information needed to show transaction history. The server cannot calculate when a spend occurs without the spend key, so a list of candidate spends is returned.

Request object

Field	Type	Description
address	base58-address	Address to retrieve
view_key	binary	View key bytes for authorization

If address is not authorized, the server must return a HTTP 403 "Forbidden" error.

Response object

Field	Type	Description
total_received	uint64-string	Sum of received outputs
scanned_height	uint64	Current tx scan progress
scanned_block_height	uint64	Current scan progress
start_height	uint64	Start height of response
blockchain_height	uint64	Current blockchain height
transactions	array of transaction objects	Possible spend info

get_random_outs

Selects random outputs to use in a ring signature of a new transaction. If the amount is 0 then the monerod RPC get_output_distribution should be used to locally select outputs using a gamma distribution as described in "An Empirical Analysis of Traceability in the Monero Blockchain". If the amount is not 0, then the monerod RPC get_output_histogram should be used to locally select outputs using a triangular distribution (uint64_t dummy_out = histogram.total * sqrt(float64(random_uint53) / float64(2^53))).

Request object

Field	Type	Description
count	uint32	Mixin (name is historical)
amounts	array of uint64-string objects	XMR amounts that need mixing

Clients must use amount 0 when computing a ringct output.

If clients are creating multiple rings with the same amount, they must set count to the mixin level and add the value to amounts multiple times. Server must respond to each value in amounts, even if the value appears multiple times.

Response object

Field	Type	Description
amount_outs	array of random_output objects	Dummy outputs for each amounts

If there are not enough outputs to mix for a specific amount, the server shall omit the outputs field in amount_outs.

get_unspent_outs

Returns a list of received outputs. The client must determine when the output was actually spent.

Request object

Field	Type	Description
address	base58-address	Address to create/probe
view_key	binary	View key bytes
amount	uint64-string	XMR send amount
mixin	uint32	Minimum mixin for source output
use_dust	boolean	Return all available outputs
dust_threshold *	uint64-string	Ignore outputs below this amount

If the total received outputs for the address is less than amount, the server shall return a HTTP 400 "Bad Request" error code.

Response object

Field	Type	Description
per_byte_fee	uint64-string	Estimated network fee
fee_mask	uint64-string	Fee quantization mask
amount	uint64-string	The total value in outputs
outputs	array of output objects	Outputs possibly available for spending

import_request

Request an account scan from the genesis block.

Request object

Field	Type	Description
address	base58-address	Address to create/probe
view_key	binary	View key bytes

Response object

Field	Type	Description
payment_address *	base58-address	Payment location
payment_id *	binary	Bytes for payment_id tx field
import_fee *	uint64-string	Fee required to complete request
new_request	boolean	New or existing request
request_fulfilled	boolean	Indicates success
status	string	Custom message

payment_id, import_fee, and payment_address may be omitted if the client does not need to send XMR to complete the request.

login

Check for the existence of an account or create a new one.

Request object

Field	Type	Description
address	base58-address	Address to create/probe
view_key	binary	View key bytes
create_account	boolean	Try to create new account
generated_locally	boolean	Indicate that the address is new

The view key bytes are required even if an account is not being created, to prevent metadata leakage.

If the server does not allow account creations, HTTP 501 "Not Implemented" error must be returned.

If approval process is manual, a successful HTTP 200 OK and response object must be returned. Subsequent requests shall be HTTP 403 "Forbidden" until account is approved.

Response object

Field	Type	Description
new_address	boolean	Whether account was just created
generated_locally *	boolean	Flag from initial account creation
start_height *	uint64	Account scanning start block

submit_raw_tx

Submit raw transaction to be relayed to monero network.

Request object

Field	Type	Description
tx	binary	Raw transaction bytes, in format used by daemon p2p comms

This format is tricky unfortunately, it is custom to the monero daemon. The internal code of monerod must be read to determine this format currently.

Response object

Field	Type	Description
status	string	Status of relay

status is typically the response by the monero daemon attempting to relay the transaction.