Getting Started

WalletPair is a wire protocol. There is no WalletPair SDK package to install: implement the encryption, relay, and EVM specifications in the dApp or wallet you control.

1. Run or choose a relay

Use a WebSocket endpoint at /v1. The connection query has exactly five required fields; values are RFC 3986 percent-encoded.

text 
wss://relay.example/v1?ch=<64-lowercase-hex>&name=<rfc3986>&url=<rfc3986>&icon=<rfc3986>&pubkey=<base64url-x25519>

2. Create the dApp pairing

Generate a fresh 32-byte channel ID and X25519 key pair. The dApp metadata must be a name, an absolute HTTP(S) URL, and an absolute HTTPS icon URL. Put those same values in the QR URI and in the dApp's relay connection.

text 
walletpair:?ch=<channel-id>&pubkey=<dapp-pubkey>&relay=<percent-encoded-wss-url>&name=<percent-encoded-name>&url=<percent-encoded-url>&icon=<percent-encoded-icon>

3. Compare the pairing code

Both sides calculate the four-digit code from the dApp channel ID, metadata, and public key. The wallet must compare it with the code shown by the dApp before joining. A mismatch requires a fresh channel and fresh keys.

4. Encrypt EVM messages

Derive directional traffic keys with X25519 and HKDF-SHA256. Encode the EIP-1193 envelope as the JSON-only MessagePack profile, then seal it with ChaCha20-Poly1305. The public chain suffix is authenticated additional data, not plaintext routing input.

text 
// Plaintext before MessagePack encoding and encryption
{
  "id": "req-1",
  "method": "eth_requestAccounts",
  "params": []
}

// Encrypted relay text frame
base64url(seq_bytes || ciphertext_tag) + "@eip155:1"

Next steps