Build on Falah OS™

Quick Start 5 Minutes

Think of the Falah OS API like a set of LEGO bricks — each brick (Identity, Wallet, Contracts) snaps cleanly onto the others. You don't need to understand the internals to build with them.

# 1. Install the SDK
npm install falah-sdk-ts

# 2. Import and initialise
import { FalahClient } from 'falah-sdk-ts'

const falah = new FalahClient({
  apiKey: 'your-api-key',
  network: 'mock-net'   // use 'mainnet' for production
})

# 3. Create an Ummah ID
const identity = await falah.identity.register({
  jurisdiction: 'MY'
})

console.log(identity.ummah_id)  // UID-A1B2C3D4-XYZ

# 4. Spin up a wallet
const wallet = await falah.wallet.create({
  ummah_id: identity.ummah_id,
  currency: 'FLH'
})

console.log(wallet.wallet_id)   // FLH-XXXX-XXXX-XXXX

# 5. Execute a Shariah contract
const contract = await falah.contracts.execute({
  contract_type: 'qard_al_hasan',
  amount: 500,
  parties: { party_a: wallet.wallet_id, party_b: 'FLH-RECIPIENT' }
})

console.log(contract.shariah_verified)  // true ✓

SDK Installation TypeScript

The Falah OS TypeScript SDK provides first-class type definitions, Mock-Net test harnesses, and RAMZ contract bindings. Additional language SDKs are in development.

TypeScript / JavaScript

Install the SDK package from npm (publishing soon — source available on GitHub):

# Install the TypeScript SDK
npm install @falah/os-sdk

Basic usage:

import { FalahClient } from '@falah/os-sdk'

// Initialise with your API key
const falah = new FalahClient({
  apiKey: 'your-api-key',
  network: 'mock-net'
})

// Register an identity
const identity = await falah.identity.register({
  jurisdiction: 'MY'
})
console.log(identity.ummah_id)

SDK source code is available on GitHub →

Python · Go · Swift — Coming Soon

Native SDKs for Python, Go, and Swift are in active development. Watch the Falah OS repository for release announcements.

API Reference Live Endpoints

All endpoints below are live on Mock-Net. Click any endpoint to expand its documentation.

curl https://dev.falah-os.com/api/health

curl -X POST https://dev.falah-os.com/api/identity/register \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction": "MY", "level": "standard"}'

curl "https://dev.falah-os.com/api/identity/verify?ummah_id=UID-ABC123"

curl -X POST https://dev.falah-os.com/api/wallet/create \
  -H "Content-Type: application/json" \
  -d '{"ummah_id": "UID-ABC123", "currency": "FLH"}'

curl "https://dev.falah-os.com/api/wallet/balance?wallet_id=FLH-XXXX-XXXX"

curl https://dev.falah-os.com/api/contracts/templates

curl -X POST https://dev.falah-os.com/api/contracts/execute \
  -H "Content-Type: application/json" \
  -d '{"contract_type": "qard_al_hasan", "amount": 500, "currency": "FLH"}'

Authentication JWT

Falah OS uses JSON Web Tokens (JWT) for API authentication. Every API call (except /api/health) must include a valid session token obtained via login.

1. Obtain a session token

Send a POST request to /api/auth/login with your registered email and password:

curl -X POST https://dev.falah-os.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@falahos.my", "password": "admin"}'

A successful response returns your JWT access token:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "user": {
    "email": "admin@falahos.my",
    "role": "developer"
  }
}

2. Pass the token in requests

Include the token in the Authorization header of every subsequent API call:

curl https://dev.falah-os.com/api/wallet/balance?wallet_id=FLH-XXXX-XXXX \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. Using the AUTH global (Browser)

When logged in via the Dev Portal, a global AUTH object is available in the browser console. Use it to authenticate API calls from your own scripts:

// Available after signing in via the Dev Portal
if (AUTH.isLoggedIn()) {
  const res = await AUTH.fetch('/api/wallet/balance?wallet_id=FLH-XXXX-XXXX')
  const data = await res.json()
  console.log(data)
}

// You can also access the token directly
const token = AUTH.getToken()
console.log(token)  // JWT string

Error Handling Codes

Falah OS returns consistent JSON error responses across all API endpoints. Every error includes a code, message, and details field.

{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid authentication token",
  "details": "Provide a valid Bearer token in the Authorization header",
  "request_id": "req_abc123def456"
}

Always check the code field programmatically — never rely on parsing the HTTP status text. Use the request_id when reporting issues to support.

Retry strategy

For 429 (rate limited) responses, wait the duration specified in the Retry-After header before retrying. For 5xx errors, implement exponential backoff starting at 1 second, doubling each retry, up to a maximum of 30 seconds.

Live API Sandbox Mock-Net

Your flight simulator. Call every endpoint live against the Mock-Net. Zero risk, full fidelity.