SDK

TypeScript SDK for reading human verification data from Starknet.

Installation

Terminal

npm install @humangate/sdk

The SDK provides HumanGateChainReader — a read-only client for querying the HumanGateRegistry contract on Starknet. All calls are free (no gas, no API keys, no backend).

Quick Start

humangate.ts

import { HumanGateChainReader } from "@humangate/sdk";

const reader = new HumanGateChainReader({
  rpcUrl: "https://rpc.starknet.lava.build",
  registryAddress: "0x07f66804a1556e31993afb4eddfb2c90b78f67785c92a5860a076edc38b17d26",
});

// Check if address is a verified human
const isHuman = await reader.isHuman(userAddress);

// Get full attestation details
const attestation = await reader.getAttestation(userAddress, "worldcoin");

// Check eligibility for a scoped action
const eligible = await reader.isEligible(userAddress, scopeHash, "worldcoin");

// Check if action already consumed
const consumed = await reader.hasConsumed(userAddress, scopeHash);

Constructor

Option	Type	Description
rpcUrl	string	Starknet RPC endpoint URL.
registryAddress	string	Address of the HumanGateRegistry contract.

Methods

Method	Returns	Description
isHuman(address, minLevel?)	Promise<boolean>	Check if address has any valid attestation at the minimum level (default 1). Checks all active providers.
getAttestation(address, providerId)	Promise<AttestationView>	Get full attestation details for a specific provider.
isEligible(address, scopeHash, providerId)	Promise<boolean>	Check if address can perform a scoped action (airdrop, vote, etc.).
hasConsumed(address, scopeHash)	Promise<boolean>	Check if an action has already been consumed by this address.

Types

AttestationView

@humangate/sdk

interface AttestationView {
  provider_id: string;    // e.g. "worldcoin"
  level: number;          // 1 = Device, 2 = Orb
  issued_at: number;      // Unix timestamp
  expires_at: number;     // Unix timestamp (0 = never)
  is_revoked: boolean;
}

ChainReaderConfig

@humangate/sdk

interface ChainReaderConfig {
  rpcUrl: string;           // Starknet RPC endpoint
  registryAddress: string;  // HumanGateRegistry contract address
}

Example: Airdrop Gate

airdrop-check.ts

import { HumanGateChainReader } from "@humangate/sdk";

const reader = new HumanGateChainReader({
  rpcUrl: "https://rpc.starknet.lava.build",
  registryAddress: "0x07f66804a1556e31993afb4eddfb2c90b78f67785c92a5860a076edc38b17d26",
});

async function canClaim(userAddress: string, scopeHash: string): Promise<boolean> {
  const isHuman = await reader.isHuman(userAddress);
  if (!isHuman) return false;

  const eligible = await reader.isEligible(userAddress, scopeHash, "worldcoin");
  const consumed = await reader.hasConsumed(userAddress, scopeHash);

  return eligible && !consumed;
}

Contract Address

HumanGateRegistry on Starknet Mainnet:

text

0x07f66804a1556e31993afb4eddfb2c90b78f67785c92a5860a076edc38b17d26

View on Starkscan →