Overview

The Warisan API is a REST interface for integrating with the Warisan estate resolution infrastructure. It exposes endpoints across six layers: identity verification, estate state machine management, asset registry, distribution calculation (Faraid & civil), SBT settlement issuance, and institutional case ingestion.

Authentication

All API requests require Bearer token authentication. Tokens are institution-scoped — each partner organisation receives a unique token with defined permission scopes.

Authorization: Bearer wrs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Warisan-Institution: YOUR_INSTITUTION_ID

Base URL & Versioning

# Production
https://api.warisan.com.my/v1

# Sandbox
https://sandbox.api.warisan.com.my/v1

All responses return JSON. Dates use ISO 8601 (2025-01-15T10:30:00Z). Currency amounts are in Malaysian Ringgit (MYR) as integers in sen (1 MYR = 100 sen) to avoid floating-point errors.

Rate Limits

Rate limit headers are returned on every response: X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding limits returns HTTP 429 with a Retry-After header.

Error Codes

All errors return a consistent JSON envelope with a machine-readable code and a human-readable message.

{
  "error": {
    "code":    "HAJB_BLOCKED",
    "message": "Heir is blocked (Hajb Hirman) by a higher-priority relative.",
    "details": { "blocked_heir_id": "heir_abc123", "blocked_by": "heir_def456" }
  }
}

Identity Layer

All heirs and the deceased must be identity-verified before an estate can advance. Identity hashes are stored off-chain; only a cryptographic proof-of-inclusion is written to the consortium chain.

{
  "identity_id":       "idn_7x9k2m4p",
  "credential_hash":   "0x3a8f...c4b2",
  "status":            "VERIFIED",
  "religion":          "ISLAM",
  "track_suggestion":  "SYARIAH",
  "verified_at":       "2025-03-12T08:44:00Z"
}

{
  "identity_id":       "idn_7x9k2m4p",
  "death_status":      "PENDING_JPN_CONFIRMATION",
  "death_cert_hash":   "0xf7b1...22e9",
  "jpn_case_ref":      "JPN-2025-0382941"
}

Estate Management

The estate is the central object in Warisan. It progresses through a strict state machine. State transitions can only move forward and cannot be skipped.

{
  "estate_id":    "est_m3k9p7xr",
  "state":        "PENDING_VERIFICATION",
  "track":        "SYARIAH",
  "ipfs_hash":    null,
  "on_chain_id":  null,
  "filed_at":     "2025-03-15T09:00:00Z",
  "heirs": [
    { "identity_id": "idn_a1b2c3", "status": "PENDING" }
  ]
}

PENDING_VERIFICATION  → IDENTITY_VERIFIED
IDENTITY_VERIFIED     → ASSET_MAPPED
ASSET_MAPPED          → ARBITRATION        (if dispute flag set)
ASSET_MAPPED          → SETTLEMENT_ISSUED  (undisputed path)
ARBITRATION           → SETTLEMENT_ISSUED  (after arbitrator resolution)
SETTLEMENT_ISSUED     → DISTRIBUTED

Asset Registry

Assets must be declared and mapped to an estate before distribution can be calculated. Each asset is assigned a UUID and linked to the estate's on-chain record. Supports all asset classes including illiquid assets with resolution mode assignment.

{
  "asset_id":              "ast_k2p8n4xm",
  "estate_id":             "est_m3k9p7xr",
  "asset_type":            "PROPERTY",
  "appraised_value_sen":   50000000,
  "resolution_mode":       "A",
  "urgency":               0,
  "liquidity_discount":    0.00,
  "adjusted_value_sen":    50000000,
  "on_chain_uuid":         "0xa3f1...8b4c"
}

{
  "ic_number":  "820315XXXXXX",
  "ar_holdings": [
    {
      "ar_case_ref":   "AR-2019-082341",
      "asset_type":    "CASH",
      "status":        "UNCLAIMED",
      "est_value_band": "RM 10,000 – RM 50,000"
    }
  ]
}

Distribution Engine

The distribution engine applies Faraid rules (Quran 4:11–12, 4:176, Shafi'i school) for the Syariah track, or Distribution Act 1958 for the civil track. Both engines output heir shares as basis points and calculated amounts.

{
  "husband":          0,   // Max 1 (if deceased is female)
  "wives":            1,   // Max 4 (if deceased is male)
  "sons":             2,
  "daughters":        1,
  "father":           1,   // Max 1
  "mother":           1,   // Max 1
  "full_brothers":    0,
  "full_sisters":     0,
  "paternal_gf":      0,   // Paternal grandfather
  "maternal_gm":      0    // Maternal grandmother
}

{
  "estate_id":  "est_m3k9p7xr",
  "nde_sen":    48000000,
  "heirs": [
    {
      "role":          "WIFE",
      "count":         1,
      "fraction":      "1/8",
      "share_bps":     1250,
      "total_sen":     6000000,
      "per_person_sen":6000000,
      "basis":         "1/8 — descendants exist",
      "type":          "FIXED"
    },
    {
      "role":          "SON",
      "count":         2,
      "fraction":      "residue",
      "share_bps":     5833,
      "total_sen":     28000000,
      "per_person_sen":14000000,
      "basis":         "Asabah — 2x unit",
      "type":          "RESIDUARY"
    }
  ],
  "blocked_heirs": [],
  "total_allocated_bps": 10000
}

{
  "gev_sen":        60000000,  // Gross Estate Value
  "adj_gev_sen":    55500000,  // After liquidity discounts
  "liabilities_sen":7500000,   // Debts + costs
  "nde_sen":        48000000,  // Net Distributable Estate
  "assets_breakdown": [
    {
      "asset_id":          "ast_k2p8n4xm",
      "appraised_sen":     50000000,
      "discount_rate":     0.10,
      "adjusted_sen":      45000000,
      "resolution_mode":   "A"
    }
  ]
}

Settlement (SBT)

Settlement Soulbound Tokens are issued per heir after distribution is confirmed. Each SBT is non-transferable, anchored to Ethereum mainnet via Merkle proof, and accepted by Warisan partner FIs as proof of beneficial interest for collateralised financing.

{
  "sbt_id":          "sbt_p9x3k7mn",
  "status":          "MINTING",
  "estate_id":       "est_m3k9p7xr",
  "heir_identity_id":"idn_a1b2c3",
  "share_bps":       1250,
  "check_url":       "/v1/sbt/sbt_p9x3k7mn"
}

{
  "sbt_id":          "sbt_p9x3k7mn",
  "status":          "ISSUED",
  "transferable":    false,
  "share_bps":       1250,
  "nde_sen":         48000000,
  "heir_amount_sen": 6000000,
  "issued_at":       "2025-03-22T14:30:00Z",
  "ethereum_anchor": "0x7f3c...a8d1",
  "ipfs_hash":       "QmXz...kP9",
  "jpn_attestation": "JPN-SIG-2025-0384",
  "last_validated_at":"2026-03-22T00:00:00Z",
  "asset_entitlements": [
    {
      "asset_id":        "ast_k2p8n4xm",
      "asset_type":      "PROPERTY",
      "resolution_mode": "A",
      "entitlement_sen": 5625000
    }
  ],
  "fi_collateral_note": {
    "max_ltv_pct":    85,    // Mode A/B resolved; 40-60 if Mode C
    "collateral_type":"BENEFICIAL_INTEREST"
  }
}

Institutional API

The Institutional API allows partner organisations — banks, EPF, Bursa, insurers — to push unresolved estate cases to Warisan for resolution. Warisan resolves the estate and returns a settlement hash and SBT references via webhook.

{
  "warisan_case_id":      "wcase_n8m3k2px",
  "institution_case_ref": "ACC-2024-089234",
  "estate_id":            "est_m3k9p7xr",
  "status":               "INTAKE",
  "estimated_resolution": "21-30 days"
}

// Example webhook payload
{
  "event":      "sbt.issued",
  "timestamp":  "2025-03-22T14:35:00Z",
  "data": {
    "sbt_id":     "sbt_p9x3k7mn",
    "estate_id":  "est_m3k9p7xr",
    "heir_ic":    "820315XXXXXX",
    "share_bps":  1250,
    "eth_anchor": "0x7f3c...a8d1"
  }
}

{
  "valid":            true,
  "sbt_id":           "sbt_p9x3k7mn",
  "heir_amount_sen":  6000000,
  "recommended_ltv": 85,
  "collateral_type": "BENEFICIAL_INTEREST",
  "ethereum_verified":true,
  "last_validated":  "2026-03-22"
}

Enums & Constants

PENDING_VERIFICATION
IDENTITY_VERIFIED
ASSET_MAPPED
ARBITRATION
SETTLEMENT_ISSUED
DISTRIBUTED
CLOSED

SYARIAH   // Faraid — Quran 4:11–12
CIVIL     // Distribution Act 1958

A  // Collective Sale (بيع جماعي)
B  // Buyout (افتداء)
C  // Co-ownership / Musya' (مشاع)

CASH
PROPERTY
VEHICLE
SHARES
BUSINESS
OTHER

0  // Voluntary (0% discount)
1  // Court Order (10–20%)
2  // Forced Sale (20–30%)
3  // Distress Auction (30–40%)

Changelog