Getting started

If you'd rather walk it manually, the same five steps are below.

Prerequisites

• Bun ≥ 1.0 (or Node ≥ 22). Iqrar is Bun-first; every bun command below also works under node.
• A foundation registry URL plus the public keys of the foundation roots that signed it. The Iqrar Foundation publishes its registry at https://iqrar.io/registry; for development you can run your own with bun run keys:init && bun run registry:sign.
• The jurisdiction code of the regulator whose rules your agent will follow — for example AE-DIFC (DFSA) or EU (ESMA).

1. Install the SDK

bun add https://iqrar.io/sdk/iqrar-agent-latest.tgz

The package is distributed as a tarball today; npm publishing is on the roadmap. The same URL works with npm install and pnpm add.

The package exports an Iqrar() factory plus framework-specific drop-ins (@iqrar/agent/openai, @iqrar/agent/anthropic, @iqrar/agent/vercel-ai, @iqrar/agent/mastra, @iqrar/agent/langchain).

2. Initialise the agent

import { Iqrar } from "@iqrar/agent";
import { filesystemIdentityStore } from "@iqrar/agent/identity";

const agent = Iqrar({
  endpoint: "https://api.iqrar.io",
  org: "acme",
  jurisdiction: "AE-DIFC",
  agentId: "acme-consumer-bot-1",
  capabilities: ["consumer_chatbot"],
  foundationRoots: [
    {
      kid: "foundation:root-1",
      pubkey_b64: process.env.IQRAR_FOUNDATION_PUBKEY!,
    },
  ],
  identityStore: filesystemIdentityStore("./.iqrar"),
});

await agent.register();

On first boot the SDK generates an Ed25519 keypair, derives agentId = sha256(pubkey)[..16], and registers against the foundation registry. The keypair persists under ./.iqrar/identity.json and rotation is structurally refused — every audit-chain entry from this agent is bound to its identity key.

3. Emit a decision

Once register() resolves, every event you emit is queued, written to a per-agent tamper-evident hash chain on the worker, and committed to a Merkle tree whose root is signed by a foundation key and submitted to Sigstore Rekor every minute.

agent.decision({
  decisionId: "loan-app-2026-05-05-001",
  input: "Customer requested $50,000 SME loan, tenure 36 months",
  output: "Approved at 8.5% APR, conditional on guarantor",
  rationale: "Credit score 740, 3y trading history, sector exposure within limits",
  affectsConsumer: true,
});

await agent.flush();

flush() durably enqueues to a Cloudflare Queue; Cloudflare ACKs the queue write before flush() returns, so even if the agent's process dies the next millisecond, the event survives.

4. Confirm the chain head

$ curl https://api.iqrar.io/agents/acme-consumer-bot-1/chain/head
{
"agent_id": "acme-consumer-bot-1",
"seq": 3,
"entry_hash": "8a2f...c1e9",
"ts": 1746478291000
}

The chain head returns (agent_id, seq, prev_hash, event_hash, entry_hash) for the most recent event. Each entry_hash = sha256(prev_hash || event_hash || seq) so any tampering with a historical event invalidates the chain forward of it.

5. Receive a regulator directive

A regulator-signed bundle published to your jurisdiction can elevate your verbosity, change your sample rate, or pause an entire capability for a defined time window. The SDK applies it on the next sync without redeploying:

$ bun run directive:issue 

--issuer DFSA 

--jurisdiction AE-DIFC 

--action verbosity 

--value debug 

--window-hours 24 

--justification "Supervisory inquiry SI-2026-001"
▸ Signed directive dir-3a91...
▸ Bundled into rules/AE-DIFC v17
▸ Published to registry. Agents will pick it up within 60s.
// In your agent process:
agent.verbosity()      // returns "debug"
agent.getActiveDirectives().active_ids   // "dir-3a91..."

The agent emits directive.received → directive.applied → agent.verbosity_changed{source:"directive"} events into its audit chain, so the change is itself committed.

Authentication after claim

Until your org is claimed through the , the API accepts unauthenticated traffic — register and ship telemetry with no credentials. The moment a claim is confirmed, the API requires a Bearer token for any agent in that org. The claim flow shows the token once; paste it into your .env:

IQRAR_API=https://api.iqrar.io
IQRAR_API_KEY=iqr_your_key_here
IQRAR_ENV=dev

The SDK reads IQRAR_API_KEY automatically and sends it on every API call. If you lose the key, rotate it from the — there's no way to recover the original.

What's next

• Concepts: the five inventive aspects of the Iqrar design —
• Audit-challenge protocol: how a regulator verifies agent behaviour against the public Rekor log without trusting Iqrar's infrastructure —
• Foundation: why a foundation governs the rules —