Official TypeScript/JavaScript SDK for Islamic Open Finance™ APIs.
Typed client for 109 Shariah-native rails across 19 categories (142+ endpoints) composed from 10 native domain engines over a single double-entry ledger. Two of those engines are the platform's defensible moats you call through this SDK:
client.settlement.*— Settlement Engine. 24×7×365 DvP/FOP/RVP/DFP finality for Murabaha, Ijarah, Salam, Sukuk. AAOIFI SS-1/8/10/17/21/30 enforced at the state machine; CSDR Art. 7 penalties priced pre-confirm; ribawi-pair netting honoured. Reclaims 60–140 bps per corridor.client.evidence.*— Evidence Engine. Signed, tamper-evident compliance pack emitted on every trade: 47/54 controls across SOC 2, ISO 27001, AAOIFI, GDPR, PSD2, IFSB and ISO 20022, SHA-256 Merkle root + HMAC signature, one-call verification. Reclaims 30–55 bps on audit + re-papering.
Combined: 100–195 bps of Islamic-finance friction reclaimed per corridor — no core replacement.
npm install @islamic-open-finance/sdk
# or
yarn add @islamic-open-finance/sdk
# or
pnpm add @islamic-open-finance/sdkimport { IOFClient } from "@islamic-open-finance/sdk";
// Initialize the client
const client = new IOFClient({
apiKey: process.env.IOF_API_KEY,
environment: "sandbox", // 'sandbox' | 'production'
});
// Create a Murabaha contract
const contract = await client.contracts.create({
type: "murabaha",
parties: [
{ role: "seller", entityId: "entity_123" },
{ role: "buyer", entityId: "entity_456" },
],
terms: {
costPrice: 100000,
profitMargin: 0.05,
paymentSchedule: "monthly",
tenure: 36,
},
});
console.log("Contract created:", contract.id);The SDK provides full coverage for all Islamic Open Finance™ rails:
| Category | Rails |
|---|---|
| Contracts | Murabaha, Musharaka, Ijara, Sukuk, Mudaraba, Istisna, Salam |
| Compliance | KYC, AML, Consent, Governance, Disputes |
| Operations | Treasury, Clearing, Reconciliation, Routing, Settlement |
| Platform | Analytics, Billing, Reporting, Notifications, Webhooks |
| Identity | Access Consent, Legal, Partners, Underwriting |
| Specialty | Zakat, Portfolio, Risk, Cases, Observability |
Full TypeScript support with comprehensive type definitions:
import type { Contract, MurabahaTerms, Party } from "@islamic-open-finance/sdk";
const terms: MurabahaTerms = {
costPrice: 100000,
profitMargin: 0.05,
paymentSchedule: "monthly",
tenure: 36,
};import { IOFClient, IOFError } from '@islamic-open-finance/sdk';
try {
await client.contracts.create({ ... });
} catch (error) {
if (error instanceof IOFError) {
console.error('IOF API Error:', error.code, error.message);
console.error('Request ID:', error.requestId);
}
}// Automatic pagination handling
const contracts = await client.contracts.list({
status: "active",
limit: 100,
});
// Iterate through all pages
for await (const contract of client.contracts.listAll({ status: "active" })) {
console.log(contract.id);
}// Create a contract
const contract = await client.contracts.create({ ... });
// Get a contract
const contract = await client.contracts.get('contract_123');
// List contracts
const { data, hasMore } = await client.contracts.list({ limit: 50 });
// Update contract status
await client.contracts.updateStatus('contract_123', 'activated');// Create a verification
const verification = await client.kyc.createVerification({
entityId: "entity_123",
type: "individual",
documents: [{ type: "passport", fileId: "file_abc" }],
});
// Check verification status
const status = await client.kyc.getVerification(verification.id);// Get positions
const positions = await client.treasury.getPositions({
workspaceId: "ws_123",
});
// Record a transaction
await client.treasury.recordTransaction({
type: "credit",
amount: 50000,
currency: "SAR",
reference: "TXN-001",
});// Create a webhook subscription
const webhook = await client.webhooks.create({
url: "https://your-server.com/webhooks",
events: ["contract.created", "contract.activated"],
secret: "whsec_your_secret",
});
// Verify webhook signatures
const isValid = client.webhooks.verifySignature(payload, signature, secret);// Query analytics
const analytics = await client.analytics.query({
metric: "contract_volume",
from: "2024-01-01",
to: "2024-12-31",
groupBy: "month",
});const client = new IOFClient({
// Required
apiKey: process.env.IOF_API_KEY,
// Optional
environment: "sandbox", // 'sandbox' | 'production'
baseUrl: "https://api.custom-domain.com", // Override base URL
timeout: 30000, // Request timeout in ms
retries: 3, // Number of retries for failed requests
// Hooks
onRequest: (config) => {
/* modify request */
},
onResponse: (response) => {
/* handle response */
},
onError: (error) => {
/* handle error */
},
});| Environment | Base URL |
|---|---|
| Sandbox | https://api.sandbox.islamicopen.finance |
| Production | https://api.islamicopen.finance |
The SDK automatically handles rate limiting with exponential backoff:
- Sandbox: 1,000 requests/minute
- Production: Based on your SKU tier
import { IOFClient, createMockClient } from "@islamic-open-finance/sdk/testing";
// Create a mock client for testing
const mockClient = createMockClient();
mockClient.contracts.create.mockResolvedValue({
id: "contract_mock_123",
status: "draft",
});See CONTRIBUTING.md for guidelines.
Apache License 2.0 - see LICENSE for details.
This license includes an explicit patent grant for enterprise use.