Install the Zafeguard TypeScript SDK, set up your API key, and execute your first component in under 5 minutes.

Getting Started

Get up and running with Zafeguard in under 5 minutes.

1. Install

npm install @zafeguard/caller-sdk
# or
yarn add @zafeguard/caller-sdk
# or
pnpm add @zafeguard/caller-sdk

Requirements: Node.js 18+ or any modern browser environment.

2. Get your API key

Go to Dashboard → Workspace → Settings → API Keys and create a new key. Label is required (e.g. Development). Leave Allowed Workflows empty for unrestricted access.

You will be shown your key once — copy it now:

Variable	Value	Purpose
`ZAFEGUARD_API_KEY`	`ws_...`	Authenticates SDK requests

Store it in an environment variable — never hardcode credentials:

# .env
ZAFEGUARD_API_KEY=ws_your_key_here
ZAFEGUARD_WORKFLOW_ID=your_workflow_uuid_here

3. Initialize the SDK

import { WorkspaceClient } from '@zafeguard/caller-sdk';

const workspace = new WorkspaceClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
});

That's it. The SDK injects the API key on every request and handles the result-streaming protocol for you.

4. Execute your first component

import { WorkspaceClient, ComponentModule } from '@zafeguard/caller-sdk';

const workspace = new WorkspaceClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
});

const result = await workspace
  .call(ComponentModule.RANDOM_UUID, {})
  .promise();

console.log(result.uuid); // "a4c2e8f1-39b0-4d7a-83c6-1b5f2e9d0c77"

.promise() submits the component and waits for the result using a Server-Sent Events stream — no polling, no webhooks required.

5. Query a blockchain

import { WorkspaceClient, ComponentModule } from '@zafeguard/caller-sdk';

const workspace = new WorkspaceClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
});

const { balance } = await workspace
  .call(ComponentModule.GET_EVM_ACCOUNT_BALANCE, {
    jsonRpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
    tokenAddress: '0x0000000000000000000000000000000000000000', // native ETH
    account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  })
  .promise();

console.log(balance); // "1000000000000000000" (wei)

6. Trigger a workflow

For multi-step workflows, use WorkflowClient with your workspace key and the workflow UUID:

import { WorkflowClient } from '@zafeguard/caller-sdk';

const workflow = new WorkflowClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
  workflowId: process.env.ZAFEGUARD_WORKFLOW_ID!,
});

// Trigger and wait for all stages to finish. `trigger()` returns an array —
// one entry per ON_API_CALLED component on the workflow (usually exactly one).
const [{ runId }] = await workflow.trigger();
const run = await workflow.waitForRun(runId);

console.log(run.status);     // "COMPLETED"
console.log(run.totalUsage); // credits consumed

What's next?

Execute Component → All delivery modes — SSE, webhook, and fire-and-forget.

Execute Workflow → Trigger, stream, and inspect workflow runs.

Component Library → Browse all 80+ components with schemas.

SDK Types → Full TypeScript type reference.

Common patterns

Error handling

import { WorkspaceClient, ComponentModule, CallerSDKError } from '@zafeguard/caller-sdk';

const workspace = new WorkspaceClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
});

try {
  const result = await workspace
    .call(ComponentModule.BROADCAST_EVM_TRANSACTION, {
      jsonRpcUrl: 'https://rpc.example.com',
      signedTransaction: '0x...',
    })
    .promise();
} catch (err) {
  if (err instanceof CallerSDKError) {
    // Validation errors are thrown synchronously before any network call
    console.error(err.message);  // Human-readable
    console.error(err.details);  // Zod validation errors or API error body
  }
}

Fire and forget with webhook

import { WorkspaceClient, ComponentModule } from '@zafeguard/caller-sdk';

const workspace = new WorkspaceClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
});

// Returns immediately — result is delivered to your webhook
const execution = await workspace
  .call(ComponentModule.WAIT_FOR_EVM_TRANSACTION, {
    jsonRpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
    transactionHash: '0xabc123...',
  })
  .execute({
    callbackUrl: 'https://your-app.com/webhooks/wr',
    callbackSecret: process.env.ZAFEGUARD_CALLBACK_SECRET,
  });

console.log('Tracking:', execution.id); // poll or stream this ID

Live workflow progress

import { WorkflowClient } from '@zafeguard/caller-sdk';

const workflow = new WorkflowClient({
  apiKey: process.env.ZAFEGUARD_API_KEY!,
  apiSecret: process.env.ZAFEGUARD_API_SECRET!,
  workflowId: process.env.ZAFEGUARD_WORKFLOW_ID!,
});

const [{ runId }] = await workflow.trigger();

const sub = workflow.stream(runId, {
  onUpdate(event) {
    const pending = event.output.pendingStageCount ?? '?';
    console.log(`${event.status} — ${pending} stages remaining`);
  },
});

// sub.close() to unsubscribe early; stream auto-closes on completion

Getting Started

On this page