synthient-rust

Synthient

High-fidelity data on residential proxies, VPNs, and other anonymized IPs.

synthient-rust

The synthient crate is the official Rust SDK for the Synthient API: IP and domain intelligence, account details, and real-time and bulk data feeds.

SDK Installation

cargo add synthient
cargo add tokio --features full

The client is asynchronous and runs on Tokio, whose full feature covers the examples below. The crate has these features:

Feature	Default	Description
`rustls`	Yes	TLS through rustls
`native-tls`	No	TLS through the platform's native library
`grpcschema`	No	The gRPC schema fetcher

To use the platform's TLS library, turn off the default features:

cargo add synthient --no-default-features --features native-tls

Requirements

Rust 1.85 or later, and a Tokio runtime with its time driver enabled, which #[tokio::main] provides.

The newest releases of some dependencies need Rust 1.88, so Rust 1.85 to 1.87 needs Cargo's MSRV-aware resolver. Edition 2024 packages use it by default. In an edition 2021 package, turn it on in [package], or in [workspace] for a workspace:

[package]
resolver = "3"

API Keys

Every request needs a Synthient API key. Keys are issued from the Synthient dashboard; if you don't have one, contact us. A key's scopes decide what it can call: BASIC covers the lookups and account, and each feed has its own scopes, listed under Feeds.

If a request fails even though you are sending a key:

401 Unauthorized: the key is malformed, unknown, or revoked.
402 Payment Required: the team is out of lookup credits.
403 Forbidden: the key lacks the scope for that endpoint or feed.

account shows the key's scopes and the team's remaining credits.

Authentication

This SDK supports the following security scheme:

Name	Type	Scheme
`api_key`	API key	`x-api-key` header

Pass the key to Client::new, reading it from the environment or a secret manager:

let client = synthient::Client::new(std::env::var("SYNTHIENT_API_KEY")?)?;

Client::new makes no network calls. To check a key, call account, which costs no credits.

SDK Example Usage

Look up an IP address

Get the network, location, and risk intelligence for an IPv4 or IPv6 address. Each lookup costs one credit; failed lookups are free.

use std::net::Ipv4Addr;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = synthient::Client::new(std::env::var("SYNTHIENT_API_KEY")?)?;

    let info = client.lookup_ip(Ipv4Addr::new(8, 8, 8, 8)).await?;
    if let Some(intelligence) = &info.intelligence {
        println!("{} {:?}", intelligence.risk_score, intelligence.categories);
    }
    Ok(())
}

network, location, and intelligence are None when the API has no data for them. Reuse one client; clones are cheap and share a connection pool. The examples below reuse client, and runnable programs are in examples.

Look up many IP addresses

Look up as many as 1000 addresses in one request for ceil(n * 0.9) credits. Private and reserved addresses are skipped and duplicates are merged, so match results by ip.

let ips = ["8.8.8.8".parse()?, "1.1.1.1".parse()?];
for result in client.lookup_ips(&ips).await? {
    if let Some(intelligence) = &result.intelligence {
        println!("{} {}", result.ip, intelligence.risk_score);
    }
}

Look up a domain

Get the honeypot traffic observed for a domain and its most recent events. Each lookup costs one credit.

let domain = client.lookup_domain("example.com", Some(10)).await?;
println!("{} {}", domain.status, domain.stats.events_24h);
for event in &domain.recent_events {
    println!(
        "{} {} {}",
        event.timestamp.0, event.target_subdomain, event.port
    );
}

The second argument caps the recent events, from 1 to 1000; None uses the default of 50.

Check your account

Get the key's account, scopes, and remaining lookup credits, at no cost.

let account = client.account().await?;
println!(
    "{} {:?} {}",
    account.organization.name, account.scopes, account.lookup_quota.credits
);

Available Resources and Operations

Available methods

Client

lookup_ip - Look up an IPv4 or IPv6 address
lookup_ips - Look up as many as 1000 addresses in one request
lookup_domain - Look up the honeypot traffic observed for a domain
account - Get the key's account, scopes, and remaining lookup credits
health - Check that the API and its dependencies are healthy

Feeds

Each feed comes from a client method, such as client.proxies(), and has the same methods:

stream - Open the feed's real-time event stream
list_exports - List one page of the feed's Parquet exports, newest first
all_exports - Stream every export, fetching pages as needed
export_meta - Get an export's checksum, size, row count, and Parquet schema
download - Download an export's Parquet file
download_url - Get a presigned URL for an export's Parquet file, valid for 24 hours

Method	Data	Event type	Stream scope	Export scope
`proxies`	Residential, mobile, and datacenter proxies	`ProxyEvent`	`PROXY_FIREHOSE`	`PROXY_FEEDS`
`anonymizers`	VPN and anonymizer IP ranges	`AnonymizerEvent`	`ANONYMIZERS_STREAM`	`ANONYMIZERS_FEED`
`torrents`	BitTorrent DHT and tracker peers	`TorrentEvent`	`TORRENTS_STREAM`	`TORRENTS_FEED`
`ja4t`	JA4T TCP fingerprints	`Ja4tEvent`	`JA4T_STREAM`	`JA4T_FEED`
`helios_http`	Helios honeypot HTTP requests	`HeliosHttpEvent`	`HONEYPOT_HTTP_STREAM`	`HONEYPOT_HTTP_FEED`
`helios_https`	Helios honeypot TLS ClientHellos	`HeliosHttpsEvent`	`HONEYPOT_HTTPS_STREAM`	`HONEYPOT_HTTPS_FEED`
`helios_dns`	Helios honeypot tunnel destinations	`HeliosDnsEvent`	`HONEYPOT_DNS_STREAM`	`HONEYPOT_DNS_FEED`
`helios_adb`	Helios honeypot Android Debug Bridge commands	`HeliosAdbEvent`	`HONEYPOT_ADB_STREAM`	`HONEYPOT_ADB_FEED`

Streaming

stream opens a connection to a feed's real-time events and returns an EventStream. Read it with next or as a Stream, and drop it to close the connection:

use synthient::Error;

async fn print_proxies(client: &synthient::Client) -> synthient::Result<()> {
    let mut events = client.proxies().stream().await?;
    while let Some(event) = events.next().await {
        let event = event?;
        println!(
            "{} {}",
            event.ip.unwrap_or_default(),
            event.provider.unwrap_or_default()
        );
    }
    Ok(())
}

loop {
    match print_proxies(&client).await {
        Ok(()) => {}
        Err(Error::Api(err)) if matches!(err.status.as_u16(), 401 | 403) => {
            return Err(Error::Api(err).into());
        }
        Err(err) => {
            eprintln!("proxy stream: {err}");
            // Avoid reconnecting in a tight loop.
            tokio::time::sleep(Duration::from_secs(2)).await;
        }
    }
}

The server closes each stream after up to 30 minutes. That ends the stream with None, and the loop reconnects at once.
A 401 or 403 stops the loop, because reconnecting can't fix a rejected key or a missing scope.
Any other failure ends the stream, and the loop waits 2 seconds before reconnecting.
Events sent while disconnected are missed. The API has no resume cursor.

Pagination

list_exports returns one page of a feed's exports, newest first. Its first argument is the page size, from 1 to 500; None uses the default of 100. Pass page.next_cursor.as_deref() as the second to get the next page; it is None on the last one.

let page = client.proxies().list_exports(Some(50), None).await?;
for export in &page.exports {
    println!("{} {} {}", export.id, export.kind, export.row_count);
}

all_exports returns a stream that fetches the pages for you as you read it:

let mut exports = client.proxies().all_exports(None, None);
while let Some(export) = exports.next().await {
    let export = export?;
    println!("{} {} {}", export.id, export.kind, export.row_count);
}

On the first page, the newest hourly export has the ID "latest", a moving alias for the freshest export. Its date and hour give its stable ID, such as "2026-10-14/21".

Downloads

Exports are Parquet files. download returns a Download, which yields the file in chunks as they arrive:

use tokio::io::AsyncWriteExt;

let mut download = client.proxies().download("latest").await?;
let mut file = tokio::fs::File::create("proxies.parquet").await?;
while let Some(chunk) = download.next().await {
    file.write_all(&chunk?).await?;
}
file.flush().await?;

Name an export by its id from a listing, by "latest", or by a UTC day as "YYYY-MM-DD" or hour as "YYYY-MM-DD/H".
export_meta returns the file's SHA-256 checksum. Use a fixed ID for both calls, because "latest" can move between them.
download_url returns a presigned URL that works without a key for 24 hours, so treat it as a secret. Your API key is never sent to the storage host.
Hourly exports roll into the daily export shortly after 00:30 UTC the next day. After that, the hour returns a 400.

Retries

The client retries a failed request up to twice, backing off exponentially with jitter and honoring Retry-After:

Requests	Retried on
Account and feed requests	500, 502, 503, and 504, transport errors, and 429 with `Retry-After`
Billed lookups and `health`	Only 429 with `Retry-After`, which comes before any work, so a lookup is never charged twice

A 429 without Retry-After means the monthly request budget is spent or too many streams are open, so it is returned at once. Downloads from the storage host are never retried.

Set the number of retries with max_retries on Client::builder. Zero disables them:

let client = synthient::Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .max_retries(4)
    .build()?;

Timeouts

By default, connecting gives up after 30 seconds and a read that stalls for 60 seconds fails. There is no overall timeout, because streams and downloads are long-lived. Set one with timeout on the builder:

let client = synthient::Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .timeout(Duration::from_secs(10))
    .build()?;

It covers every attempt and the waits between them. For streams and downloads, it covers only opening them. An operation that runs out of time returns Error::Timeout. To bound a single call, wrap it in tokio::time::timeout.

Error Handling

A request that fails with a non-success status returns Error::Api, which holds an ApiError:

Field	Type	Description
`status`	`StatusCode`	HTTP status code, such as `404`
`problem_type`	`Option<String>`	URI identifying the problem type
`title`	`Option<String>`	Short summary of the problem type
`detail`	`Option<String>`	Explanation of this occurrence
`errors`	`BTreeMap<String, Vec<String>>`	Validation messages by request field
`request_id`	`Option<String>`	Request ID to give Synthient support
`retry_after`	`Option<Duration>`	How long the server asked you to wait

Its Display output contains only the HTTP status, so it is safe to log. The fields hold untrusted server data.

Example

use synthient::{Error, StatusCode};

match client.lookup_ip(Ipv4Addr::new(8, 8, 8, 8)).await {
    Ok(info) => println!("{:?}", info.intelligence),
    Err(Error::Api(err)) if err.status == StatusCode::PAYMENT_REQUIRED => {
        eprintln!("out of lookup credits");
    }
    Err(Error::Api(err)) if err.status == StatusCode::TOO_MANY_REQUESTS => {
        match err.retry_after {
            Some(retry_after) => eprintln!("rate limited, retry after {retry_after:?}"),
            None => eprintln!("monthly request budget spent"),
        }
    }
    Err(Error::Api(err)) => {
        let message = err.detail.or(err.title).unwrap_or_default();
        let request_id = err.request_id.unwrap_or_default();
        eprintln!("request {request_id} failed: {message}");
    }
    Err(err) => eprintln!("lookup failed: {err}"),
}

Error Types

Error is #[non_exhaustive], so a match on it needs a catch-all arm. Its variants:

Api: the API, or the storage host during download, returned a non-success status.
InvalidInput: an argument or setting, such as an empty API key, was rejected before any request is sent.
Http: the HTTP client could not be built, the request could not be sent, or the response could not be read.
Timeout: the operation outlasted the client's timeout.
Decode: a response or stream event was not the JSON the API documents.
Protocol: a response broke the API's contract, such as an oversized body.

Status codes

Status	Meaning
400	The request is invalid, such as an hourly export that was rolled up
401	The API key is malformed, unknown, or revoked
402	The team is out of lookup credits
403	The key lacks the scope for the endpoint or feed
404	The export doesn't exist, or a daily export is still rolling up (`retry_after` is set)
422	The input is invalid, such as a private address or a malformed domain
429	Rate limited if `retry_after` is set; otherwise the budget is spent or too many streams are open
5xx	The server failed

Server Selection

Override Server URL Per-Client

The default server is https://api.synthient.com/api/v4. Use base_url on the builder to send requests elsewhere, such as a mock server in tests:

let client = synthient::Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .base_url("http://localhost:8080/api/v4")
    .build()?;

Custom HTTP Client

Pass a reqwest ClientBuilder to http_client, for example to use a specific proxy. Build it from the re-exported synthient::reqwest, so the versions match:

use synthient::reqwest;

let http = reqwest::Client::builder()
    .proxy(reqwest::Proxy::all("http://proxy.example.com:8080")?)
    .connect_timeout(Duration::from_secs(30))
    .read_timeout(Duration::from_secs(60));

let client = synthient::Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .http_client(http)
    .build()?;

Set the connect and read timeouts yourself, as above, because your builder replaces the defaults.
Don't set a total timeout on it. It would also cut off streams and downloads.
The SDK turns off reqwest's redirects and retries on your builder, so the API key never reaches the storage host and a billed lookup is never sent twice.
The default client already honors HTTP_PROXY, HTTPS_PROXY, and the macOS and Windows proxy settings.

user_agent("my-app/1.2") on the builder adds your product token to the User-Agent header.

Debugging

on_response on the builder calls a function after every API response, including retries, pages, and stream handshakes, with a ResponseMetadata holding the status, request ID, rate limit, and headers:

let client = synthient::Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .on_response(|meta| {
        eprintln!("status={} request_id={:?}", meta.status, meta.request_id);
        if let Some(rate_limit) = &meta.rate_limit {
            eprintln!(
                "rate limit: {} of {} left",
                rate_limit.remaining, rate_limit.limit
            );
        }
    })
    .build()?;

The hook runs synchronously, before the response body is read, so keep it fast.

Warning

Response headers can contain secrets, such as presigned download URLs. Avoid logging meta.headers in production.

gRPC Schema

The grpcschema module fetches the protobuf schema of the Synthient gRPC API through server reflection. It needs the grpcschema feature:

cargo add synthient --features grpcschema

let schema = match synthient::grpcschema::fetch(std::env::var("SYNTHIENT_API_KEY")?).await {
    Ok(schema) => schema,
    Err(err) => match err.explain() {
        Some(explanation) => return Err(format!("{explanation} {err}").into()),
        None => return Err(err.into()),
    },
};
for file in &schema.descriptor_set.file {
    println!("{} {}", file.name(), file.package());
}

schema.descriptor_set is a prost_types::FileDescriptorSet, and the module re-exports prost and prost_types. SchemaError::explain describes common gRPC errors in plain language.

Development

Maturity

This SDK follows Semantic Versioning. Breaking changes ship only in a new major version. Response types and enums are #[non_exhaustive], and unknown enum values decode to Unknown, so new API fields and values can arrive in minor versions.

Contributions

Bug reports and feature requests are welcome as GitHub issues. For questions about the API or your account, contact Synthient support.

License

Apache 2.0

Name		Name	Last commit message	Last commit date
.github		.github
.sdkgen		.sdkgen
assets		assets
consumer-test		consumer-test
examples		examples
scripts		scripts
src		src
tests/integration		tests/integration
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Synthient

synthient-rust

Table of Contents

SDK Installation

Requirements

API Keys

Authentication

SDK Example Usage

Look up an IP address

Look up many IP addresses

Look up a domain

Check your account

Available Resources and Operations

Client

Feeds

Streaming

Pagination

Downloads

Retries

Timeouts

Error Handling

Example

Error Types

Server Selection

Override Server URL Per-Client

Custom HTTP Client

Debugging

gRPC Schema

Development

Maturity

Contributions

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages