nym-sdk

nym-sdk is the Rust SDK for the Nym mixnet. All modules share a common MixnetClient that manages gateway connections, Sphinx encryption, and cover traffic.

┌──────────────────────────────────────────────────────────────┐
│  Your Rust app (alice)                                       │
│       └─ MixnetClient (Sphinx layering, cover traffic)       │
│            └─ WebSocket to entry gateway                     │
│                 └─ Nym mixnet (entry → 3 mix layers → exit)  │
│                      └─ MixnetClient (bob)                   │
│                           └─ Your Rust app (bob)             │
└──────────────────────────────────────────────────────────────┘

Both sides run a MixnetClient. Sphinx encryption protects every hop end-to-end; neither gateway nor any mix node can link sender to receiver.

Full API reference: docs.rs/nym-sdk (opens in a new tab)

For an overview of what the SDK can do, see the Tour. For setup instructions, see Installation.

Modules

Module	What it does	Status
Stream	Multiplexed `AsyncRead + AsyncWrite` byte streams over the Mixnet, the closest analogue to TCP sockets.	Recommended
Mixnet	Raw message payloads, independently routed, no connections or ordering. Full control over the communication model.	Stable
SOCKS5	Local SOCKS5 proxy that routes any SOCKS-capable application through the Mixnet to a Network Requester (proxy mode, exits to clearnet).	Stable
Client Pool	Keeps ready-to-use `MixnetClient` instances warm for bursty workloads.	Stable
TcpProxy	TCP socket proxying with session management and message ordering.	Deprecated
FFI	Go and C/C++ bindings.	Stable

🚫

TcpProxy is deprecated. Use the Stream module for new projects.

Which module do I need?

Two questions settle it.

Are you reaching a third-party service, or another Nym client? A clearnet destination means proxy mode, and that is smolmix or the SOCKS5 module rather than anything below. Both ends running your software means end to end, and the choice is between Stream and Mixnet.

Is it a conversation, or a set of independent messages? This is the call people get wrong.

Stream for anything interactive: a chat, a request/response protocol, or code that expects AsyncRead/AsyncWrite. It reorders on a sequence number, so bytes arrive in the order you wrote them, and framing comes free from the async I/O traits.
Mixnet for messages that stand alone: a notification, a one-shot request, a broadcast. There are no ordering guarantees, so two messages sent in order may arrive reversed. Building a conversation on it means writing your own sequencing and framing.

Both are end to end, and both keep the sender anonymous through reply SURBs. The difference is whether the protocol you are building has a sequence to preserve.

If the thing you are writing is the side that receives requests and answers them, rather than the side that sends, see Building a Nym Service Provider. It covers the receive-and-reply loop, why the client needs persistent storage to keep a stable address, and the sending budget a provider shares across all of its clients.

When to use streams vs messages compares them line by line, including ordering, status and what each is best for.

Proxy-mode crates

For proxy-mode integrations (reaching third-party services through an Exit Gateway), see also:

smolmix: TcpStream and UdpSocket over the Mixnet via a userspace IP stack. Compatible with tokio-rustls, hyper, tokio-tungstenite, and the rest of the async Rust ecosystem.
nym-smoldvpn: a userspace 1-/2-hop WireGuard dVPN datapath. Tunnels tokio TcpStream, UdpSocket and gRPC/HTTP traffic to clearnet via the exit gateway, with an optional QUIC bridge for DPI-blocked clients.
SOCKS5 module: SOCKS4/4a/5 proxy via the Exit Gateway's Network Requester. Works with any SOCKS-capable application without code changes.

nym-sdk

Modules

Which module do I need?

Proxy-mode crates

See also