C# SDK
The official .NET client for the Synthient API: IP lookups, account details, real-time feed streams, and Parquet exports.
Getting started
1. Install
dotnet add package Synthient.Client
Or as a PackageReference. The second reference is only needed for the gRPC schema fetcher:
<ItemGroup>
<PackageReference Include="Synthient.Client" Version="1.0.0" />
<PackageReference Include="Synthient.Client.GrpcSchema" Version="1.0.0" />
</ItemGroup>
Requires .NET 8 or later. Every type is in the Synthient namespace. Synthient.Client is compatible with Native AOT. It targets net8.0 and net10.0, depends only on System.Text.Json on net8.0, and supports trimming. The gRPC schema fetcher is a separate package, Synthient.Client.GrpcSchema, in the same namespace. Synthient.Client and Synthient.Client.GrpcSchema are released together with the same version.
2. Make your first lookup
Each lookup costs one credit.
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.
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.
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: create and configure the client, and read the metadata of every API response.
- Lookups: look up IP addresses and check your account and the API's health.
- Feeds: stream each feed's real-time events and download its hourly and daily Parquet exports.
- Errors and retries: how failed requests are reported, and which requests are retried.
- Types: the fields of every response and event type, and the enumerations they use.
- gRPC schema: fetch the protobuf schema of the Synthient gRPC API.