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); // 0Journal 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 anX-Api-Key, so it's out of scope for the SDK. UseHttpClientdirectly or a separate platform-admin tool. - Retries. No automatic backoff on
429or5xx. Use Polly: see Rate Limiting for a worked example. - Currency formatting. Amounts are
longminor units everywhere. Display formatting is your app's concern.
Last updated on