# SDK Overview

LedgerCore.Sdk: the official .NET client for the Shiwake API.

URL: https://docs.shiwake.app/docs/sdk



`LedgerCore.Sdk` is the official .NET client for Shiwake. It ships as a
single NuGet package targeting `net8.0` and gives you three layers you can
mix and match:

<Cards>
  <Card title="Core client" href="/docs/sdk/core-client">
    `ILedgerCoreClient`: a typed, 1:1 mapping of the core ledger REST API.
    One method per endpoint, throws `LedgerCoreException` on non-success.
  </Card>

  <Card title="Banking client (simple)" href="/docs/sdk/banking">
    `IBankingClient`: opinionated convenience layer over the core ledger:
    open client account, deposit, withdraw, transfer via direct journal entries.
  </Card>

  <Card title="Banking API client (full)" href="/docs/sdk/banking-api">
    `IBankingApiClient`: typed 1:1 client for the full `/api/v1/banking/*`
    surface: wallets, fee schedules, limits, suspense, statements, audit.
  </Card>
</Cards>

When to use which [#when-to-use-which]

**Use the core client** when you want direct control: posting arbitrary
journal entries, managing holds, running reconciliation. This is the right
layer for accounting-aware code.

**Use the simple banking client** when you're building a very small
product that thinks in terms of "clients have a balance, they deposit,
withdraw, and transfer." It collapses the platform-float + customer-liability
pattern into one-line calls and writes journal entries directly. No
wallets, no fees, no limits.

**Use the banking API client** for everything else, and most production
banking workloads fall here. It covers the full banking domain: wallet
products and tiers, hold/capture withdrawals, fee schedules, per-tier
limits, suspense and reconciliation, statements, and the audit log.

All three share the same `HttpClient` and the same tenant API key, so you
can register any combination and mix them freely in the same service.

Design goals [#design-goals]

* **Typed everything.** Every request and response has a C# record or
  class. No dictionaries, no `dynamic`.
* **No hidden retries.** The SDK throws on `429` and `5xx`; your app owns
  the retry policy (we recommend Polly: see [Rate Limiting](/docs/api/rate-limiting)).
* **DI-first.** One-line `AddLedgerCoreSdk` registers an `HttpClient`-backed
  client via `IHttpClientFactory`.
* **Idempotency is your job.** Mutating methods take an `idempotencyKey`
  parameter explicitly so you have to think about it.

Next steps [#next-steps]

<Cards>
  <Card title="Installation" href="/docs/sdk/installation">
    Add the NuGet package and wire it into DI.
  </Card>

  <Card title="Configuration" href="/docs/sdk/configuration">
    `LedgerCoreOptions`, `BankingOptions`, and how to bind from `appsettings`.
  </Card>

  <Card title="Error handling" href="/docs/sdk/error-handling">
    `LedgerCoreException`, status code switching, retry policies.
  </Card>
</Cards>
