Waqf Rail

Islamic endowment (Waqf) creation, management, and beneficiary distribution.

Overview

The Waqf rail provides a complete lifecycle for managing Islamic endowments in compliance with AAOIFI Shariah Standard No. 33 (SS-33). A Waqf is a perpetual charitable endowment where the principal asset is preserved and only its yields or usufruct are distributed to designated beneficiaries.

The rail supports the three primary Waqf types: Waqf Khayri (public charitable endowment), Waqf Ahli (family endowment), and Waqf Mushtarak (combined endowment). Each type carries distinct rules for beneficiary designation, asset management, and distribution schedules.

Waqf assets are held in trust and cannot be sold, gifted, or inherited. The platform enforces this immutability at the contract level, ensuring that only the generated income from Waqf assets flows to beneficiaries. Nazir (trustee) management, periodic valuations, and Shariah board oversight are built into the workflow.

Integration with the Ledger rail ensures transparent tracking of all income generated by Waqf assets, while the Compliance rail validates adherence to the Waqf deed (Waqfiyyah) conditions throughout the endowment lifecycle.

Endpoints

Create Waqf Endowment

POST /v1/rails/waqf/endowments

const waqf = await iof.waqf.create({
  name: "Al-Noor Education Waqf",
  type: "khayri",
  asset_description: "Commercial building - Block A, Riyadh Business District",
  asset_value: 2000000,
  currency: "SAR",
  waqif_id: "cpty_waqif_001",
  nazir_id: "cpty_nazir_001",
  beneficiaries: [
    { category: "education", allocation_pct: 0.6 },
    { category: "healthcare", allocation_pct: 0.4 },
  ],
  distribution_frequency: "quarterly",
});

Response:

{
  "id": "wqf_xyz",
  "type": "waqf",
  "subtype": "khayri",
  "status": "DRAFT",
  "name": "Al-Noor Education Waqf",
  "asset_value": 2000000,
  "currency": "SAR",
  "beneficiaries": [
    { "category": "education", "allocation_pct": 0.6 },
    { "category": "healthcare", "allocation_pct": 0.4 }
  ],
  "distribution_frequency": "quarterly",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Waqf Endowment

GET /v1/rails/waqf/endowments/:id

List Waqf Endowments

GET /v1/rails/waqf/endowments

Record Income

POST /v1/rails/waqf/endowments/:id/income

Record income generated by the Waqf asset (rental income, investment returns).

Distribute to Beneficiaries

POST /v1/rails/waqf/endowments/:id/distribute

Request Valuation

POST /v1/rails/waqf/endowments/:id/valuations

Update Nazir (Trustee)

PUT /v1/rails/waqf/endowments/:id/nazir

Waqf Types

Type	Arabic	Description
`khayri`	خيري	Public charitable endowment
`ahli`	أهلي	Family endowment for descendants
`mushtarak`	مشترك	Combined public and family endowment

Endowment Status

Status	Description
`DRAFT`	Waqf deed created, pending review
`PENDING_SHARIAH_REVIEW`	Awaiting Shariah board approval
`ACTIVE`	Endowment registered and operational
`SUSPENDED`	Temporarily suspended by nazir
`DISSOLVED`	Dissolved by court order (rare)

Integration Points

Ledger Rail — tracks all income, expenses, and distributions for the Waqf
Compliance Rail — validates Waqfiyyah conditions and Shariah adherence
Reporting Rail — generates periodic beneficiary and financial reports
Governance Rail — Shariah board oversight of Waqf management decisions

Webhooks

Event	Description
`waqf.endowment.created`	Waqf deed created
`waqf.endowment.activated`	Endowment registered and active
`waqf.income.recorded`	Income from Waqf asset recorded
`waqf.distribution.issued`	Beneficiary distribution completed
`waqf.valuation.completed`	Asset valuation updated
`waqf.nazir.changed`	Trustee updated

Standards

Next Steps

Sadaqah Rail - Charitable donations
Zakat Rail - Zakat calculation and distribution
Governance Rail - Shariah board oversight