dominusnode -- Official Dominus Node Rust SDK

The official Rust SDK for the Dominus Node rotating proxy-as-a-service platform. Manage proxy connections, API keys, wallet balances, usage tracking, and more from Rust applications.

• Async by default -- powered by Tokio and reqwest
• Strongly typed -- every request and response has a dedicated type
• Auto token refresh -- JWT expiry handled transparently with async mutex
• Rate limit auto-retry -- 429 responses automatically retried with backoff
• Typed error hierarchy -- pattern-match on specific error variants
• URL-safe -- all proxy URL components are percent-encoded (RFC 3986)

Installation

Add to your Cargo.toml:

[dependencies]
dominusnode = "1.0"
tokio = { version = "1", features = ["full"] }

Feature Flags

Quick Start

use dominusnode::{DominusNodeClient, Config};

#[tokio::main]
async fn main() -> dominusnode::Result<()> {
    // Create client with default config
    let client = DominusNodeClient::new(Config {
        base_url: "https://api.dominusnode.com".into(),
        ..Config::default()
    })?;

    // Authenticate with API key
    client.connect_with_key("dn_live_your_api_key").await?;

    // Check wallet balance
    let balance = client.wallet.get_balance().await?;
    println!("Balance: {} cents", balance.balance_cents);

    // Build a proxy URL
    let proxy_url = client.proxy.build_url("dn_live_your_api_key", None);
    println!("Proxy URL: {}", proxy_url);
    // => http://user:dn_live_your_api_key@proxy.dominusnode.com:8080

    Ok(())
}

Authentication

API Key (Recommended for Proxy Usage)

let client = DominusNodeClient::new(Config::default())?;
client.connect_with_key("dn_live_your_api_key").await?;

Or provide in the config:

let client = DominusNodeClient::new(Config {
    base_url: "https://api.dominusnode.com".into(),
    api_key: Some("dn_live_your_api_key".into()),
    ..Config::default()
})?;
// Note: API key auth happens lazily on first authenticated request

Email/Password

let client = DominusNodeClient::new(Config::default())?;
let result = client.connect_with_credentials("user@example.com", "SecurePass123!").await?;

if result.mfa_required {
    // MFA enabled -- complete with TOTP code
    client.complete_mfa("123456", None, false).await?;
}

Pre-existing Tokens

let client = DominusNodeClient::new(Config {
    access_token: Some("eyJhbGci...".into()),
    refresh_token: Some("eyJhbGci...".into()),
    ..Config::default()
})?;

Resources

All API operations are accessed through public resource fields on the client.

Auth

// Register
let result = client.auth.register("user@example.com", "SecurePass123!").await?;

// Login
let result = client.auth.login("user@example.com", "SecurePass123!").await?;

// Change password
client.auth.change_password("OldPass123!", "NewPass456!").await?;

// Logout (revokes all refresh tokens)
client.auth.logout().await?;

// Get current user
let user = client.auth.me().await?;
println!("User: {}, Admin: {}", user.email, user.is_admin);

MFA

// Setup MFA
let setup = client.auth.mfa_setup().await?;
println!("Secret: {}", setup.secret);
println!("OTPAuth URI: {}", setup.otpauth_uri);
println!("Backup codes: {:?}", setup.backup_codes); // Save these!

// Enable MFA
client.auth.mfa_enable("123456").await?;

// Check status
let status = client.auth.mfa_status().await?;
println!("Enabled: {}, Backup codes: {}", status.enabled, status.backup_codes_remaining);

// Disable MFA
client.auth.mfa_disable("password", "123456").await?;

API Keys

// Create key (raw key only shown once)
let created = client.keys.create("my-scraper").await?;
println!("Key: {}", created.key); // dn_live_xxxx -- save this!

// List keys
let keys = client.keys.list().await?;
for key in &keys {
    println!("  {} - {}", key.prefix, key.label);
}

// Revoke
client.keys.revoke("key-uuid").await?;

Wallet

// Balance
let balance = client.wallet.get_balance().await?;
println!("Balance: {} cents (${:.2})", balance.balance_cents, balance.balance_cents as f64 / 100.0);

// Transactions
let txs = client.wallet.get_transactions(Some(20), Some(0)).await?;
for tx in &txs {
    println!("  {}: {} cents - {}", tx.tx_type, tx.amount_cents, tx.description);
}

// Stripe top-up
let checkout = client.wallet.topup_stripe(5000).await?;
println!("Checkout URL: {}", checkout.url);

// Crypto top-up
let invoice = client.wallet.topup_crypto(5000, "btc").await?;

Usage

// Usage records
let usage = client.usage.get(Some("2026-01-01"), Some("2026-02-01"), Some(50), Some(0)).await?;

// Daily breakdown
let daily = client.usage.get_daily(Some("2026-01-01"), Some("2026-02-01")).await?;
for day in &daily {
    println!("  {}: {} bytes", day.date, day.bytes_total);
}

// Top hosts
let hosts = client.usage.get_top_hosts(Some(10)).await?;
for host in &hosts {
    println!("  {}: {} bytes", host.host, host.bytes_total);
}

// CSV export
let csv = client.usage.export_csv(Some("2026-01-01"), Some("2026-02-01")).await?;

Plans

// List plans
let plans = client.plans.list().await?;
for plan in &plans {
    println!("  {}: {} - {} cents/GB", plan.id, plan.name, plan.price_per_gb_cents);
}

// Current plan
let current = client.plans.get_user_plan().await?;

// Change plan
client.plans.change("vol100").await?;

Sessions

let sessions = client.sessions.get_active().await?;
for session in &sessions {
    println!("  Session {}: {} bytes", session.id, session.bytes_total);
}

Proxy

use dominusnode::types::ProxyUrlOptions;

// Default proxy URL
let url = client.proxy.build_url("dn_live_key", None);

// With geo-targeting
let opts = ProxyUrlOptions {
    protocol: Some("http".into()),
    country: Some("US".into()),
    state: Some("california".into()),
    city: Some("losangeles".into()),
    ..Default::default()
};
let geo_url = client.proxy.build_url("dn_live_key", Some(&opts));

// SOCKS5
let socks_opts = ProxyUrlOptions {
    protocol: Some("socks5".into()),
    country: Some("DE".into()),
    ..Default::default()
};
let socks_url = client.proxy.build_url("dn_live_key", Some(&socks_opts));

// Sticky session
let sticky_opts = ProxyUrlOptions {
    country: Some("US".into()),
    session_id: Some("my-session-123".into()),
    ..Default::default()
};
let sticky_url = client.proxy.build_url("dn_live_key", Some(&sticky_opts));

// Health check (no auth)
let health = client.proxy.get_health().await?;
println!("Status: {}, Sessions: {}", health.status, health.active_sessions);

// Detailed status
let status = client.proxy.get_status().await?;

// Configuration
let config = client.proxy.get_config().await?;

Admin

// List users
let users = client.admin.list_users(Some(50), Some(0)).await?;

// User detail
let detail = client.admin.get_user("user-uuid").await?;

// Suspend/activate
client.admin.suspend_user("user-uuid").await?;
client.admin.activate_user("user-uuid").await?;

// Revenue
let revenue = client.admin.get_revenue(None, None).await?;
println!("Total: {} cents", revenue.total_revenue_cents);

// System stats
let stats = client.admin.get_stats().await?;
println!("Users: {}, Active sessions: {}", stats.total_users, stats.active_sessions);

Using Proxy URLs with reqwest

use dominusnode::{DominusNodeClient, Config};
use dominusnode::types::ProxyUrlOptions;
use reqwest::Proxy;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = DominusNodeClient::new(Config::default())?;
    client.connect_with_key("dn_live_your_key").await?;

    // Build proxy URL with geo-targeting
    let opts = ProxyUrlOptions {
        country: Some("US".into()),
        ..Default::default()
    };
    let proxy_url = client.proxy.build_url("dn_live_your_key", Some(&opts));

    // Use with reqwest
    let http_client = reqwest::Client::builder()
        .proxy(Proxy::all(&proxy_url)?)
        .build()?;

    let resp = http_client.get("https://httpbin.org/ip").send().await?;
    println!("{}", resp.text().await?);

    Ok(())
}

Error Handling

All errors are variants of DominusNodeError, implementing std::error::Error via thiserror:

use dominusnode::DominusNodeError;

match client.connect_with_key("dn_live_invalid").await {
    Ok(_) => println!("Connected!"),
    Err(DominusNodeError::Authentication(msg)) => {
        eprintln!("Invalid API key: {}", msg);
    }
    Err(DominusNodeError::RateLimit { retry_after_secs, .. }) => {
        eprintln!("Rate limited, retry after {}s", retry_after_secs);
    }
    Err(DominusNodeError::InsufficientBalance(msg)) => {
        eprintln!("Low balance: {}", msg);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Configuration

use dominusnode::Config;

let config = Config {
    base_url: "https://api.dominusnode.com".into(),
    api_key: None,
    access_token: None,
    refresh_token: None,
    proxy_host: "proxy.dominusnode.com".into(),
    http_proxy_port: 8080,
    socks5_proxy_port: 1080,
};

All fields have sensible defaults via Config::default().

Security Notes

• Token storage: Tokens are stored in memory only (never written to disk)
• Token refresh: Uses tokio::sync::Mutex to prevent concurrent refresh races
• URL encoding: API keys and geo-targeting values are percent-encoded (RFC 3986)
• TLS: reqwest verifies TLS certificates by default
• Force refresh: On 401, the SDK forces a token refresh (bypasses expiry check) to handle stale-but-not-expired tokens

License

MIT