:::note
**TL;DR**
- One NuGet package, `RoxyApi.Sdk`, ships today and covers Western astrology, Vedic kundli, panchang, tarot, numerology, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, and location across 164 endpoints under one API key.
- Install with `dotnet add package RoxyApi.Sdk`. Targets `net8.0` and `netstandard2.0`, so it runs on .NET 8+, .NET Framework 4.6.1+, Blazor, MAUI, and Unity. One runtime dependency, the MIT-licensed Kiota bundle from Microsoft.
- Geocode the birth city with `roxy.Location.Search` first, then feed `Latitude`, `Longitude`, and `Timezone` into every chart, kundli, panchang, dasha, or natal call.
- Build a multi-domain insight app this afternoon with the [astrology API](/products/astrology-api "production-ready astrology API with natal charts, transits, synastry, and daily horoscopes").
:::

The RoxyAPI .NET SDK ships on NuGet as `RoxyApi.Sdk`, the fourth typed client in the family after TypeScript, Python, and PHP. One install gives any ASP.NET Core, Blazor, MAUI, or Unity project the full surface: Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, and location, plus usage and language helpers. The client is generated from the live OpenAPI spec, so every response is a fully typed object your IDE autocompletes, and new endpoints appear the day they ship. This post is a hands-on tutorial: by the end you will have a small ASP.NET Core app calling multiple RoxyAPI domains and returning JSON ready for any frontend.

## What does the RoxyAPI .NET SDK cover, and why C#

`RoxyApi.Sdk` covers 164 endpoints across 12 insight domains under one API key, exposed as a strongly typed client in the `RoxyApi` namespace with `RoxyClient` as the entry point. C# runs a large share of enterprise backends, Unity games, and Blazor apps, and none of those stacks had a first-class typed insight client until now. The SDK is generated with Microsoft Kiota from the public OpenAPI specification, so the method tree mirrors the URL path exactly and the compiler catches a wrong field before you deploy. The only runtime dependency is `Microsoft.Kiota.Bundle`, MIT licensed and maintained by Microsoft.

| Accessor | Endpoints | What it covers |
|----------|----------:|----------------|
| `roxy.Astrology` | 33 | Western natal charts, transits, synastry, daily, weekly, monthly horoscopes |
| `roxy.VedicAstrology` | 43 | Kundli, panchang, dasha, dosha, KP system, navamsa, Guna Milan |
| `roxy.Numerology` | 20 | Life Path, Expression, Soul Urge, Personal Year, compatibility |
| `roxy.Tarot` | 10 | Daily card, Celtic Cross, three-card, yes / no, card catalog |
| `roxy.HumanDesign` | 12 | Full bodygraph, type, authority, profile, centers, channels, gates |
| `roxy.Crystals` | 12 | By zodiac, chakra, birthstone, free-text search |
| `roxy.Iching` | 9 | Cast a reading, 64 hexagrams, changing lines |
| `roxy.Biorhythm` | 6 | Daily, forecast, compatibility, critical days |
| `roxy.Forecast` | 5 | Cross-domain, significance-scored event timeline |
| `roxy.Dreams` | 5 | Symbol lookup, dream dictionary search |
| `roxy.AngelNumbers` | 4 | Sequence meanings, universal digit-root lookup |
| `roxy.Location` | 3 | City search and geocoding |

Ready to build with this? The [Vedic Astrology API](/products/vedic-astrology-api "production-ready Vedic Astrology API with kundli, panchang, dashas, and KP") and every other domain run under one key, every domain in every plan. [See pricing](/pricing "RoxyAPI pricing and plan tiers").

## How to install the .NET SDK and make your first call

Add the package with `dotnet add package RoxyApi.Sdk`, then construct one `RoxyClient` with your API key. The constructor sets the base URL (`https://roxyapi.com/api/v2`) and injects the auth header on every request, so application code never builds an `HttpClient` by hand. Read the key from configuration or an environment variable, never a literal. The daily horoscope is the simplest call in the catalog, no coordinates and no request body, just a lowercase sign on the path indexer.

```bash
dotnet add package RoxyApi.Sdk
```

```csharp
using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var horoscope = await roxy.Astrology.Horoscope["aries"].Daily.GetAsync();
Console.WriteLine(horoscope!.Overview);
Console.WriteLine($"Lucky number: {horoscope.LuckyNumber}, energy: {horoscope.EnergyRating}/10");
```

Running that against a live key today prints a real transit-driven reading:

```text
Saturn steadies Aries with quiet determination today. Structure creates freedom, and
the boundaries you set now protect what matters most. Rest and reflect.
Lucky number: 28, energy: 9/10
```

Every call is `async` and returns the typed response directly, or throws `RoxyError` on a 4xx or 5xx. There is no result-wrapper object to unpack. The success body is nullable because errors throw, so use `horoscope!.Overview` or a null check after handling errors.

## How to geocode a birth city and generate a Vedic kundli

Every chart, kundli, panchang, dasha, dosha, navamsa, KP, synastry, and natal endpoint needs `Latitude`, `Longitude`, and `Timezone`. Never ask a user to type coordinates. Call `roxy.Location.Search` first, take the first city, and pass its fields straight into the chart method. The `Timezone` field is a typed union, so wrap the IANA string with `new() { String = city.Timezone }` or a decimal offset with `new() { Double = 5.5 }`. The server resolves an IANA name to the DST-correct offset for the chart date, so a historical birth returns the right offset without caller-side date math.

```csharp
using RoxyApi;
using RoxyApi.Models;
using Microsoft.Kiota.Abstractions; // Date and Time structs

var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Mumbai");
var city = search!.Cities![0];

var kundli = await roxy.VedicAstrology.BirthChart.PostAsync(new()
{
    Date = new Date(1990, 1, 15),
    Time = new Time(14, 30, 0),
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});

foreach (var graha in kundli!.Leo!.Signs ?? [])
    Console.WriteLine($"{graha.Graha} in Leo, house {graha.House}: " +
        $"{graha.Nakshatra?.Name} pada {graha.Nakshatra?.Pada}");
```

The Vedic response is where the depth lives. Each sign accessor (`kundli.Leo`, `kundli.Aries`) carries a `Signs` list, and each entry exposes `Graha`, `House`, `IsRetrograde`, `Longitude`, and a `Nakshatra` object with `Name`, `Pada`, and `Lord`. The run above prints `Moon in Leo, house 4: Purva Phalguni pada 3` for that birth, pada-quarter precision straight off the typed object with no manual longitude math.

## How to combine domains in a single multi-insight call

Multi-domain readings are the unlock single-purpose APIs cannot match. Once the client is wired, a numerology Life Path, a daily tarot card, and a Western natal chart for the same user are three method calls on the same `roxy` instance. Because the three are independent, fire them together with `Task.WhenAll` so the whole profile resolves in one round trip of latency instead of three sequential ones. Each domain hangs off a property on the client, each method maps to one operationId in the spec, and each response is a typed object.

```csharp
var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Austin");
var city = search!.Cities![0];

var lifePathTask = roxy.Numerology.LifePath.PostAsync(new() { Year = 1990, Month = 1, Day = 15 });
var cardTask     = roxy.Tarot.Daily.PostAsync(new() { Seed = "user-42" });
var chartTask    = roxy.Astrology.NatalChart.PostAsync(new()
{
    Date = new Date(1990, 1, 15),
    Time = new Time(14, 30, 0),
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});
await Task.WhenAll(lifePathTask, cardTask, chartTask);

var lifePath = lifePathTask.Result;
var card = cardTask.Result;
var chart = chartTask.Result;

Console.WriteLine($"Life Path {lifePath!.Number}: {lifePath.Meaning?.Title}");
Console.WriteLine($"Card: {card!.Card!.Name}{(card.Card.Reversed == true ? " (reversed)" : "")}");
Console.WriteLine($"Ascendant: {chart!.Ascendant!.Sign}, element: {chart.Summary?.DominantElement}");
```

For that input the live API returns Life Path `8` titled "The Powerhouse", a natal `Ascendant` in Gemini, and a `Summary.DominantElement` of Earth. Nested fields are typed objects, not strings: `chart.Ascendant` has `Sign`, `Degree`, and `Longitude`, so drill in with `chart.Ascendant.Sign`. IntelliSense shows every field, and you rarely name a response type yourself, capture with `var` and let the compiler carry the shape.

## How to wire the SDK into ASP.NET Core with dependency injection

`RoxyClient` is thread-safe and built once per process, so register it as a singleton in the DI container and inject it into any minimal-API handler, controller, or `BackgroundService`. Read the key from `IConfiguration` (user secrets in development, environment variables in production) rather than a literal. The pattern below is a complete two-endpoint app: a daily horoscope by sign and a natal chart that geocodes the city server-side, with `RoxyError` mapped to the matching HTTP status.

```csharp
using RoxyApi;
using RoxyApi.Models;
using Microsoft.Kiota.Abstractions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(new RoxyClient(builder.Configuration["RoxyApi:Key"]
    ?? throw new InvalidOperationException("RoxyApi:Key is not configured.")));

var app = builder.Build();

app.MapGet("/api/horoscope/{sign}", async (string sign, RoxyClient roxy) =>
    Results.Ok(await roxy.Astrology.Horoscope[sign.ToLowerInvariant()].Daily.GetAsync()));

app.MapGet("/api/natal-chart", async (string city, string date, string time, RoxyClient roxy) =>
{
    try
    {
        var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = city);
        var loc = search!.Cities![0];
        var d = DateOnly.Parse(date);
        var t = TimeOnly.Parse(time);

        return Results.Ok(await roxy.Astrology.NatalChart.PostAsync(new()
        {
            Date = new Date(d.Year, d.Month, d.Day),
            Time = new Time(t.Hour, t.Minute, t.Second),
            Latitude = loc.Latitude,
            Longitude = loc.Longitude,
            Timezone = new() { String = loc.Timezone },
        }));
    }
    catch (RoxyError e)
    {
        return Results.Json(new { error = e.Message, code = e.Code }, statusCode: e.ResponseStatusCode);
    }
});

app.Run();
```

Never expose the API key in a Blazor WebAssembly, MAUI, Unity, or browser client. Call Roxy from server-side code only. The full [SDK guide](/docs/sdk "typed RoxyAPI SDKs for TypeScript, Python, PHP, C#, and Go") covers the same singleton pattern for controllers and hosted services.

## How to localize responses and handle errors correctly

Two .NET-specific shapes are worth learning here. First, the `Lang` query parameter is a generated enum, not a string, so the compiler steers you to a valid value: pass `PostLangQueryParameterType.Es`, not `"es"`. Interpretations are available in eight languages (`en`, `tr`, `de`, `es`, `fr`, `hi`, `pt`, `ru`), professionally localized and native-speaker reviewed. Second, every endpoint throws a typed `RoxyError` on failure, so switch on the stable `Code`, never the human-readable `Message`.

```csharp
var card = await roxy.Tarot.Daily.PostAsync(
    new() { Seed = "user-42" },
    c => c.QueryParameters.Lang = RoxyApi.Tarot.Daily.PostLangQueryParameterType.Es);
Console.WriteLine($"{card!.Card!.Name}: {card.DailyMessage}");
```

That call returns Spanish interpretation text live: `Reina de Bastos: Tu carta para 2026-07-08: Reina de Bastos (invertida). enfoque interior, reconstruir la autoestima, introversion, celos.` Untranslated fields fall back to English. On the error path, `RoxyError` extends `ApiException` and exposes `Code` (stable, switch on it), `Message` (wording may change), `ResponseStatusCode` (the HTTP status), and `Issues` (every field that failed validation on a 400). Wrap calls in `try { ... } catch (RoxyError e)` and branch on `e.Code`: `validation_error`, `invalid_api_key`, `subscription_inactive`, `rate_limit_exceeded`, `not_found`, or `internal_error`. Explore any endpoint on the live [API reference](/api-reference "interactive RoxyAPI playground returning real production responses") playground, which returns real production responses.

## FAQ

**How do I add astrology to a C# or .NET project?**

Install the SDK with `dotnet add package RoxyApi.Sdk` and create a client with `new RoxyClient(apiKey)`. The astrology namespace exposes 33 endpoints, including `roxy.Astrology.Horoscope["aries"].Daily.GetAsync()` for a transit-driven daily horoscope and `roxy.Astrology.NatalChart.PostAsync(...)` for a full natal chart with planets, houses, and aspects. Every response is a fully typed object, so your IDE autocompletes each field and the compiler catches mistakes before you deploy.

**Which .NET versions does the RoxyAPI SDK support?**

RoxyApi.Sdk targets `net8.0` and `netstandard2.0`, so it runs on .NET 8 and later plus anything that consumes netstandard2.0: .NET Framework 4.6.1+, Unity, Xamarin, MAUI, Blazor, and Mono. Language version 12 or later is recommended for the target-typed `new()` and collection-expression syntax in the examples. The only runtime dependency is the MIT-licensed Kiota bundle from Microsoft.

**How do I generate a Vedic kundli in C#?**

Geocode the birth city with `roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Mumbai")`, then call `roxy.VedicAstrology.BirthChart.PostAsync(new() { Date = new Date(1990, 1, 15), Time = new Time(14, 30, 0), Latitude = city.Latitude, Longitude = city.Longitude, Timezone = new() { String = city.Timezone } })`. Each sign accessor carries a `Signs` list where every planet exposes `Graha`, `House`, `IsRetrograde`, and a `Nakshatra` object with name and pada for pada-quarter precision.

**Do RoxyAPI SDK calls return an error object or throw?**

They throw. On success a call returns the typed response as a nullable reference; on a 4xx or 5xx it throws `RoxyError`, a subclass of `ApiException`. Wrap calls in `try { ... } catch (RoxyError e)` and switch on the stable `e.Code`. A 400 populates `e.Issues` with every field that failed validation, and `e.ResponseStatusCode` carries the HTTP status for mapping to your own responses.

**How do I set the response language in the .NET SDK?**

The `Lang` query parameter is a generated enum, not a string, so pass `roxy.Tarot.Daily.PostAsync(new() { Seed = "user-42" }, c => c.QueryParameters.Lang = RoxyApi.Tarot.Daily.PostLangQueryParameterType.Es)`. Eight languages are supported (en, tr, de, es, fr, hi, pt, ru) across astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, and angel numbers. Untranslated fields fall back to English, and `roxy.Languages.GetAsync()` returns the live list.

## Conclusion

The .NET SDK closes the C# gap in the RoxyAPI client family, which now spans TypeScript, Python, PHP, C#, and Go, all sharing the same operationId-driven surface across 164 endpoints and 12 domains under one key. Install with `dotnet add package RoxyApi.Sdk`, set your key in configuration, and ship an ASP.NET Core, Blazor, MAUI, or Unity insight app this afternoon. Start with the [astrology API](/products/astrology-api "production-ready astrology API with natal charts, transits, and synastry") to grab a key and make your first call.