XposedOrNot

Official .NET SDK for the XposedOrNot API
Check if your email or password has been exposed in data breaches

---

Note: This SDK uses the free public API from XposedOrNot.com - a free service to check if your email has been compromised in data breaches. Visit the XposedOrNot website to learn more about the service and check your email manually.

---

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• API Reference
  • CheckEmailAsync
  • GetBreachesAsync
  • GetBreachAnalyticsAsync
  • CheckPasswordAsync
• Error Handling
• Rate Limits
• Configuration
• Contributing
• License
• Links

---

Features

• Simple API - Easy-to-use async methods for checking email and password breaches
• Free and Plus Support - Works with both the free API and the Plus API (with API key)
• Password Safety - Passwords are hashed locally with Keccak-512; only a prefix is sent (k-anonymity)
• Detailed Analytics - Get breach details, summaries, metrics, and paste exposures
• Error Handling - Custom exception classes for different failure scenarios
• Configurable - Timeout, retries, custom headers, and IHttpClientFactory support
• Multi-target - Supports .NET 6.0 and .NET 8.0

Installation

dotnet add package XposedOrNot

Or add the PackageReference directly to your .csproj:

<PackageReference Include="XposedOrNot" Version="1.0.0" />

Requirements

• .NET 6.0 or .NET 8.0

Quick Start

using XposedOrNot;

// Free API (no key required)
using var client = new XposedOrNotClient();

// Check if an email has been breached
var result = await client.Email.CheckEmailAsync("test@example.com");

if (result.Found)
{
    Console.WriteLine($"Email found in breaches!");
}
else
{
    Console.WriteLine("Good news! Email not found in any known breaches.");
}

// Check password exposure (hashed locally, only prefix sent)
var passResult = await client.Password.CheckPasswordAsync("mypassword");

// Get all known breaches
var breaches = await client.Breaches.GetBreachesAsync();

// Get breach analytics for an email
var analytics = await client.Breaches.GetBreachAnalyticsAsync("test@example.com");

Plus API (with API key)

var options = new XposedOrNotOptions { ApiKey = "your-api-key" };
using var client = new XposedOrNotClient(options);

// Returns detailed breach information when an API key is configured
var detailed = await client.Email.CheckEmailAsync("test@example.com");

API Reference

Constructor

// Default options (free API)
using var client = new XposedOrNotClient();

// Custom options
using var client = new XposedOrNotClient(options);

// With IHttpClientFactory (see Configuration section)
using var client = new XposedOrNotClient(httpClient, options);

Methods

CheckEmailAsync

Check if an email address has been exposed in data breaches. Automatically uses the Plus API when an API key is configured, otherwise uses the free API.

var result = await client.Email.CheckEmailAsync("user@example.com");

// Check which API was used
if (result.IsDetailed)
{
    var detailed = result.DetailedResponse;
}
else
{
    var free = result.FreeResponse;
}

Parameter	Type	Description
email	string	The email address to check
cancellationToken	CancellationToken	Optional cancellation token

GetBreachesAsync

Get a list of all known data breaches, optionally filtered by domain.

// Get all breaches
var breaches = await client.Breaches.GetBreachesAsync();

// Filter by domain
var filtered = await client.Breaches.GetBreachesAsync(domain: "adobe.com");

Parameter	Type	Description
domain	string?	Optional domain to filter breaches by
cancellationToken	CancellationToken	Optional cancellation token

Returns: List<Breach> with properties such as BreachID, BreachedDate, Domain, Industry, ExposedData, ExposedRecords, and more.

GetBreachAnalyticsAsync

Get comprehensive breach analytics for an email address, including breach details, summaries, metrics, and paste exposures.

var analytics = await client.Breaches.GetBreachAnalyticsAsync("user@example.com");

Console.WriteLine($"Exposed breaches: {analytics.ExposedBreaches}");
Console.WriteLine($"Breach summary: {analytics.BreachesSummary}");
Console.WriteLine($"Breach metrics: {analytics.BreachMetrics}");
Console.WriteLine($"Paste exposures: {analytics.ExposedPastes}");

Parameter	Type	Description
email	string	The email address to analyze
cancellationToken	CancellationToken	Optional cancellation token

CheckPasswordAsync

Check if a password has been exposed in data breaches. The password is hashed locally using Keccak-512 and only the first 10 hex characters of the hash are sent to the API, preserving your privacy through k-anonymity.

var result = await client.Password.CheckPasswordAsync("mypassword");

Parameter	Type	Description
password	string	The plaintext password to check
cancellationToken	CancellationToken	Optional cancellation token

Error Handling

The library provides custom exception classes for different scenarios:

using XposedOrNot;
using XposedOrNot.Exceptions;

using var client = new XposedOrNotClient();

try
{
    var result = await client.Email.CheckEmailAsync("invalid-email");
}
catch (ValidationException ex)
{
    Console.Error.WriteLine($"Invalid input: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.Error.WriteLine($"Rate limited: {ex.Message}");
}
catch (NetworkException ex)
{
    Console.Error.WriteLine($"Network error: {ex.Message}");
}
catch (NotFoundException ex)
{
    Console.Error.WriteLine($"Not found: {ex.Message}");
}
catch (AuthenticationException ex)
{
    Console.Error.WriteLine($"Authentication failed: {ex.Message}");
}
catch (XposedOrNotException ex)
{
    Console.Error.WriteLine($"API error: {ex.Message}");
}

Exception Types

Exception Class	Description
XposedOrNotException	Base exception class for all API errors
ValidationException	Invalid input (e.g., malformed email, empty password)
RateLimitException	API rate limit exceeded after all retry attempts
NotFoundException	Requested resource not found
AuthenticationException	Authentication failed (invalid API key)
NetworkException	Network connectivity issues
ApiException	General API or deserialization error

Rate Limits

The XposedOrNot API has the following rate limits:

• 2 requests per second
• 50-100 requests per hour
• 100-1000 requests per day

The client includes automatic retry with exponential backoff for rate-limited (429) responses, configurable via MaxRetries in XposedOrNotOptions.

Configuration

XposedOrNotOptions

var options = new XposedOrNotOptions
{
    BaseUrl = "https://api.xposedornot.com",           // Free API base URL
    PlusBaseUrl = "https://plus-api.xposedornot.com",  // Plus API base URL
    PasswordsBaseUrl = "https://passwords.xposedornot.com/api", // Password API base URL
    Timeout = TimeSpan.FromSeconds(30),                // HTTP request timeout
    MaxRetries = 3,                                    // Retry attempts on 429 responses
    ApiKey = "your-api-key",                           // Plus API key (optional)
    CustomHeaders = new Dictionary<string, string>     // Extra headers (optional)
    {
        ["X-Custom-Header"] = "value"
    }
};

using var client = new XposedOrNotClient(options);

Option	Type	Default	Description
BaseUrl	string	https://api.xposedornot.com	Free API base URL
PlusBaseUrl	string	https://plus-api.xposedornot.com	Plus API base URL
PasswordsBaseUrl	string	https://passwords.xposedornot.com/api	Password API base URL
Timeout	TimeSpan	30 seconds	HTTP request timeout
MaxRetries	int	3	Retry attempts on rate-limited responses
ApiKey	string?	null	API key for Plus API access
CustomHeaders	Dictionary<string, string>	{}	Custom headers for all requests

Using IHttpClientFactory

For ASP.NET Core or long-running applications, use IHttpClientFactory to manage HttpClient lifetimes:

// In Startup.cs or Program.cs
services.AddHttpClient("XposedOrNot");

// In your service
public class MyService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    public async Task CheckBreaches()
    {
        var httpClient = _httpClientFactory.CreateClient("XposedOrNot");
        var options = new XposedOrNotOptions();
        using var client = new XposedOrNotClient(httpClient, options);

        var result = await client.Email.CheckEmailAsync("user@example.com");
    }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/XposedOrNot/XposedOrNot-DotNet.git
cd XposedOrNot-DotNet

# Build
dotnet build

# Run tests
dotnet test

# Pack NuGet package
dotnet pack

License

MIT - see the LICENSE file for details.

Links

• XposedOrNot Website
• API Documentation
• NuGet Package
• GitHub Repository
• XposedOrNot API Repository

---

Made with care by XposedOrNot