ShiwakeDocs

Quickstart

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

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

1. Create a tenant

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" }'

Response gives you a ten_... id. Save it.

2. Mint the first API key

curl -X POST "https://api.shiwake.example.com/api/v1/platform/tenants/ten_01HZ.../rotate-api-key" \
  -H "Authorization: Bearer $PLATFORM_ADMIN_JWT"

The response contains data.api_key. 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.

export LEDGER_KEY="sk_live_KJH3k2jh4KJH3...=="

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).

# 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"
  }'

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).

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 }
    ]
  }'

50000 is GHS 500.00 in pesewas. Everything in Shiwake is minor units.

5. Read the balance

curl "https://api.shiwake.example.com/api/v1/ledger/accounts/CLIENT-42/balance" \
  -H "X-Api-Key: $LEDGER_KEY"

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.

Where to go next

Edit on GitHub

Last updated on

On this page