Create Ledger

POST /v1/ledgers

A ledger represents a currency. Every account and transfer belongs to a ledger. Accounts on different ledgers cannot transact directly.

Request

{
  "id": 1001,
  "name": "TZS",
  "currency_code": "TZS",
  "asset_scale": 0
}

Field	Required	Type	Description
id	Yes	integer	Unique ledger ID
name	Yes	string	Display name
currency_code	Yes	string	ISO 4217 code
asset_scale	No	integer	Decimal places. 2 for USD (cents), 0 for TZS, 8 for BTC

Asset scale

Quda stores all amounts as integers. The asset scale tells the system how many decimal places the currency uses.

Currency	Scale	Amount 50000 means
USD	2	$500.00
TZS	0	TZS 50,000
KWD	3	50.000 KWD
BTC	8	0.00050000 BTC

Formula: display = amount / 10^scale

Asset scale cannot be changed

Once a ledger is created, its asset scale is permanent. You cannot change it later. If you choose the wrong scale, you will need to create a new ledger and migrate your accounts.

Think about whether your application may ever need more precision. For example, it might seem natural to use scale 2 for USD. But if you ever need to represent fractions of a cent (for interest calculations, fee splitting, or crypto conversions), you will wish you had used scale 4 or 6 from the start.

Choose a larger scale than you think you need. It is much easier to divide for display than to migrate a ledger.

Working with amounts

All amounts in Quda are integers. Never use floating-point arithmetic.

// Correct: calculate in integers
fee = amount * 25 / 1000   // 2.5% fee

// Wrong: floating-point introduces rounding errors
fee = amount * 0.025        // Do not do this

When displaying amounts to users, divide by 10^scale only at the presentation layer. All internal calculations, comparisons, and storage should use the raw integer amounts.

Response 201

{
  "data": {
    "tenant_id": "f714f6af-93fd-4e7a-8f79-254377a7c38f",
    "ledger": {
      "id": 1001,
      "name": "TZS",
      "currency_code": "TZS",
      "asset_scale": 0,
      "created_at": "2026-04-06T22:21:44Z"
    }
  }
}

Headers

Authorization: Bearer qk_live_...
Idempotency-Key: <unique-string>
Content-Type: application/json