# C# SDK

The official .NET client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

> **Note**: The package is on [NuGet](https://www.nuget.org/packages/Synthient.Client). There is no hosted API reference, but every public type and member carries XML documentation that your editor shows. These pages cover the same surface with examples. The source and runnable programs are at [github.com/synthient/synthient-dotnet](https://github.com/synthient/synthient-dotnet), in `examples/`.

## Getting started

### 1. Install

```bash
dotnet add package Synthient.Client
```

Requires .NET 8 or later. Every type is in the `Synthient` namespace. `Synthient.Client` is compatible with Native AOT. The [gRPC schema](https://docs.synthient.com/sdks/csharp/grpc-schema) fetcher is a separate package, `Synthient.Client.GrpcSchema`, in the same namespace.

### 2. Make your first lookup

This program creates a client and looks up one address. Each lookup costs one credit.

```csharp
using System.Net;
using Synthient;

using var client = new SynthientClient();

var info = await client.LookupIPAsync(IPAddress.Parse("8.8.8.8"));
if (info.Network is not null)
{
    Console.WriteLine($"{info.Network.Isp} {info.Network.Type}");
}
if (info.Intelligence is not null)
{
    Console.WriteLine($"{info.Intelligence.RiskScore} {string.Join(", ", info.Intelligence.Categories)}");
}
```

`new SynthientClient()` reads the API key from the `SYNTHIENT_API_KEY` environment variable. `IPInfo.Network`, `IPInfo.Location`, and `IPInfo.Intelligence` are `null` when the API has no data for that section, so check them before reading their fields.

### 3. Check your credits

`GetAccountAsync` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```csharp
var account = await client.GetAccountAsync();
Console.WriteLine($"{account.Email} {account.Organization.Name} {string.Join(", ", account.Scopes)}");
Console.WriteLine($"{account.LookupQuota.Credits} credits, resetting in {account.LookupQuota.ResetsIn}");
```

### 4. Handle errors

A call that fails with an HTTP error status throws an `ApiException`. A call that gets no response throws an `ApiConnectionException`, or its subclass `ApiTimeoutException` when `SynthientClientOptions.Timeout` or the default handler's 10-second connect timeout elapses.

```csharp
try
{
    await client.LookupIPAsync(IPAddress.Parse("8.8.8.8"));
}
catch (ApiException e) when (e.StatusCode == 402)
{
    Console.WriteLine("out of lookup credits");
}
catch (ApiException e) when (e.StatusCode == 429 && e.RetryAfter is { } retryAfter)
{
    Console.WriteLine($"rate limited, retry after {retryAfter}");
}
catch (ApiException e) when (e.StatusCode == 429)
{
    Console.WriteLine("monthly request budget spent");
}
catch (ApiException e)
{
    Console.WriteLine($"request {e.RequestId} failed: {e.Detail ?? e.Title}");
}
catch (ApiConnectionException e)
{
    Console.WriteLine($"no response: {e.Message}");
}
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/csharp/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/csharp/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/csharp/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/csharp/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/csharp/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/csharp/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.