Defines a JSON-based protocol for requesting bitcoin addresses and more
- 👌 Simple
- 🗓️ Versioned
- 🍡 Supports script types
- 🖋️ Supports message signatures
- 👩🚀 Supports extended public keys
- 💸 Supports SLIP-0024 payment requests
A service or wallet requests a bitcoin address request requestAddress:
{
"version": "0",
"type": "requestAddress",
"withMessageSignature": "SX0KOveC",
"withExtendedPublicKey": true,
"withScriptType": "p2wpkh",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}The other service or wallet replies with the requested address:
{
"version": "0",
"type": "address",
"bitcoinAddress": "bc1qfd8phxz2vcazlfjtxqef94xjwulf5xyjghrxge",
"signature": "Hzqs3cyg1YYF7M/m+U3BbDFykpZELv4xQhk4uWGCGAoOOq3kYKcR3uUzhXludmyEjQct7rAx3NxrWDBUmWcs/B8=",
"extendedPublicKey": "zpub6rjWsJX5PFBXVAivrvSX7QUwtHKPuudSYokPBiA35H6g6ue4YaLPNQYhSkiL1G8zGAhQNuiMi15k4xMKBy4jHPj99uWDnKihRuvGDycEGiD",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}A user can be prompted to verify received address with verifyAddress:
{
"version": "0",
"type": "verifyAddress",
"bitcoinAddress": "bc1qfd8phxz2vcazlfjtxqef94xjwulf5xyjghrxge",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}A service or wallet can also request an extended public key requestExtendedPublicKey:
{
"version": "0",
"type": "requestExtendedPublicKey",
"withScriptType": "p2wpkh",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}The other service or wallet replies with the requested extendedPublicKey:
{
"version": "0",
"type": "extendedPublicKey",
"extendedPublicKey": "zpub6rjWsJX5PFBXVAivrvSX7QUwtHKPuudSYokPBiA35H6g6ue4YaLPNQYhSkiL1G8zGAhQNuiMi15k4xMKBy4jHPj99uWDnKihRuvGDycEGiD",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}A service or wallet sends a paymentRequest:
{
"version": "0",
"type": "paymentRequest",
"bitcoinAddress": "bc1qfd8phxz2vcazlfjtxqef94xjwulf5xyjghrxge",
"amount": 0.01,
"label": "Dragon's Tale",
"message": "Elderberries",
"slip24": {
"recipientName": "Dragon's Tale",
"nonce": null,
"memos": [{
"type": "text",
"text": "Elderberries"
}],
"outputs": [{
"address": "bc1qfd8phxz2vcazlfjtxqef94xjwulf5xyjghrxge",
"amount": 1000000
}],
"signature": "MEQCIH+0V4j4DTzT4y9EE9XHjQlyRfwHnnVQL9NFFYVCta1PAiAW0mlS4YtDzNzwJ0gR8ApKzdIKmSBKzClnxyFFp84oig=="
},
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}The other service or wallet replies with the payment that was requested:
{
"version": "0",
"type": "payment",
"txid": "4bec63963c6c573f4fb1f524e50c286c9e4243c8d30ec33687a0e9dbdff1f43e",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}If a request can not be fulfilled, the other service should reply with a cancel message and an optional reason:
{
"version": "0",
"type": "cancel",
"reason": "rejected_by_user",
"correlationId": "23735ca1-542d-469f-85a3-902bc1afc100"
}The correlationId introduced in v0.0.11 is a unique identifier for a request. It is used to match the request with the response.
To ensure backward compatibility, the requester should always listen for all messages that do not have a correlationId field.
Serialize a message to string for transmission
Parse a string into a message
type Message =
| RequestAddressV0Message
| RequestExtendedPublicKeyV0Message
| VerifyAddressV0Message
| AddressV0Message
| ExtendedPublicKeyV0Message
| PaymentRequestV0Message
| PaymentV0Message
| CloseV0Message
| CancelV0Message;type RequestAddressV0Message = {
version: MessageVersion.V0;
type: V0MessageType.RequestAddress;
correlationId?: string;
withMessageSignature?: string | false | null;
withExtendedPublicKey?: boolean | null;
withScriptType?: V0MessageScriptType | null;
};type RequestExtendedPublicKeyV0Message = {
version: MessageVersion.V0;
type: V0MessageType.RequestExtendedPublicKey;
correlationId?: string;
withScriptType?: V0MessageScriptType | null;
};type VerifyAddressV0Message = {
version: MessageVersion.V0;
type: V0MessageType.VerifyAddress;
correlationId?: string;
bitcoinAddress: string;
};type AddressV0Message = {
version: MessageVersion.V0;
type: V0MessageType.Address;
correlationId?: string;
bitcoinAddress: string;
signature?: string | null;
extendedPublicKey?: string | null;
};type ExtendedPublicKeyV0Message = {
version: MessageVersion.V0;
type: V0MessageType.ExtendedPublicKey;
correlationId?: string;
extendedPublicKey: string;
};type PaymentRequestV0Message = {
version: MessageVersion.V0;
type: V0MessageType.PaymentRequest;
correlationId?: string;
bitcoinAddress: string;
amount: number;
label: string | null;
message: string | null;
slip24: Slip24 | null;
};type PaymentV0Message = {
version: MessageVersion.V0;
type: V0MessageType.Payment;
correlationId?: string;
txid: string;
};type CloseV0Message = {
version: MessageVersion.V0;
type: V0MessageType.Close;
correlationId?: string;
};type CancelV0Message = {
version: MessageVersion.V0;
type: V0MessageType.Cancel;
correlationId?: string;
reason?: string | null;
};enum V0MessageScriptType {
P2PKH = 'p2pkh',
P2WPKH = 'p2wpkh',
P2SH = 'p2sh',
P2TR = 'p2tr',
}enum V0MessageType {
RequestAddress = "requestAddress",
RequestExtendedPublicKey = "requestExtendedPublicKey",
VerifyAddress = "verifyAddress",
Address = "address",
ExtendedPublicKey = "extendedPublicKey",
PaymentRequest = "paymentRequest",
Payment = "payment",
Close = "close",
Cancel = "cancel",
}enum MessageVersion {
V0 = '0',
}type Slip24 = {
recipientName: string,
nonce: string | null,
memos: Array<{
type: 'text',
text: string,
} | {
type: 'refund',
refund: string,
} | {
type: 'coinPurchase',
coinPurchase: {
coinType: number,
amount: string,
address: string,
},
}>,
outputs: Array<{
amount: number,
address: string,
}>,
signature: string,
};MIT