Author: Joakim Stai <joakimstai@gmail.com>
Status: Draft
Created: 2018-03-09
License: CC-BY-SA-4.0
This is a proposal for IOTA, based on BIP21 for Bitcoin.
This document proposes a URI scheme for initiating IOTA transfers.
The purpose of this URI scheme is to enable users to easily make transfers by simply clicking links or scanning tags.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
The syntax of an iota URI is described using the ABNF of STD68 and non-terminal definitions from STD66 (unreserved, pct-encoded).
The path component consists of an IOTA address, and the query component provides additional parameters relating to the transfer.
(See also a simpler representation of the syntax.)
iota-uri = "iota:" address [ params ]
address = 90tryte ; IOTA address with checksum
params = "?" param *( "&" param )
param = [ amount-param / tag-param / message-param / other-param ]
amount-param = "amount=" *digit
tag-param = "tag=" pvalue
message-param = "message=" pvalue
other-param = pname [ "=" pvalue ]
tryte = *( %x41-5A / "9" ) ; A-Z9
pname = 1*qchar ; 1 or more qchars
pvalue = *qchar ; 0 or more qchars
qchar = unreserved / pct-encoded / not-reserved
not-reserved = "!" / "$" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "@"
A tryte is the ternary equivalent of a byte, represented as uppercase latin letters (A-Z) and the number 9. The 90 trytes address consists of an IOTA address (81 trytes) and its checksum (9 trytes).
Some characters that can appear in qchar MUST be percent-encoded. These are the characters that cannot appear in a URI according to STD66, as well as % (because it is used for percent-encoding). Of the characters in registered, the following are reserved and MUST be percent-encoded when not serving as delimiters: :, ?, =, and &.
Non-ASCII characters MUST first be encoded according to UTF-8 STD63, and then each octet of the corresponding UTF-8 sequence MUST be percent-encoded to be represented as URI characters.
amount– The amount of iotas to transfertag– A short tag to be published with the transfermessage– A message to be published with the transfer
If amount is provided, it MUST be specified using IOTA units (i) in integer numbers.
Other parameters MAY be added for future extensions. These MUST be optional, support is not to be expected in IOTA clients.
IOTA clients SHOULD register themselves as the handler for the iota URI scheme by default if no other handler is already registered. If there is already a registered handler, the client MAY prompt the user to change it once when they first run the client.
IOTA clients MUST NOT act on URIs without getting the user's authorization.
IOTA clients SHOULD require the user to manually approve each transfer individually, though in some cases they MAY allow the user to automatically make this decision.
IOTA clients MAY display the amount in any format that is not intended to deceive the user.
IOTA clients SHOULD choose a format that is foremost least confusing, and only after that the format that is most reasonable given the amount specified.
Any parameters for future extensions that are not supported by the IOTA client, can be safely ignored by the client.
As this proposal is written, no known IOTA clients actively implement an iota URI scheme.
This section is non-normative and does not cover all possible syntax. Please see the ABNF grammar above for the normative syntax.
[foo] means optional, <bar> are placeholders
iota:<address>[?amount=<amount>][?tag=<tag>][?message=<message>]
Just the address:
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW
Address with a tag:
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?tag=foo
Request for 100 i (IOTAs):
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?amount=100
Request for 10 Mi (Mega IOTAs):
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?amount=10000000
Request for 1 Gi (Giga IOTAs) with a message:
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?amount=1000000000&message=Payment%20for%20XYZ
Some future version that has parameters which are currently not understood and will therefore be ignored:
iota:MZLFXAZOHOSGRPIGFSQATWQXTFRWATQTOZXAZIGCRXAGIED9ZCPXMCMSSUHYVEGVTOILQMAD9VZIV9PJCHCCO9YMIW?somethingyoudontunderstand=50&somethingelseyoudontget=999