Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MercuryWorkshop/epoxy-tls/llms.txt

Use this file to discover all available pages before exploring further.

Epoxy TLS lets you make fully encrypted HTTP and WebSocket requests directly from browser JavaScript by running TLS inside WebAssembly and tunneling TCP connections through the Wisp protocol. This guide walks you through installing the package, initializing the WASM module, and issuing your first proxied fetch() call.
1
Install the package
2
Add @mercuryworkshop/epoxy-tls to your project using your preferred package manager.
3
npm
npm install @mercuryworkshop/epoxy-tls
yarn
yarn add @mercuryworkshop/epoxy-tls
pnpm
pnpm add @mercuryworkshop/epoxy-tls
4
Initialize the WASM module
5
Before using any Epoxy class, you must call init() and await its result. The way you call init() depends on which package export you import.
6
Bundled variant (default import — WASM is embedded as base64, no extra file needed):
7
import init, { EpoxyClient, EpoxyClientOptions } from "@mercuryworkshop/epoxy-tls";

// No arguments required — the WASM binary is already bundled
await init();
8
Non-bundled variant (WASM file must be served separately):
9
import init, { EpoxyClient, EpoxyClientOptions } from "@mercuryworkshop/epoxy-tls/epoxy";

// Pass the path or URL to the separately hosted .wasm file
await init({ module_or_path: "/path/to/epoxy.wasm" });
10
Use the bundled variant (@mercuryworkshop/epoxy-tls or @mercuryworkshop/epoxy-tls/epoxy-bundled) during development and for simpler deployments — it requires no extra static file serving setup.
11
Configure EpoxyClientOptions
12
Create an EpoxyClientOptions object and configure it before constructing the client. Enabling wisp_v2 is strongly recommended for best compatibility and performance.
13
const options = new EpoxyClientOptions();
options.user_agent = navigator.userAgent;
options.wisp_v2 = true;
14
Other available options include udp_extension_required, disable_certificate_validation, redirect_limit, header_limit, and buffer_size. See the API reference for the full list.
15
Create an EpoxyClient
16
Pass your Wisp server URL (using the ws:// or wss:// scheme) as the first argument to the EpoxyClient constructor, along with the options object you just configured.
17
// Use your own self-hosted Wisp server in production
const client = new EpoxyClient("wss://wisp.mercurywork.shop", options);
18
EpoxyClient also accepts an async function instead of a URL string if you need a custom transport. The function must return { read: ReadableStream<ArrayBuffer>, write: WritableStream<Uint8Array> }. See the API reference for details.
19
Make your first fetch() call
20
Call client.fetch() just like the native browser fetch API. It returns a standard Response object whose headers, text(), json(), and arrayBuffer() methods all work as expected. An additional rawHeaders property exposes the raw header map.
21
const res = await client.fetch("https://example.com");

// Standard Headers object
console.log(res.headers);

// Raw header map (object with header name keys)
console.log(res.rawHeaders);

// Read the body
console.log(await res.text());
The demo Wisp server at wss://wisp.mercurywork.shop is intentionally throttled and is provided for testing only. For production use, self-host a Wisp server and pass its URL to EpoxyClient.

​
Complete example

The following snippet combines all of the steps above into a single, copy-pasteable module. 
import init, { EpoxyClient, EpoxyClientOptions } from "@mercuryworkshop/epoxy-tls";

(async () => {
  // 1. Initialize the WASM module
  await init();

  // 2. Configure the client
  const options = new EpoxyClientOptions();
  options.user_agent = navigator.userAgent;
  options.wisp_v2 = true;

  // 3. Connect to a Wisp server
  // Replace with your own self-hosted server URL in production
  const client = new EpoxyClient("wss://wisp.mercurywork.shop", options);

  // 4. Make a proxied fetch request
  const res = await client.fetch("https://example.com");
  console.log(res.headers, res.rawHeaders);
  console.log(await res.text());
})();

​
Next steps

Fetch guide

Learn about request options, redirect handling, streaming bodies, and POST requests.

WebSocket guide

Open proxied WebSocket connections using EpoxyHandlers and connect_websocket.

API reference

Full reference for EpoxyClient, EpoxyClientOptions, and EpoxyHandlers.

Build docs developers (and LLMs) love

Get started for freeTalk to us