Go SDK - OathNet API

Installation

go get github.com/oathnet/oathnet-go

Requirements: Go 1.21+ Source: oathnet/oathnet-go

Quick Start

package main

import (
    "fmt"
    "log"
    "github.com/oathnet/oathnet-go/pkg/oathnet"
)

func main() {
    // Initialize client with API key (required)
    client, err := oathnet.NewClient("your-api-key")
    if err != nil {
        log.Fatal(err)
    }

    // Search breaches
    result, err := client.Search.Breach("user@example.com", nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d results\n", result.Data.ResultsFound)
    for _, record := range result.Data.Results {
        fmt.Printf("%s: %s\n", record.Email, record.Password)
    }
}

Authentication

import (
    "time"
    "github.com/oathnet/oathnet-go/pkg/oathnet"
)

// Explicit API key (required)
client, err := oathnet.NewClient("your-api-key")

// With options
client, err := oathnet.NewClient("your-api-key",
    oathnet.WithBaseURL("https://oathnet.org/api"),
    oathnet.WithTimeout(30 * time.Second),
)

Search Service

Breach Search

// Basic search
result, err := client.Search.Breach("user@example.com", nil)
if err != nil {
    log.Fatal(err)
}

// With options
opts := &oathnet.SearchOptions{
    DBNames: "linkedin_2012,adobe_2013",
}
result, err := client.Search.Breach("user@example.com", opts)

// Access results
fmt.Printf("Total: %d\n", result.Data.ResultsFound)
fmt.Printf("Shown: %d\n", result.Data.ResultsShown)

for _, record := range result.Data.Results {
    fmt.Printf("Email: %s\n", record.Email)
    fmt.Printf("Password: %s\n", record.Password)
    fmt.Printf("Database: %s\n", record.DBName)
}

// Pagination
if result.Data.Cursor != "" {
    nextOpts := &oathnet.SearchOptions{
        Cursor: result.Data.Cursor,
    }
    nextPage, _ := client.Search.Breach("user@example.com", nextOpts)
}

Initialize Session

Search sessions group related lookups for the same query. Set SearchType when you already know what the query is; otherwise OathNet will detect it. Reuse the returned Session.ID as SearchID on follow-up searches.

// Create a search session for quota optimization.
result, err := client.Search.InitSession("user@example.com", &oathnet.SearchSessionOptions{
    SearchType: "email",
})
if err != nil {
    log.Fatal(err)
}

sessionID := result.Data.Session.ID
fmt.Printf("Session ID: %s\n", sessionID)
fmt.Printf("Status: %s\n", result.Data.Session.Status)
fmt.Printf("Search Type: %s\n", result.Data.Session.SearchType)
fmt.Printf("Expires: %s\n", result.Data.Session.ExpiresAt)

if result.Data.Summary != nil {
    fmt.Printf("Available services: %d\n", result.Data.Summary.AvailableServices)
}

// Reuse the session ID on current V2 search calls.
breachResults, err := client.Breach.Search("user@example.com", &oathnet.BreachV2SearchOptions{
    SearchID: sessionID,
    PageSize: 25,
})
if err != nil {
    log.Fatal(err)
}
if breachResults.Data != nil {
    fmt.Printf("Breach items: %d\n", len(breachResults.Data.Items))
}

AI Filters

Translate natural-language prompts into reusable V2 structured filters.

aiFilter, err := client.AI.Create(oathnet.V2AIFilterRequest{
    Index: oathnet.AIFilterIndexBreach,
    Query: "US gmail users with LinkedIn records after 2020",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(aiFilter.FilterID)
fmt.Printf("%+v\n", aiFilter.Filter)

context, err := client.AI.GetContext(aiFilter.FilterID)
if err != nil {
    log.Fatal(err)
}

fmt.Println(context.IndexType)
fmt.Println(context.Query)

Use aiFilter.FilterID with V2 search, export, bulk-search, or scanner QueryConfig flows when you want OathNet to reuse the generated filter context. Set FilterID on V2AIFilterRequest to refine an existing context.

V2 Breach Search

Use V2 breach search when you need fielded filters, structured filters, or autocomplete-driven workflows. GET is best for simple filters that fit in query parameters. POST is best when the filter tree comes from AI filters, saved UI state, or a complex manual builder.

// Simple pivots stay readable and shareable
result, err := client.Breach.Search("user@example.com", &oathnet.BreachV2SearchOptions{
    DBNames:  []string{"linkedin_2012"},
    Fields:   []string{"email", "password", "dbname"},
    PageSize: 25,
})

// The same method accepts structured filters
filtered, err := client.Breach.Search("", &oathnet.BreachV2SearchOptions{
    Filter: map[string]interface{}{
        "and": []map[string]interface{}{
            {"field": "email_domain", "operator": "eq", "value": "example.com"},
            {"field": "country", "operator": "eq", "value": "US"},
        },
    },
    Fields: []string{"email", "username", "dbname"},
})

// Use autocomplete before building a narrow query or scanner QueryConfig
values, err := client.Breach.Autocomplete(&oathnet.BreachV2AutocompleteOptions{
    Field:       "email_domain",
    Query:       "example",
    Limit:       10,
    IncludeInfo: true,
})
dbnames, err := client.Breach.AutocompleteDBNames(&oathnet.BreachV2AutocompleteDBNamesOptions{
    Query: "link",
    Limit: 10,
})
fieldCoverage, err := client.Breach.AutocompleteFields(&oathnet.BreachV2AutocompleteFieldsOptions{
    Field: "discord_id",
    Limit: 10,
})

V2 Stealer Search

// Basic search
result, err := client.Stealer.Search("user@example.com", nil)

// Advanced filtering
opts := &oathnet.StealerSearchOptions{
    Domains:   []string{"google.com", "facebook.com"},
    HasLogID:  true,
    PageSize:  50,
}
result, err := client.Stealer.Search("user@example.com", opts)

// Access items
for _, item := range result.Data.Items {
    fmt.Printf("URL: %s\n", item.URL)
    fmt.Printf("Username: %s\n", item.Username)
    fmt.Printf("Password: %s\n", item.Password)
    fmt.Printf("Log ID: %s\n", item.LogID)
}

// Pagination
if result.Data.NextCursor != "" {
    nextOpts := &oathnet.StealerSearchOptions{
        Cursor: result.Data.NextCursor,
    }
    nextPage, _ := client.Stealer.Search("user@example.com", nextOpts)
}

// Subdomain extraction with optional live checks and session reuse
alive := true
subResult, err := client.Stealer.Subdomain("example.com", "", &oathnet.SubdomainOptions{
    Query: "mail",
    Alive: &alive,
    SearchID: "sess_0123456789abcdef",
})
fmt.Printf("Found %d subdomains\n", subResult.Data.Count)
for _, sub := range subResult.Data.Subdomains {
    fmt.Printf("  %v\n", sub)
}

Investigation And Phonebook

Use investigation when one query should fan out across credentials, victims, files, properties, and related credentials. Use phonebook when you want domain host and email intelligence before deciding which pivots to run next.

// Structured filters use the same search method
filtered, err := client.Stealer.Search("", &oathnet.StealerSearchOptions{
    Filter: map[string]interface{}{
        "field": "domain", "operator": "eq", "value": "example.com",
    },
    Fields: []string{"log_id", "url_str", "username"},
    View:   "enriched",
})

investigation, err := client.Stealer.InvestigationSearch("example.com", &oathnet.InvestigationSearchOptions{
    Scope:    "all",
    Include:  []string{"credentials", "victims", "files"},
    PageSize: 25,
    View:     "enriched",
})

investigationFromBody, err := client.Stealer.InvestigationSearch("example.com", &oathnet.InvestigationSearchOptions{
    Scope:   "all",
    Include: []string{"credentials"},
    Filters: oathnet.V2InvestigationSectionFilters{
        "credentials": map[string]interface{}{"domain": "example.com"},
    },
})

if investigation.Data != nil &&
    investigation.Data.Sections != nil &&
    investigation.Data.Sections.Credentials != nil {
    for _, item := range investigation.Data.Sections.Credentials.Items {
        fmt.Println(item.LogID, item.Username)
    }
}

phonebook, err := client.Stealer.Phonebook("example.com", &oathnet.PhonebookOptions{
    Alive: true,
})
fmt.Println(len(phonebook.Data.Subdomains))

Victims

Victim search returns stealer-log profiles. Use the LogID from a selected victim to inspect its file tree, fetch one raw file, or download the whole archive. Passing the SearchID from InitSession keeps these follow-up requests tied to the same search workflow.

// Search victims
result, err := client.Victims.Search("user@example.com", nil)

for _, victim := range result.Data.Items {
    fmt.Printf("Log ID: %s\n", victim.LogID)
    fmt.Printf("Users: %v\n", victim.DeviceUsers)
    fmt.Printf("Documents: %d\n", victim.TotalDocs)
}

// Use the same method when the pivot comes from an AI/manual structured filter
victims, err := client.Victims.Search("", &oathnet.VictimsSearchOptions{
    Filter: map[string]interface{}{
        "field": "service", "operator": "eq", "value": "discord",
    },
    View: "enriched",
})

// Search victim properties globally, then inspect one selected log
excludeCookieEvidence := true
properties, err := client.Victims.SearchVictimProperties(&oathnet.VictimPropertiesSearchOptions{
    Query:                 "example.com",
    Service:               "discord",
    Confidence:            []string{"high"},
    ExcludeCookieEvidence: &excludeCookieEvidence,
})
propertiesFromBody, err := client.Victims.SearchVictimProperties(&oathnet.VictimPropertiesSearchOptions{
    Query:      "example.com",
    Service:    "discord",
    Confidence: []string{"high", "medium"},
})
fmt.Println(len(properties.Data.Items), len(propertiesFromBody.Data.Items))

details, err := client.Victims.GetProperties("log_id_here", &oathnet.VictimPropertiesSearchOptions{
    Service: "discord",
})
fmt.Println(len(details.Data.Items))

summary, err := client.Victims.GetSummary("log_id_here", nil)
cookies, err := client.Victims.GetCookies("log_id_here", &oathnet.VictimCookieInventoryOptions{
    Domain: "example.com",
    Status: "active",
})

// Raw cookie-domain inspection returns copyable text
cookieText, err := client.Victims.InspectCookieDomain("log_id_here", &oathnet.VictimCookieDomainOptions{
    Domain: "example.com",
})
fmt.Printf("Cookie export characters: %d\n", len(cookieText.CopyText))

// Get the manifest (file tree) for the selected log
searchID := "sess_0123456789abcdef"
logID := "log_id_here"
manifest, err := client.Victims.GetManifest(logID, &oathnet.VictimRawOptions{
    SearchID: searchID,
})
fmt.Printf("Root: %s\n", manifest.VictimTree.Name)

for _, child := range manifest.VictimTree.Children {
    fmt.Printf("  %s (%s)\n", child.Name, child.Type)
}

// Get one raw file from the manifest as bytes
file, err := client.Victims.GetFile(
    logID,
    "Browser Passwords/file 1.txt",
    &oathnet.VictimRawOptions{SearchID: searchID},
)
fmt.Printf("Downloaded file bytes: %d\n", len(file))

// Download the full victim archive as ZIP bytes
archive, err := client.Victims.DownloadArchiveBytes(logID, &oathnet.VictimRawOptions{
    SearchID: searchID,
})
if err == nil {
    os.WriteFile("./victim_archive.zip", archive, 0644)
}

File Search

File search runs an asynchronous scan across selected stealer-log files. Use metadata search first when you only need file names and IDs. Create a file-search job when you need to scan file contents with a literal, regex, or wildcard expression.

// Search victim file metadata before fetching any file bytes
files, err := client.Victims.SearchFilesMetadata(&oathnet.FileMetadataSearchOptions{
    Query:    "cookies",
    Kind:     "cookies",
    PageSize: 25,
})
for _, file := range files.Data.Items {
    fmt.Println(file.LogID, file.FileID, file.Path)
}

// Create a file search job
result, err := client.FileSearch.Create("password", &oathnet.FileSearchCreateOptions{
    LogIDs:     []string{"log_id_1", "log_id_2"},
    SearchMode: "literal",  // literal, regex, or wildcard
})
jobID := result.Data.JobID
fmt.Printf("Job ID: %s\n", jobID)

// Check job status
status, err := client.FileSearch.GetStatus(jobID)
fmt.Printf("Status: %s\n", status.Data.Status)
if status.Data.Summary != nil {
    fmt.Printf("Files scanned: %d\n", status.Data.Summary.FilesScanned)
    fmt.Printf("Matches: %d\n", status.Data.Summary.Matches)
}

// Wait for completion and get results
searchResult, err := client.FileSearch.Search("password", &oathnet.FileSearchCreateOptions{
    LogIDs:     []string{"log_id_1", "log_id_2"},
    SearchMode: "literal",
}, 300*time.Second)

for _, match := range searchResult.Data.Matches {
    fmt.Printf("File: %s\n", match.FileName)
    fmt.Printf("Log ID: %s\n", match.LogID)
    fmt.Printf("Match: %s\n", match.MatchText)
}

Exports

Exports are asynchronous jobs for large result sets. Create a job with the service and structured QueryConfig you want, poll the job status, then download the completed file. Use docs for credential-style stealer exports, victims for victim/profile exports, and breach for breach-record exports.

// List recent export jobs before creating a duplicate
exports, err := client.Exports.ListExportsV2(1, 20)
for _, job := range exports.Results {
    fmt.Println(job.JobID, job.Status)
}

// Create an export job from a structured breach query
result, err := client.Exports.CreateExportV2("breach", &oathnet.ExportCreateOptions{
    Service: "breach",
    Limit:   100,
    Format:  "jsonl", // json, jsonl, csv, txt, or html
    Fields:  []string{"email", "password", "dbname"},
    QueryConfig: map[string]interface{}{
        "filter": map[string]interface{}{
            "field":    "email_domain",
            "operator": "eq",
            "value":    "example.com",
        },
    },
})
jobID := result.Data.JobID
fmt.Printf("Export Job ID: %s\n", jobID)

// Check export status
status, err := client.Exports.GetExportV2(jobID)
fmt.Printf("Status: %s\n", status.Data.Status)
if status.Data.Progress != nil {
    fmt.Printf("Progress: %.1f%%\n", status.Data.Progress.Percent)
}

// Wait for completion
completed, err := client.Exports.WaitForCompletion(jobID, 2*time.Second, 600*time.Second)
if completed.Data.Status == "completed" {
    // Download the export file
    exportBytes, err := client.Exports.DownloadExportV2(jobID)
    if err == nil {
        os.WriteFile("./export.jsonl", exportBytes, 0644)
    }
}

Bulk Search

Bulk search is for many input terms or a saved structured filter that should run as one background job. Create the job, poll it, and download the result file when it completes.

job, err := client.Bulk.Create(
    []string{"alice@example.com", "bob@example.com"},
    "breach",
    &oathnet.BulkCreateOptions{
        Format: "jsonl",
        QueryConfig: oathnet.BulkSearchQueryConfig{
            "filter": map[string]interface{}{
                "field": "email_domain", "operator": "eq", "value": "example.com",
            },
        },
        Fields: []string{"email", "password", "dbname"},
    },
)
jobID := job.Data.JobID

status, err := client.Bulk.GetStatus(jobID)

jobs, err := client.Bulk.List(1, 20)
for _, item := range jobs.Results {
    fmt.Println(item.JobID, item.Status)
}

completed, err := client.Bulk.WaitForCompletion(jobID, 5*time.Second, 10*time.Minute)
if completed.Data.Status == "completed" {
    err = client.Bulk.Download(jobID, "./bulk-results.jsonl")
}

Scanners

Scanners monitor newly indexed breach or stealer data and send notifications. Use regular search endpoints for historical investigation; scanners only watch new data after their baseline.

// Check scanner quota before creating a new monitor
quota, err := client.Scanners.GetQuota()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Remaining scanners: %d\n", quota.Remaining)

queryConfig := oathnet.ScannerQueryConfig{
    "filter": map[string]interface{}{
        "and": []map[string]interface{}{
            {"field": "email_domain", "operator": "eq", "value": "example.com"},
            {"field": "dbname", "operator": "in", "value": []string{"twitter.com", "linkedin.com"}},
        },
    },
}

// Validate webhook or Discord delivery before saving the scanner.
// A 200 response can still have Success=false when the remote endpoint rejects
// the test delivery, so inspect the returned object.
test, err := client.Scanners.TestDraftDelivery(oathnet.ScannerDraftTestRequest{
    ScannerType:         "breach",
    QueryConfig:         queryConfig,
    NotificationType:    "webhook",
    WebhookURL:          "https://alerts.example.com/oathnet",
    WebhookSecurityMode: "signed_json",
})
if err != nil {
    log.Fatal(err)
}
if !test.Success {
    fmt.Printf("Delivery test failed: %s\n", test.Message)
}

notifyOnZero := false
scanner, err := client.Scanners.Create(oathnet.ScannerCreateRequest{
    Name:                "Example breach monitor",
    ScannerType:         "breach",
    QueryConfig:         queryConfig,
    NotificationType:    "webhook",
    WebhookURL:          "https://alerts.example.com/oathnet",
    WebhookSecurityMode: "signed_json",
    NotifyOnZeroResults: &notifyOnZero,
})
if err != nil {
    log.Fatal(err)
}

security, err := client.Scanners.GetWebhookSecurity(scanner.UID)
if err != nil {
    log.Fatal(err)
}
if security.Data != nil {
    fmt.Println(security.Data.VerificationMethod)
}

scanner, err = client.Scanners.Update(scanner.UID, oathnet.ScannerUpdateRequest{
    Name: "Example breach monitor v2",
})
if err != nil {
    log.Fatal(err)
}

_, err = client.Scanners.Trigger(scanner.UID)
if err != nil {
    log.Fatal(err)
}

runs, err := client.Scanners.ListRuns(scanner.UID, &oathnet.ScannerRunsOptions{
    Limit: 10,
})
if err != nil {
    log.Fatal(err)
}
for _, run := range runs {
    fmt.Printf("%s: %s (%d results)\n", run.UID, run.Status, run.ResultsCount)
}

_, _ = client.Scanners.Pause(scanner.UID)
_, _ = client.Scanners.Resume(scanner.UID)

Use client.Scanners.Delete(scannerUID) when you want to permanently remove a scanner and its run history. Webhook receivers should verify signed_json or signed_encrypted deliveries against the exact raw request body before parsing JSON. See Scanners for the HMAC and encryption contract.

OSINT Lookups

// IP Info
ipInfo, err := client.OSINT.IPInfo("8.8.8.8")
fmt.Printf("Location: %s, %s\n", ipInfo.Data.City, ipInfo.Data.Country)
fmt.Printf("ISP: %s\n", ipInfo.Data.ISP)
fmt.Printf("Proxy: %v\n", ipInfo.Data.Proxy)

// Steam
steam, err := client.OSINT.Steam("76561198012345678")
fmt.Printf("Username: %s\n", steam.Data.Username)
fmt.Printf("Avatar: %s\n", steam.Data.Avatar)

// Xbox
xbox, err := client.OSINT.Xbox("GamerTag123")
fmt.Printf("Username: %s\n", xbox.Data.Username)
fmt.Printf("Avatar: %s\n", xbox.Data.Avatar)

// Discord User Info
discord, err := client.OSINT.DiscordUserinfo("123456789012345678")
fmt.Printf("Username: %s\n", discord.Data.Username)
fmt.Printf("Global Name: %s\n", discord.Data.GlobalName)
fmt.Printf("Created: %s\n", discord.Data.CreationDate)

// Discord Username History
history, err := client.OSINT.DiscordUsernameHistory("123456789012345678")
for _, entry := range history.Data.History {
    if len(entry.Name) > 0 && len(entry.Time) > 0 {
        fmt.Printf("%s at %s\n", entry.Name[0], entry.Time[0])
    }
}

// Roblox User Info
roblox, err := client.OSINT.RobloxUserinfo(oathnet.RobloxUserinfoOptions{
    UserID: "123456789",
})
// Or by username:
roblox2, _ := client.OSINT.RobloxUserinfo(oathnet.RobloxUserinfoOptions{
    Username: "PlayerName",
})
fmt.Printf("Username: %s\n", roblox.Data.Username)
fmt.Printf("Display Name: %s\n", roblox.Data.DisplayName)

// Holehe - Email account detection
holehe, err := client.OSINT.Holehe("user@example.com")
fmt.Printf("Found on %d services:\n", len(holehe.Data.Domains))
for _, domain := range holehe.Data.Domains {
    fmt.Printf("  %s\n", domain)
}

// GHunt - Google account lookup
ghunt, err := client.OSINT.GHunt("user@gmail.com")
if ghunt.Data != nil && ghunt.Data.Data != nil && ghunt.Data.Data.Profile != nil {
    fmt.Printf("Name: %s\n", ghunt.Data.Data.Profile.Name)
}

// Subdomain extraction
alive := true
subdomains, err := client.OSINT.ExtractSubdomain("example.com", &alive)
for _, sub := range subdomains.Data.Subdomains {
    fmt.Println(sub)
}

// Minecraft username history
mc, err := client.OSINT.MinecraftHistory("PlayerName")
for _, entry := range mc.Data.History {
    fmt.Printf("%s - %s\n", entry.Username, entry.ChangedAt)
}

Utility Service

// Database name autocomplete
dbnames, err := client.Utility.DBNameAutocomplete("link")
for _, name := range dbnames {
    fmt.Println(name)  // linkedin_2012, linkedin_2021, etc.
}

Error Handling

import "github.com/oathnet/oathnet-go/pkg/oathnet"

result, err := client.Search.Breach("user@example.com", nil)
if err != nil {
    switch e := err.(type) {
    case *oathnet.AuthenticationError:
        fmt.Println("Invalid API key")
    case *oathnet.QuotaExceededError:
        fmt.Println("Daily quota exceeded")
    case *oathnet.RateLimitError:
        fmt.Printf("Rate limited. Retry after %d seconds\n", e.RetryAfter)
    case *oathnet.NotFoundError:
        fmt.Println("Resource not found")
    case *oathnet.ValidationError:
        fmt.Printf("Invalid input: %s\n", e.Message)
    case *oathnet.OathNetError:
        fmt.Printf("API error: %s\n", e.Message)
    default:
        fmt.Printf("Unknown error: %v\n", err)
    }
    return
}

Timeout Configuration

client, err := oathnet.NewClient("your-api-key",
    oathnet.WithTimeout(10 * time.Second),
)
result, err := client.Search.Breach("user@example.com", nil)

Configuration Options

import (
    "time"
    "github.com/oathnet/oathnet-go/pkg/oathnet"
)

client, err := oathnet.NewClient("your-api-key",
    oathnet.WithBaseURL("https://oathnet.org/api"),
    oathnet.WithTimeout(60 * time.Second),
)

CLI Tool

Next: CLI documentation

JavaScript SDK

Previous: JavaScript SDK

​Installation

​Quick Start

​Authentication

​Search Service

​Breach Search

​Initialize Session

​AI Filters

​V2 Breach Search

​V2 Stealer Search

​Investigation And Phonebook

​Victims

​File Search

​Exports

​Bulk Search

​Scanners

​OSINT Lookups

​Utility Service

​Error Handling

​Timeout Configuration

​Configuration Options