Wakalah Rail

Agency contract endpoints for delegated investment and service management.

Overview

The Wakalah rail provides:

Agency contract creation and management
Fee-based and incentive-based Wakalah support
Investment Wakalah (Wakalah bil Istithmar) for fund management
Agent performance tracking and reporting

Wakalah is an agency contract where one party (the principal, or Muwakkil) appoints another party (the agent, or Wakil) to perform a specific task on their behalf. The agent acts within the authority granted and earns a fee for their services.

Investment Wakalah (Wakalah bil Istithmar) is widely used in Islamic banking for deposit placement, fund management, and treasury operations. The principal entrusts funds to the agent for investment, and the agent receives a fixed fee or an incentive fee linked to performance above a benchmark.

Wakalah can be general (covering a broad scope of activities) or specific (limited to a particular transaction). It is commonly combined with other contracts such as Mudarabah and Ijarah to create structured Islamic financial products.

Endpoints

Create Wakalah Contract

POST /v1/rails/wakalah/contracts

const contract = await iof.wakalah.create({
  wakalah_type: "investment",
  description: "Treasury fund placement - Q1 2025",
  principal_id: "cpty_institution",
  agent_id: "cpty_fund_mgr",
  investment_amount: 2000000,
  currency: "USD",
  fee_structure: {
    type: "incentive",
    base_fee: 10000,
    performance_fee_ratio: 0.2,
    benchmark_return: 0.05,
  },
  investment_period_months: 6,
  permitted_activities: ["sukuk", "commodity_murabaha", "money_market"],
});

Response:

{
  "id": "wkl_xyz",
  "type": "wakalah",
  "subtype": "investment",
  "status": "DRAFT",
  "investment_amount": 2000000,
  "currency": "USD",
  "fee_structure": {
    "type": "incentive",
    "base_fee": 10000,
    "performance_fee_ratio": 0.2,
    "benchmark_return": 0.05
  },
  "investment_period_months": 6,
  "created_at": "2024-01-15T10:30:00Z"
}

Get Wakalah Contract

GET /v1/rails/wakalah/contracts/:id

List Wakalah Contracts

GET /v1/rails/wakalah/contracts

Execute Wakalah Contract

POST /v1/rails/wakalah/contracts/:id/execute

Report Performance

POST /v1/rails/wakalah/contracts/:id/report-performance

Contract Types

Type	Description
`investment`	Agent invests funds on behalf of the principal
`service`	Agent performs a specific service or task
`general`	Agent has broad authority to act for the principal

Contract Status

Status	Description
`DRAFT`	Contract created, pending review
`PENDING_SHARIAH_REVIEW`	Awaiting Shariah board approval
`SHARIAH_APPROVED`	Approved by Shariah board
`ACTIVE`	Agency appointment active
`COMPLETED`	Agency period ended, fees settled
`TERMINATED`	Contract terminated early

Shariah Compliance

The scope of the agent’s authority must be clearly defined
The agent’s fee must be known and agreed at inception
The agent may not guarantee the principal’s capital or a fixed return
Any loss due to agent negligence or misconduct is borne by the agent
Investment losses (absent negligence) are borne by the principal
The principal may revoke the agency at any time

Webhooks

Event	Description
`wakalah.contract.created`	Contract created
`wakalah.contract.executed`	Agency appointment active
`wakalah.performance.reported`	Performance report submitted
`wakalah.fee.paid`	Agent fee disbursed
`wakalah.contract.completed`	Agency period ended

Standards

Next Steps

Mudarabah Rail - Profit-sharing partnership
Musharakah Rail - Equity partnership
Contracts Rail - General contract management