oathnet 1.0.2

Official Python SDK and CLI for OathNet API

OathNet Python SDK

Official Python SDK and CLI for the OathNet API.

Installation

pip install oathnet

Or install from source:

pip install -e .

Quick Start

SDK Usage

from oathnet import OathNetClient

# Initialize client
client = OathNetClient("your-api-key")

# Search breach database
results = client.search.breach("[e-mail]")
print(f"Found {results.data.results_found} results")

for result in results.data.results:
    print(f"  {result.email} from {result.dbname}")

# OSINT lookups
discord_user = client.osint.discord_userinfo("300760994454437890")
print(f"Discord user: {discord_user.data.username}")

ip_info = client.osint.ip_info("174.235.65.156")
print(f"IP location: {ip_info.data.city}, {ip_info.data.country}")

CLI Usage

# Set API key
export OATHNET_API_KEY="your-api-key"

# Search breach database
oathnet search breach -q "[e-mail]"

# OSINT lookups
oathnet osint discord user 300760994454437890
oathnet osint ip 174.235.65.156
oathnet osint steam 1100001586a2b38

# Output as JSON
oathnet --format json search breach -q "winterfox"

Features

Search Services

• Breach Search: Search leaked credentials across 50B+ records
• Stealer Search: Search stealer log databases
• Search Sessions: Optimize quota with grouped lookups

V2 Services

• V2 Stealer: Enhanced stealer search with filtering
• V2 Victims: Search victim profiles with device info
• V2 File Search: Regex search within victim files
• V2 Exports: Export results to CSV/JSONL

OSINT Lookups

• Discord (user info, username history, linked Roblox)
• Steam profiles
• Xbox Live profiles
• Roblox user info
• IP geolocation
• Email existence (Holehe)
• Google accounts (GHunt)
• Subdomain extraction
• Minecraft username history

SDK Reference

Client

from oathnet import OathNetClient

client = OathNetClient(
    api_key="your-api-key",
    base_url="https://oathnet.org/api",  # Optional
    timeout=30.0  # Optional
)

Services

Search

# Initialize search session
session = client.search.init_session("query")

# Search breach database
results = client.search.breach("query", cursor=None, dbnames="linkedin")

# Search stealer database
results = client.search.stealer("query")

# Paginate through all results
for result in client.search.breach_paginate("query"):
    print(result)

OSINT

# IP lookup
info = client.osint.ip_info("8.8.8.8")

# Steam profile
profile = client.osint.steam("steam_id")

# Xbox profile
profile = client.osint.xbox("gamertag")

# Discord user
user = client.osint.discord_userinfo("discord_id")

# Discord username history
history = client.osint.discord_username_history("discord_id")

# Discord to Roblox
mapping = client.osint.discord_to_roblox("discord_id")

# Roblox user
user = client.osint.roblox_userinfo(username="username")

# Holehe email check
result = client.osint.holehe("[e-mail]")

# Subdomain extraction
result = client.osint.extract_subdomain("example.com")

V2 Stealer

# Enhanced search with filters
results = client.stealer.search(
    q="query",
    domain=["facebook.com"],
    has_log_id=True
)

# Extract subdomains from stealer data
subs = client.stealer.subdomain("example.com")

V2 Victims

# Search victim profiles
victims = client.victims.search(
    q="query",
    email=["[e-mail]"]
)

# Get file manifest
manifest = client.victims.get_manifest("log_id")

# Download file
content = client.victims.get_file("log_id", "file_id")

# Download archive
client.victims.download_archive("log_id", "output.zip")

File Search (Async)

# Create search job
job = client.file_search.create("password", search_mode="regex")

# Wait for results
result = client.file_search.wait_for_completion(job.data.job_id)

# Or use convenience method
result = client.file_search.search("api_key", search_mode="literal")

Exports (Async)

# Create export
job = client.exports.create(
    export_type="docs",
    format="csv",
    search={"query": "example.com"}
)

# Wait and download
path = client.exports.wait_and_download(job.data.job_id, "export.csv")

Error Handling

from oathnet import OathNetClient
from oathnet.exceptions import (
    AuthenticationError,
    NotFoundError,
    QuotaExceededError,
    ValidationError
)

try:
    results = client.search.breach("query")
except AuthenticationError:
    print("Invalid API key")
except QuotaExceededError as e:
    print(f"Quota exceeded: {e.used_today}/{e.daily_limit}")
except NotFoundError:
    print("Resource not found")
except ValidationError as e:
    print(f"Invalid parameters: {e.errors}")

CLI Reference

# Global options
oathnet --api-key KEY --format json|table|raw COMMAND

# Search commands
oathnet search breach -q "query" [--cursor] [--dbnames]
oathnet search stealer -q "query"
oathnet search init -q "query"

# Stealer V2
oathnet stealer search -q "query" [--domain] [--wildcard]
oathnet stealer subdomain -d "domain.com"

# Victims V2
oathnet victims search -q "query" [--email] [--ip]
oathnet victims manifest LOG_ID
oathnet victims file LOG_ID FILE_ID
oathnet victims archive LOG_ID

# OSINT
oathnet osint ip IP_ADDRESS
oathnet osint steam STEAM_ID
oathnet osint xbox GAMERTAG
oathnet osint discord user DISCORD_ID
oathnet osint discord history DISCORD_ID
oathnet osint discord roblox DISCORD_ID
oathnet osint roblox [--user-id ID | --username NAME]
oathnet osint holehe EMAIL
oathnet osint ghunt EMAIL
oathnet osint subdomain DOMAIN
oathnet osint minecraft USERNAME

# Utility
oathnet util dbnames -q "linked"

Configuration

API key can be set via:

1. CLI flag: --api-key KEY
2. Environment variable: OATHNET_API_KEY

Examples

The examples/ directory contains comprehensive examples for common use cases:

Example	Description
basic_usage.py	Client initialization and simple search
breach_search.py	Breach search with filters and pagination
stealer_search.py	V2 stealer search with log ID access
victims_search.py	Victim profiles, manifests, and file access
file_search.py	Async file search within victim logs
osint_lookups.py	All 12 OSINT methods demonstrated
exports.py	Async export to CSV/JSONL
error_handling.py	Exception patterns and retry logic
pagination.py	Cursor-based pagination patterns

Run an example:

export OATHNET_API_KEY="your-api-key"
python examples/basic_usage.py

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (requires API key)
export OATHNET_API_KEY="your-api-key"
pytest tests/ -v

# Run specific test file
pytest tests/test_sdk.py -v

# Run specific test class
pytest tests/test_sdk.py::TestOSINTService -v

# Run with coverage
pytest tests/ -v --cov=oathnet --cov-report=html

# Run only fast tests (skip slow integration tests)
pytest tests/ -v -m "not slow"

Test Structure

tests/
  conftest.py              # Fixtures (API key from env)
  test_sdk.py              # Core SDK tests
  test_file_search_service.py  # File search tests
  test_exports_service.py  # Export tests

License

MIT License - See LICENSE file for details.

Support

• Documentation: https://docs.oathnet.org
• Discord: https://discord.gg/DCjnk9TAMK
• Email: [e-mail]