Mysterium Network Integration

Mysterium Network Integration

Specific situation: you are building an application that needs a decentralized VPN or residential proxy—without a single provider, without user KYC, with payment in crypto. Mysterium Network is a p2p network of ~13k nodes where anyone can sell traffic for MYST tokens. For a developer the task is not to "connect to VPN" but to embed Mysterium in your application as a programmable transport layer.

Mysterium Architecture: What's Under the Hood

Mysterium works on top of several protocols:

• Wireguard is the main protocol for VPN connections (UDP, fast, widely supported)
• OpenVPN is legacy, supported for compatibility
• NATS is a message broker for discovery and signaling between nodes
• Hermes is a payment settlement smart contract on Polygon (previously Ethereum)

Key component for developer is mysterium-vpn-js SDK (TypeScript) and myst-provider API (REST HTTP server running with node).

Programmatic Work with Mysterium via SDK

Launch and Node Connection

import { TequilapiClientFactory, NodeHttpTransport } from "mysterium-vpn-js";

const factory = new TequilapiClientFactory(
  "http://127.0.0.1:4050",  // tequilapi — REST API of node
  5000                        // timeout ms
);

const api = factory.build(NodeHttpTransport());

// Check node status
const nodeInfo = await api.healthCheck();
console.log("Node version:", nodeInfo.version);

// List available providers (sample from Discovery)
const proposals = await api.findProposals({
  serviceType: "wireguard",   // or "openvpn"
  qualityMin: 0.9,            // quality score filter (0-1)
  locationCountry: "DE",      // country of exit node
});

Session Creation and Management

// Identity — your "wallet" in the Mysterium network
const identities = await api.identityList();
if (identities.length === 0) {
  const identity = await api.identityCreate("your_passphrase");
  await api.identityRegister(identity.id, {
    token: undefined,  // referral token is optional
  });
}

const identity = identities[0];

// Make sure identity is registered on-chain
const status = await api.identityStatus(identity.id);
if (status.registrationStatus !== "Registered") {
  // Need to top up MYST balance for registration payment
  throw new Error("Identity not registered");
}

// Connect to selected provider
const connection = await api.connectionCreate({
  consumerId: identity.id,
  providerId: proposals[0].providerId,
  serviceType: "wireguard",
  connectOptions: {
    dnsOption: "auto",   // or specific DNS server
  }
});

console.log("Session ID:", connection.sessionId);
console.log("Status:", connection.status); // "Connected"

Session Monitoring and Statistics

// Current connection status
const stats = await api.connectionStatistics();
console.log({
  bytesSent: stats.bytesSent,
  bytesReceived: stats.bytesReceived,
  tokensSpent: stats.tokensSpent,  // MYST spent
  duration: stats.duration,         // seconds
});

// Current IP (to verify traffic goes through node)
const location = await api.connectionLocation();
console.log("Exit IP:", location.ip, "Country:", location.country);

// Disconnect
await api.connectionCancel();

Payment Integration: MYST on Polygon

Mysterium uses payment channels via Hermes contract on Polygon. Not direct on-chain transactions per megabyte—off-chain micropayments with periodic settlement.

Balance Top-Up

// Get address to top up consumer identity balance
const channelAddress = await api.paymentOrderGetChannelAddress(
  identity.id
);
// channelAddress is Polygon address, send MYST there

// Create order via built-in gateway (if on-ramp via card)
const order = await api.paymentOrderCreate(identity.id, {
  mystAmount: "10.0",
  payCurrency: "USD",
  gateway: "coingate",  // or "paypal"
  country: "US",
  callerData: "{}",
});
console.log("Payment URL:", order.publicGatewayData.paymentUrl);

For programmatic use case (your app tops up user balances itself)—direct MYST transfer on Polygon via ethers.js:

import { ethers } from "ethers";

const MYST_POLYGON = "0x1379e8886a0d08c7902c843f5c6353d3e8e99a18";
const mystContract = new ethers.Contract(MYST_POLYGON, ERC20_ABI, signer);

// channelAddress from api.paymentOrderGetChannelAddress()
await mystContract.transfer(channelAddress, ethers.parseUnits("10", 18));

Custom Discovery Service

By default Mysterium node uses centralized Discovery service of Mysterium Foundation to find providers. For enterprise use or private network—own Discovery needed.

Mysterium uses NATS as discovery broker. Can deploy self-hosted:

# docker-compose.yml for self-hosted discovery
version: '3.8'
services:
  nats:
    image: nats:2.9-alpine
    ports:
      - "4222:4222"
      - "8222:8222"  # monitoring
    command: "--jetstream --cluster_name mysterium-private"
  
  discovery:
    image: mysteriumnetwork/discovery:latest
    environment:
      - NATS_URL=nats://nats:4222
      - BROKER_ADDRESS=nats://nats:4222
    depends_on:
      - nats

Nodes in your private network are configured with --discovery.address pointing to your NATS.

Typical Use Cases

Decentralized proxy for web scraping instead of rotating residential proxies from Oxylabs/Brightdata, use Mysterium nodes. Cost is 3–10x lower, but reliability varies (p2p network ≠ enterprise SLA).

Privacy-preserving API calls mobile app makes requests to external APIs through Mysterium, hiding user IP from destination service.

Geo-distributed testing test your application from different geolocations programmatically, without renting VPS in each region.

Limitations to consider: Mysterium gives no guarantees of bandwidth or uptime from specific node. For apps with latency <100ms requirements—p2p VPN is not optimal choice. Need fallback mechanism and provider switching logic.

Basic integration via mysterium-vpn-js in existing app: 2–3 weeks. Full with billing, node under your backend control and custom discovery: 6–10 weeks.