MessageBox Server HTTP API

The MessageBox Server provides a store-and-forward REST API for peer-to-peer messaging. Clients send messages to named inboxes, recipients retrieve messages later, and messages are deleted once acknowledged. All requests use BRC-31 mutual authentication so the server knows sender and recipient identity without passwords.

At a glance

What problem this solves

Asynchronous peer-to-peer messaging without accounts or servers. Traditional messaging requires accounts, servers, and complex infrastructure. MessageBox enables store-and-forward: sender encrypts and posts to recipient's inbox, recipient polls or listens via WebSocket, and messages are automatically deleted after reading. Identity is cryptographic (no username/password).

Encrypted message storage. Messages are encrypted with AES-256-GCM before storage. Only the recipient (holder of the private key) can decrypt. The server cannot read message contents.

Peer discovery via overlay network. Clients can discover peers' MessageBox hosts by querying the overlay network (UHRP protocol), enabling dynamic host discovery without DNS or a central directory.

Protocol overview

Three-step flow (send → store → retrieve):

1. Sender → MessageBox POST /messages

   • Recipient public key in body
   • Message body (encrypted with AES-256-GCM)
   • x-bsv-auth-* headers (BRC-31 mutual auth)
   • Server stores message in recipient's inbox

2. Recipient → MessageBox GET /messages/{messageBox}

   • Retrieves all pending messages in their inbox
   • x-bsv-auth-* headers
   • Server returns array of messages

3. Recipient → MessageBox POST /acknowledge

   • Acknowledges (deletes) messages by ID
   • x-bsv-auth-* headers
   • Server deletes messages

Live subscription (alternative to polling):

• Recipient → MessageBox WebSocket upgrade + BRC-103 handshake
• Server pushes new messages in real-time via WebSocket
• Recipient can joinRoom(messageBox) / listenForMessages()

Key types / endpoints

Example: Send encrypted message

import { MessageBoxClient } from '@bsv/message-box-client'
import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient('auto', 'example.com')

const msgBox = new MessageBoxClient({
  walletClient: wallet,
  host: 'https://message-box-us-1.bsvb.tech'
})

// 1. Send message (auto-encrypted with AES-256-GCM)
await msgBox.sendMessage({
  recipient: '025706528f0f6894b2ba505007267ccff1133e004452a1f6b72ac716f246216366',
  messageBox: 'general_inbox',
  body: 'Hello! This is encrypted and only you can read it.'
})

Example: Retrieve and acknowledge messages

// 2. Retrieve all messages in inbox
const messages = await msgBox.listMessages({ 
  messageBox: 'general_inbox' 
})

for (const msg of messages) {
  console.log(`From ${msg.sender}: ${msg.body}`)
}

// 3. Acknowledge (delete) messages
await msgBox.acknowledgeMessage({
  messageIds: messages.map(m => m.messageId)
})

Example: Listen for live messages

// 4. Subscribe to real-time messages
await msgBox.listenForLiveMessages({
  messageBox: 'general_inbox',
  onMessage: (msg) => {
    console.log('Live message:', msg.body)
  }
})

Conformance vectors

There is no standalone MessageBox vector directory in the current conformance corpus. Related portable coverage lives in conformance/vectors/messaging/brc31/authrite-signature.json; MessageBox client/server behavior is covered by package tests and the OpenAPI artifact linked below.

Implementations in ts-stack

Related specs

• BRC-31 Auth — Mutual authentication for all endpoints
• AuthSocket — WebSocket implementation of BRC-31
• BRC-29 Peer Payment — Payment delivery via message box
• UHRP — Host discovery overlay protocol

Spec artifact

message-box-http.yaml