SDKs Overview

SDKs Overview

Islamic Open Finance™ provides official SDKs for popular programming languages, making it easy to integrate our API into your applications.

Available SDKs

Language	Package Name	Version	Status	Install Command
TypeScript	@iof/sdk	1.0.0	✅ Stable	npm install @iof/sdk
Python	iof-sdk	1.0.0	✅ Stable	pip install iof-sdk
Go	iof-sdk-go	0.1.0	🚧 Preview	go get github.com/Islamic-Open-Finance/iof-sdk-go
Java	iof-sdk	0.1.0	🚧 Preview	Maven/Gradle

::: note SDK Status

• Stable: Production-ready with full API coverage
• Preview: Under active development - API may change :::

Features

All SDKs include:

• Type Safety - Full type definitions for all API resources
• Auto-Retry - Automatic retry with exponential backoff
• Rate Limiting - Built-in rate limit handling
• Error Handling - Structured error types and messages
• Pagination - Easy iteration over paginated results
• Webhooks - Signature verification utilities

Quick Start

TypeScript

import { IOFClient } from "@iof/sdk";

const client = new IOFClient({
  apiKey: process.env.IOF_API_KEY!,
  environment: "sandbox",
});

// Create a contract
const contract = await client.contracts.create({
  type: "murabaha",
  parties: {
    financier: { entityId: "ent_123" },
    customer: { entityId: "ent_456" },
  },
  asset: {
    description: "Commercial vehicle",
    costPrice: { amount: 50000, currency: "SAR" },
    profitMargin: 0.08,
  },
});

// List contracts with pagination
for await (const contract of client.contracts.list()) {
  console.log(contract.id);
}

Python

import os
from iof import IOFClient

client = IOFClient(
    api_key=os.environ["IOF_API_KEY"],
    environment="sandbox"
)

# Create a contract
contract = client.contracts.create(
    type="murabaha",
    parties={
        "financier": {"entity_id": "ent_123"},
        "customer": {"entity_id": "ent_456"},
    },
    asset={
        "description": "Commercial vehicle",
        "cost_price": {"amount": 50000, "currency": "SAR"},
        "profit_margin": 0.08,
    }
)

# List contracts with pagination
for contract in client.contracts.list():
    print(contract.id)

Go

package main

import (
    "context"
    "fmt"
    "os"

    iof "github.com/Islamic-Open-Finance/iof-sdk-go"
)

func main() {
    client := iof.NewClient(
        iof.WithAPIKey(os.Getenv("IOF_API_KEY")),
        iof.WithEnvironment(iof.Sandbox),
    )

    ctx := context.Background()

    // Create a contract
    contract, err := client.Contracts.Create(ctx, &iof.ContractCreateParams{
        Type: "murabaha",
        Parties: &iof.ContractParties{
            Financier: &iof.Party{EntityID: "ent_123"},
            Customer:  &iof.Party{EntityID: "ent_456"},
        },
        Asset: &iof.Asset{
            Description:  "Commercial vehicle",
            CostPrice:    &iof.Money{Amount: 50000, Currency: "SAR"},
            ProfitMargin: 0.08,
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Created contract: %s\n", contract.ID)
}

Configuration Options

All SDKs support these configuration options:

Option	Description	Default
apiKey	Your API key	Required
environment	sandbox or production	sandbox
timeout	Request timeout in milliseconds	30000
maxRetries	Maximum retry attempts	3
baseUrl	Custom API base URL	Auto

Error Handling

SDKs provide structured error types:

import { IOFError, ValidationError, RateLimitError } from "@iof/sdk";

try {
  await client.contracts.create({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log("Validation failed:", error.details);
  } else if (error instanceof RateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof IOFError) {
    console.log("API error:", error.code, error.message);
  }
}

from iof.errors import IOFError, ValidationError, RateLimitError

try:
    client.contracts.create(...)
except ValidationError as e:
    print(f"Validation failed: {e.details}")
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}")
except IOFError as e:
    print(f"API error: {e.code} - {e.message}")

:::

Webhook Verification

All SDKs include utilities for verifying webhook signatures:

import { verifyWebhookSignature } from "@iof/sdk/webhooks";

const isValid = verifyWebhookSignature(
  payload,
  signature,
  process.env.WEBHOOK_SECRET!,
);

from iof.webhooks import verify_signature

is_valid = verify_signature(
    payload=payload,
    signature=signature,
    secret=os.environ["WEBHOOK_SECRET"]
)

:::

Next Steps

• TypeScript SDK - Detailed TypeScript documentation
• Python SDK - Detailed Python documentation
• Error Handling - Comprehensive error handling guide
• Webhooks - Webhook integration guide