HTTP Wallet Communications Substrate

• Brayden Langley ([email protected])

• Ty Everett ([email protected])

Abstract

The Bitcoin Wallet HTTP Interface is a standard interface that enables applications to connect with Bitcoin wallets to facilitate certain functionality. The interface provides a unified way for applications to request the creation of a Bitcoin transaction, encryption, digital signature creation, and other features provided by the wallet. By standardizing the interface, applications can support multiple wallets and give the user greater control over their Bitcoin-related activities.

Motivation

The motivation for this standard interface is to provide a common way for applications to connect with Bitcoin wallets. Currently, many Bitcoin wallets provide their own APIs, which makes it difficult for applications to support multiple wallets. The Bitcoin Wallet HTTP Interface standardizes the way that applications can interact with wallets, enabling them to be more easily integrated into various applications. This interface is designed to be flexible enough to support a range of wallets and use cases, while also providing a secure and standardized method of communication.

Status Note

This document originally described the pre-BRC-100 localhost HTTP API. The /v1/... routes, mixed GET/POST method table, and legacy method names such as createCertificate and findCertificates are historical. Current interoperable implementations in bsv-blockchain/ts-sdk expose the BRC-100 wallet interface over HTTP substrates without a versioned URL prefix.

Implementers SHOULD use the current substrates below for new work. The older route table is deprecated except where a deployment explicitly maintains backwards compatibility with legacy wallets.

Specification

Current wallet HTTP interoperability is defined by two localhost substrates for the BRC-100 wallet interface:

1. Binary wallet wire

   • Default base URL: http://localhost:3301

   • Route: POST /<BRC-100 methodName>

   • Request body: application/octet-stream

   • Body framing: the BRC-100 wallet-wire parameter payload for the selected method, excluding the method call code and originator frame that are used by the client-side substrate to choose the route and Origin header.

   • Originator: conveyed through the HTTP Origin header when available.

2. JSON wallet API

   • Default base URL: http://localhost:3321

   • Secure development base URL: https://localhost:2121

   • Route: POST /<BRC-100 methodName>

   • Request body: JSON arguments for the BRC-100 method

   • Response body: JSON result

   • Originator: Node clients may set Origin and Originator; browser clients rely on the browser-managed Origin header.

No /v1 prefix is used by the current ts-sdk HTTP wallet substrates.

Standard HTTP Routes

Every current BRC-100 wallet method is addressed by its method name:

Route	Request Method	Substrate
/createAction	POST	Binary wire or JSON
/signAction	POST	Binary wire or JSON
/abortAction	POST	Binary wire or JSON
/listActions	POST	Binary wire or JSON
/internalizeAction	POST	Binary wire or JSON
/listOutputs	POST	Binary wire or JSON
/relinquishOutput	POST	Binary wire or JSON
/getPublicKey	POST	Binary wire or JSON
/revealCounterpartyKeyLinkage	POST	Binary wire or JSON
/revealSpecificKeyLinkage	POST	Binary wire or JSON
/encrypt	POST	Binary wire or JSON
/decrypt	POST	Binary wire or JSON
/createHmac	POST	Binary wire or JSON
/verifyHmac	POST	Binary wire or JSON
/createSignature	POST	Binary wire or JSON
/verifySignature	POST	Binary wire or JSON
/acquireCertificate	POST	Binary wire or JSON
/listCertificates	POST	Binary wire or JSON
/proveCertificate	POST	Binary wire or JSON
/relinquishCertificate	POST	Binary wire or JSON
/discoverByIdentityKey	POST	Binary wire or JSON
/discoverByAttributes	POST	Binary wire or JSON
/isAuthenticated	POST	Binary wire or JSON
/waitForAuthentication	POST	Binary wire or JSON
/getHeight	POST	Binary wire or JSON
/getHeaderForHeight	POST	Binary wire or JSON
/getNetwork	POST	Binary wire or JSON
/getVersion	POST	Binary wire or JSON

The method names, argument structures, result structures, and binary call codes are specified normatively in BRC-100.

JSON Code Example

const httpResult = await makeHttpRequest(
  'http://localhost:3321/createAction',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      description: 'Create a wallet action',
      outputs: []
    })
  }
)

Binary-Wire Code Example

const httpResult = await makeHttpRequest(
  'http://localhost:3301/createAction',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/octet-stream'
    },
    body: walletWireParameterBytes
  }
)

Implementation

Applications and wallets should implement the current BRC-100 method set and one or more of the current HTTP substrates above. The current reference implementation is the bsv-blockchain/ts-sdk wallet substrate implementation.