# Core Client

ILedgerCoreClient: 1:1 mapping to the REST API.

URL: https://docs.shiwake.app/docs/sdk/core-client



`ILedgerCoreClient` is a direct, typed mapping of the REST API. Each
method maps to exactly one endpoint. There are no convenience helpers and
no hidden calls. What you see is what the wire sees.

Inject it into any service after calling `AddLedgerCoreSdk`:

```csharp
public class LedgerService(ILedgerCoreClient ledger)
{
    // use `ledger` for any ledger operation
}
```

All mutating methods throw `LedgerCoreException` on non-success. See
[Error handling](/docs/sdk/error-handling) for the details.

Accounts [#accounts]

```csharp
Task<Account> CreateAccountAsync(
    CreateAccountRequest request,
    string? idempotencyKey = null,
    CancellationToken ct = default);

Task<Account> GetAccountAsync(
    string accountId,
    CancellationToken ct = default);

Task<AccountListResponse> ListAccountsAsync(
    string? accountType = null,
    string? parentId    = null,
    string? cursor      = null,
    int size            = 50,
    CancellationToken ct = default);

Task<Account> DeactivateAccountAsync(
    string accountId,
    string? idempotencyKey = null,
    CancellationToken ct   = default);

Task<AccountBalance> GetBalanceAsync(
    string accountId,
    CancellationToken ct = default);

Task<TransactionListResponse> GetTransactionsAsync(
    string accountId,
    DateTime? from = null,
    DateTime? to   = null,
    string? cursor = null,
    int size       = 50,
    CancellationToken ct = default);
```

Maps to the endpoints documented in [Accounts](/docs/api/accounts). The
`accountId` parameter accepts either the ULID id or the account code.

Quick example:

```csharp
await ledger.CreateAccountAsync(new CreateAccountRequest
{
    Code     = "CLIENT-42",
    Name     = "Acme Retail wallet",
    Type     = AccountType.Liability,
    Currency = "GHS"
}, idempotencyKey: Guid.NewGuid().ToString());

var balance = await ledger.GetBalanceAsync("CLIENT-42");
Console.WriteLine(balance.LedgerBalance); // 0
```

Journal Entries [#journal-entries]

```csharp
Task<JournalEntry> PostJournalEntryAsync(
    PostJournalEntryRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Task<JournalEntry> GetJournalEntryAsync(
    string entryId,
    CancellationToken ct = default);

Task<JournalEntryListResponse> ListJournalEntriesAsync(
    DateTime? from = null,
    DateTime? to   = null,
    string? status = null,
    string? cursor = null,
    int size       = 50,
    CancellationToken ct = default);

Task<JournalEntry> ReverseJournalEntryAsync(
    string entryId,
    ReverseEntryRequest request,
    string idempotencyKey,
    CancellationToken ct = default);
```

Note that `idempotencyKey` is **required** (not optional) on `Post` and
`Reverse`. These are the mutations that matter most and the signature
makes it impossible to forget. See [Journal Entries](/docs/api/journal-entries)
for the full endpoint reference and [Idempotency](/docs/api/idempotency)
for why it matters.

```csharp
var entry = await ledger.PostJournalEntryAsync(new PostJournalEntryRequest
{
    Description = "Deposit",
    Lines =
    [
        new("PLATFORM-FLOAT", EntryType.Debit,  50_000),
        new("CLIENT-42",      EntryType.Credit, 50_000)
    ]
}, idempotencyKey: Guid.NewGuid().ToString());
```

Holds [#holds]

```csharp
Task<Hold> PlaceHoldAsync(
    PlaceHoldRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Task<JournalEntry> CaptureHoldAsync(
    string holdId,
    CaptureHoldRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Task<Hold> ReleaseHoldAsync(
    string holdId,
    ReleaseHoldRequest request,
    string idempotencyKey,
    CancellationToken ct = default);

Task<HoldListResponse> ListHoldsAsync(
    string accountId,
    string? status = null,
    string? cursor = null,
    int size       = 50,
    CancellationToken ct = default);
```

Maps 1:1 to the [Holds](/docs/api/holds) endpoints. `CaptureHoldAsync`
returns the resulting `JournalEntry`: captures always settle by posting
an entry.

Reconciliation [#reconciliation]

```csharp
Task<TrialBalance> GetTrialBalanceAsync(
    DateTime? asOf = null,
    CancellationToken ct = default);

Task<BalanceVerification> VerifyBalancesAsync(
    DateTime? asOf = null,
    CancellationToken ct = default);
```

Both are read-only. `VerifyBalancesAsync` throws `LedgerCoreException`
with `StatusCode == 422` when discrepancies are found. This is the signal
to page oncall.

```csharp
try
{
    var result = await ledger.VerifyBalancesAsync();
    logger.LogInformation("All {Count} accounts balanced", result.AccountsChecked);
}
catch (LedgerCoreException ex) when (ex.StatusCode == 422)
{
    await pagerDuty.TriggerAsync("Ledger balance drift: " + ex.ApiMessage);
    throw;
}
```

What the core client does not do [#what-the-core-client-does-not-do]

* **Tenant management.** `POST /platform/tenants/*` requires a JWT, not an
  `X-Api-Key`, so it's out of scope for the SDK. Use `HttpClient` directly
  or a separate platform-admin tool.
* **Retries.** No automatic backoff on `429` or `5xx`. Use Polly: see
  [Rate Limiting](/docs/api/rate-limiting) for a worked example.
* **Currency formatting.** Amounts are `long` minor units everywhere.
  Display formatting is your app's concern.
