ShiwakeDocs

Core Client

ILedgerCoreClient: 1:1 mapping to the REST API.

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:

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

All mutating methods throw LedgerCoreException on non-success. See Error handling for the details.

Accounts

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. The accountId parameter accepts either the ULID id or the account code.

Quick example:

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

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 for the full endpoint reference and Idempotency for why it matters.

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

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 endpoints. CaptureHoldAsync returns the resulting JournalEntry: captures always settle by posting an entry.

Reconciliation

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.

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

  • 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 for a worked example.
  • Currency formatting. Amounts are long minor units everywhere. Display formatting is your app's concern.
Edit on GitHub

Last updated on

On this page