Bitcoin URIs

Represents a bitcoin payment URI. Bitcoin URI strings became the most popular way to share payment request, sometimes as a bitcoin link and others using a QR code.

URI Examples:

bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu
bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2
bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2&message=Payment&label=Satoshi&extra=other-param

URI Validation

The main use that we expect you'll have for the URI class in bitcore is validating and parsing bitcoin URIs. A URI instance exposes the address as a bitcore Address object and the amount in Satoshis, if present.

The code for validating URIs looks like this:

var uriString = 'bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2';
var valid = URI.isValid(uriString);
var uri = new URI(uriString);
console.log(uri.address.network, uri.amount); // 'livenet', 120000000

URI Parameters

All standard parameters can be found as members of the URI instance. However a bitcoin URI may contain other non-standard parameters, all those can be found under the extra namespace.

See the official BIP21 spec for more information.

Create URI

Another important use case for the URI class is creating a bitcoin URI for sharing a payment request. That can be accomplished by using a dictionary to create an instance of URI.

The code for creating an URI from an Object looks like this:

var uriString = new URI({
  address: '12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu',
  amount : 10000, // in satoshis
  message: 'My payment request'
});
var uriString = uri.toString();

URI

Kind: global class

new URI(data, [knownParams])

Bitcore URI

Instantiate an URI from a bitcoin URI String or an Object. An URI instance can be created with a bitcoin uri string or an object. All instances of URI are valid, the static method isValid allows checking before instantiation.

All standard parameters can be found as members of the class, the address is represented using an {Address} instance and the amount is represented in satoshis. Any other non-standard parameters can be found under the extra member.

Returns: URI - A new valid and frozen instance of URI
Throws:

  • TypeError Invalid bitcoin address
  • TypeError Invalid amount
  • Error Unknown required argument
Param Type Description
data string | Object A bitcoin URI string or an Object
[knownParams] Array.<string> Required non-standard params

Example


var uri = new URI('bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu?amount=1.2');
console.log(uri.address, uri.amount);

urI._fromObject(obj)

Internal function to load the URI instance with an object.

Kind: instance method of URI
Throws:

  • TypeError Invalid bitcoin address
  • TypeError Invalid amount
  • Error Unknown required argument
Param Type Description
obj Object Object with the information

urI._parseAmount(amount) ⇒ Object

Internal function to transform a BTC string amount into satoshis

Kind: instance method of URI
Returns: Object - Amount represented in satoshis
Throws:

  • TypeError Invalid amount
Param Type Description
amount string Amount BTC string

urI.toString() ⇒ string

Will return a the string representation of the URI

Kind: instance method of URI
Returns: string - Bitcoin URI string

urI.inspect() ⇒ string

Will return a string formatted for the console

Kind: instance method of URI
Returns: string - Bitcoin URI

URI.fromString(str) ⇒ URI

Instantiate a URI from a String

Kind: static method of URI
Returns: URI - A new instance of a URI

Param Type Description
str string JSON string or object of the URI

URI.fromObject(data) ⇒ URI

Instantiate a URI from an Object

Kind: static method of URI
Returns: URI - A new instance of a URI

Param Type Description
data Object object of the URI

URI.isValid(data, [knownParams]) ⇒ boolean

Check if an bitcoin URI string is valid

Kind: static method of URI
Returns: boolean - Result of uri validation

Param Type Description
data string | Object A bitcoin URI string or an Object
[knownParams] Array.<string> Required non-standard params

Example


var valid = URI.isValid('bitcoin:12A1MyfXbW6RhdRAZEqofac5jCQQjwEPBu');
// true

URI.parse(uri) ⇒ Object

Convert a bitcoin URI string into a simple object.

Kind: static method of URI
Returns: Object - An object with the parsed params
Throws:

  • TypeError Invalid bitcoin URI
Param Type Description
uri string A bitcoin URI string