# Quickstart

Provision a tenant, post your first entry, and read the balance.

URL: https://docs.shiwake.app/docs/getting-started/quickstart



This guide walks through the five calls that get a brand-new tenant to a
working ledger: create the tenant, mint an API key, create two accounts,
post a balanced journal entry, and read the balance. It should take under
five minutes.

You will need:

* A running Shiwake instance (this guide uses
  `https://api.shiwake.example.com` as the base URL)
* A platform-admin JWT for the create-tenant step
* `curl` or the [.NET SDK](/docs/sdk)

***

<Steps>
  <Step>
    1\. Create a tenant [#1-create-a-tenant]

    <CodeBlockTabs defaultValue="curl">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          curl
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants" \
          -H "Authorization: Bearer $PLATFORM_ADMIN_JWT" \
          -H "Content-Type: application/json" \
          -d '{ "name": "Acme Finance", "slug": "acme-finance" }'
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Response gives you a `ten_...` id. Save it.
  </Step>

  <Step>
    2\. Mint the first API key [#2-mint-the-first-api-key]

    <CodeBlockTabs defaultValue="curl">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          curl
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../rotate-api-key" \
          -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    The response contains `data.api_key`. &#x2A;*This is the only time the raw key
    is shown.** Stash it in a secret store now. If you lose it, you have to
    rotate again.

    ```bash
    export LEDGER_KEY="sk_live_KJH3k2jh4KJH3...=="
    ```
  </Step>

  <Step>
    3\. Create two accounts [#3-create-two-accounts]

    You need at least two accounts to post anything, because every entry
    requires balanced debits and credits. For a wallet product, the classic
    pair is a platform-owned float (Asset) and a customer liability (Liability).

    <CodeBlockTabs defaultValue="curl">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          curl
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="csharp">
          C# (SDK)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        # Platform float: where customer deposits actually sit
        curl -X POST "https://api.shiwake.example.com/api/v1/ledger/accounts" \
          -H "X-Api-Key: $LEDGER_KEY" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "code": "PLATFORM-FLOAT",
            "name": "Platform float",
            "accountType": "Asset",
            "normalBalance": "Debit",
            "currency": "GHS"
          }'

        # Customer wallet: what the platform owes them
        curl -X POST "https://api.shiwake.example.com/api/v1/ledger/accounts" \
          -H "X-Api-Key: $LEDGER_KEY" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "code": "CLIENT-42",
            "name": "Acme Retail wallet",
            "accountType": "Liability",
            "normalBalance": "Credit",
            "currency": "GHS"
          }'
        ```
      </CodeBlockTab>

      <CodeBlockTab value="csharp">
        ```csharp
        var ledger = new LedgerCoreClient(new LedgerCoreOptions
        {
            BaseUrl = "https://api.shiwake.example.com",
            ApiKey  = Environment.GetEnvironmentVariable("LEDGER_KEY")!
        });

        await ledger.CreateAccountAsync(new CreateAccountRequest
        {
            Code     = "PLATFORM-FLOAT",
            Name     = "Platform float",
            Type     = AccountType.Asset,
            Currency = "GHS"
        }, idempotencyKey: Guid.NewGuid().ToString());

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

  <Step>
    4\. Post a journal entry [#4-post-a-journal-entry]

    Book a GHS 500 deposit into the customer's wallet. Debit the asset (float
    grew), credit the liability (we owe more).

    <CodeBlockTabs defaultValue="curl">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          curl
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="csharp">
          C# (SDK)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl -X POST "https://api.shiwake.example.com/api/v1/ledger/journal-entries" \
          -H "X-Api-Key: $LEDGER_KEY" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "description": "Deposit into Acme Retail wallet",
            "createdBy": "quickstart",
            "lines": [
              { "accountCode": "PLATFORM-FLOAT", "entryType": "Debit",  "amount": 50000 },
              { "accountCode": "CLIENT-42",      "entryType": "Credit", "amount": 50000 }
            ]
          }'
        ```
      </CodeBlockTab>

      <CodeBlockTab value="csharp">
        ```csharp
        var entry = await ledger.PostJournalEntryAsync(new PostJournalEntryRequest
        {
            Description = "Deposit into Acme Retail wallet",
            CreatedBy   = "quickstart",
            Lines =
            [
                new("PLATFORM-FLOAT", EntryType.Debit,  50_000),
                new("CLIENT-42",      EntryType.Credit, 50_000)
            ]
        }, idempotencyKey: Guid.NewGuid().ToString());

        Console.WriteLine($"Posted entry {entry.Id}");
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <Callout type="info">
      `50000` is GHS 500.00 in pesewas. Everything in Shiwake is minor
      units.
    </Callout>
  </Step>

  <Step>
    5\. Read the balance [#5-read-the-balance]

    <CodeBlockTabs defaultValue="curl">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="curl">
          curl
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="csharp">
          C# (SDK)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="curl">
        ```bash
        curl "https://api.shiwake.example.com/api/v1/ledger/accounts/CLIENT-42/balance" \
          -H "X-Api-Key: $LEDGER_KEY"
        ```
      </CodeBlockTab>

      <CodeBlockTab value="csharp">
        ```csharp
        var balance = await ledger.GetAccountBalanceAsync("CLIENT-42");
        Console.WriteLine($"Ledger: {balance.LedgerBalance}, available: {balance.AvailableBalance}");
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    You should see `50000` for both ledger and available balance. Congratulations. You have a working tenant with a real journal entry and a real balance.
  </Step>
</Steps>

Where to go next [#where-to-go-next]

<Cards>
  <Card title="API reference" href="/docs/api">
    Every endpoint, every field, every status code.
  </Card>

  <Card title=".NET SDK" href="/docs/sdk">
    The typed client and the higher-level Banking layer.
  </Card>

  <Card title="Holds" href="/docs/api/holds">
    Authorize now, settle later.
  </Card>

  <Card title="Reconciliation" href="/docs/api/reconciliation">
    Trial balance and stored-vs-computed verification.
  </Card>
</Cards>
