Support for these languages is currently in development: Python, Node, Java, Ruby.

# Go SDK

The official Synthient client library for Go. It covers the same surfaces documented across these docs: IP and domain lookups, account details, Parquet snapshot feeds, real-time firehose and Helios streams, and gRPC schema introspection.

It's open source at [github.com/synthient/go-synthient](https://github.com/synthient/go-synthient), with full reference docs on [pkg.go.dev](https://pkg.go.dev/github.com/synthient/go-synthient/v2).

## Install

```bash
go get -u github.com/synthient/go-synthient/v2
```

Requires Go 1.25 or later. Real-time streams are built on `iter.Seq2`, available since Go 1.23.

## Getting started

Every request goes through a `synthient.Client`. Create one with your API key:

```go
client := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
```

Each method takes a trailing `*synthient.RequestOptions`. Pass `nil` for the defaults, or supply a context to control cancellation and timeouts:

```go
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
opts := &synthient.RequestOptions{Context: ctx}
```

## Lookups

`GetIP` enriches a single address, `GetIPs` batches many into one request, and `GetDomain` returns Helios traffic statistics for a domain.

**Lookups**

```go title="IP"
ip, err := client.GetIP("213.149.183.127", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(ip.Intelligence.RiskScore, ip.Network.Isp, ip.Location.Country)
```

```go title="Batch"
results, err := client.GetIPs([]string{"8.8.8.8", "1.1.1.1"}, nil)
if err != nil {
    log.Fatal(err)
}
for _, ip := range results {
    fmt.Println(ip.IP, ip.Intelligence.RiskScore)
}
```

```go title="Domain"
domain, err := client.GetDomain("google.com", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(domain.Stats.Events24H, domain.Status)
```

`GetAccount` returns the profile and quota details for the authenticated key:

```go
account, err := client.GetAccount(nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(account.Organization.Name, account.LookupQuota.Credits)
```

## Snapshot feeds

`FeedSnapshots` pages through the available daily and hourly snapshots, newest first. `FeedSnapshotMeta` returns the checksum, row count, size, and Parquet schema for one of them; `date` accepts `latest`, `YYYY-MM-DD`, or `YYYY-MM-DD/HH`.

```go
meta, err := client.FeedSnapshotMeta("proxies", "latest", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(meta.Rows, meta.Checksum)
```

`DownloadFeedSnapshot` follows the API's redirect and hands back a streaming reader for the Parquet file, which the caller closes. Pass a non-nil hour pointer (0–23) to address a specific hourly snapshot in the current UTC day.

```go
r, err := client.DownloadFeedSnapshot("proxies", "latest", nil, nil)
if err != nil {
    log.Fatal(err)
}
defer r.Close()
```

Per-feed wrappers take the same `(date, hour, filename, opts)` arguments with the stream pre-filled: `DownloadProxy`, `DownloadAnonymizer`, `DownloadTorrent`, `DownloadHeliosHTTP`, and `DownloadHeliosTLS`. Give them a non-empty filename to write straight to disk.

```go
_, err := client.DownloadHeliosTLS("latest", nil, "helios-tls.parquet", nil)
```

See [Feeds](https://docs.synthient.com/enterprise/feeds) for the full snapshot catalog and schemas.

## Streams

Every stream method returns an [`iter.Seq2`](https://pkg.go.dev/iter#Seq2) that yields one event per NDJSON line. Break out of the loop or cancel the context to stop.

**Streams**

```go title="Proxies"
for event, err := range client.StreamProxy(nil) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(event.IP, event.Provider, event.CountryCode)
}
```

```go title="Anonymizers"
for event, err := range client.StreamAnonymizer(nil) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(event.RangeStart, event.RangeEnd, event.Type, event.Provider)
}
```

```go title="Torrents"
for event, err := range client.StreamTorrent(nil) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s %s peers=%d\n", event.InfoHash, event.Name, len(event.Peers))
}
```

```go title="Helios HTTP"
for event, err := range client.StreamHeliosHTTP(nil) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(event.Details.Method, event.Details.URI, event.Domain)
}
```

```go title="Helios TLS"
for event, err := range client.StreamHeliosTLS(nil) {
    if err != nil {
        log.Fatal(err)
    }
    if event.Details == nil {
        continue // sensor could not parse the handshake
    }
    fmt.Println(event.Domain, event.Details.HandshakeVersion, len(event.Details.CipherSuites))
}
```

Stream payloads match the [Firehose](https://docs.synthient.com/enterprise/firehose) and [Helios](https://docs.synthient.com/enterprise/helios) documentation field for field.

## gRPC schema

`GRPCSchema` pulls protobuf file descriptors from `grpc.synthient.com:443` over server reflection. Pass `nil` to resolve every service, or name the symbols you want.

```go
result, err := client.GRPCSchema(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, svc := range result.Symbols {
    fmt.Println(svc)
}
```

`ExplainGRPCError` turns transport failures into human-readable messages, and `NormalizeGRPCEndpoint` handles custom endpoint strings. More detail is on the [gRPC](https://docs.synthient.com/grpc) page.

## Client customization

Point the client at a different endpoint, or replace the HTTP client to control timeouts and proxies:

```go
client.BaseAPI.Host = "synthient.myserver.com"
client.HttpClient = &http.Client{Timeout: 30 * time.Second}
```