Skip to main content

HumanPass JS-SDK

Overview​

The HumanPass JavaScript SDK will provide a seamless way for third-party dApps to integrate with the HumanPass ecosystem. This SDK will enable developers to verify unique human identity across multiple blockchain environments.

Note: The JS-SDK is currently in development and planned for release in Q1 2026. This documentation outlines the intended functionality.

Core Features​

  • World ID Verification: Verify users through World ID's Proof of Personhood (Orb, Document, or Device levels)
  • Wallet Integration: Connect users' blockchain wallets and verify Soulbound Tokens (SBTs)
  • Cross-Chain Verification: Verify human identity across multiple blockchain networks
  • Human Identity Score (HIS) Access: Leverage HumanPass's reputation framework
  • Social Account Verification: Verify linked Twitter and Telegram accounts

Installation (Future)​

# Using npm
npm install @humanpass/js-sdk

# Using pnpm
pnpm add @humanpass/js-sdk

Basic Usage​

import { HumanPassSDK } from "@humanpass/js-sdk";

// Initialize the SDK
const humanpass = new HumanPassSDK({
  appId: "YOUR_APP_ID",
  environment: "production", // or 'staging' for development
});

// Check if the user is a verified human
const isHuman = await humanpass.verification.isHuman();
if (isHuman) {
  // Enable human-only features
  enableHumanOnlyFeatures();
} else {
  // Prompt for verification
  promptForVerification();
}

Verification Process​

// Define verification requirements
const verificationParams = {
  requiredVerifications: {
    worldId: {
      required: true,
      minLevel: "device", // "orb", "document", or "device"
    },
    wallet: {
      required: true,
      chains: ["evm"],
    },
    social: {
      required: false,
      platforms: ["twitter", "telegram"],
    },
  },
  humanIdentityScore: {
    required: false,
    minScore: 0,
  },
};

// Request verification
try {
  const verificationRequest = await humanpass.verification.requestVerification(
    verificationParams
  );
  console.log(`Verification requested: ${verificationRequest.id}`);
} catch (error) {
  console.error("Verification request failed:", error);
}

// Handle verification completion
humanpass.on("verificationComplete", (result) => {
  if (result.success) {
    console.log("Verification successful:", result.data);
    processVerifiedData(result.data);
  } else {
    console.error("Verification failed:", result.error);
  }
});

Wallet Integration​

// Connect a wallet
const walletConnection = await humanpass.wallet.connect();

// Check if the wallet has a Soulbound Token (SBT)
const hasSBT = await humanpass.wallet.hasSoulboundToken(
  walletConnection.address
);

if (hasSBT) {
  console.log("Wallet has a HumanPass Soulbound Token");
} else {
  // Initiate SBT minting process
  const mintRequest = await humanpass.wallet.requestSBTMinting(
    walletConnection.address
  );
  console.log("SBT minting requested:", mintRequest.id);
}

Cross-Chain Verification​

// Check if the user is verified on a specific chain
const isVerified = await humanpass.verification.isVerifiedOnChain("ethereum");

if (isVerified) {
  console.log("User is verified on Ethereum");
} else {
  console.log("User is not verified on Ethereum");
}

Human Identity Score (HIS)​

// Get the user's Human Identity Score
const hisData = await humanpass.his.getUserScore();

console.log("Human Identity Score:", hisData.score);
console.log("Verification Level:", hisData.verificationLevel);
console.log("Human Points:", hisData.humanPoints);

Practical Use Cases​

Sybil-Resistant Airdrops​

// Check if the user is a verified human with Orb verification
const isOrbVerified = await humanpass.verification.isHuman("orb");

if (isOrbVerified) {
  // Allow claiming the maximum allocation
  allowMaxAllocation();
} else {
  // Check for device-level verification
  const isDeviceVerified = await humanpass.verification.isHuman("device");

  if (isDeviceVerified) {
    // Allow claiming a reduced allocation
    allowReducedAllocation();
  } else {
    // Prompt for verification
    promptForVerification();
  }
}

Bot-Free NFT Minting​

// Check if the user is a verified human
const isHuman = await humanpass.verification.isHuman();

// Get the user's wallet connection
const walletConnection = await humanpass.wallet.connect();

if (isHuman && walletConnection) {
  // Enable minting with fair queue position
  enableMinting(walletConnection.address);
} else {
  // Require verification before minting
  requireVerificationForMinting();
}

Human-Only Community Access​

// Check if the user is a verified human
const isHuman = await humanpass.verification.isHuman();

// Get the user's social verification status
const socialAccounts = await humanpass.social.getVerifiedAccounts();

if (isHuman) {
  // Enable full community access
  enableFullCommunityAccess();

  // If they have verified social accounts, grant additional privileges
  if (socialAccounts.twitter || socialAccounts.telegram) {
    grantSocialVerifiedBadge();
    enableAdvancedFeatures();
  }
} else {
  // Limit access and prompt for verification
  limitAccessAndPromptVerification();
}

API Reference​

Core Methods​

Constructor​

const humanpass = new HumanPassSDK(options);

Parameters:

  • options (Object):
    • appId (String): Your application ID
    • environment (String): 'production' or 'staging'
    • debug (Boolean): Enable debug mode (optional)

Verification Module​

Check Human Status​

const isHuman = await humanpass.verification.isHuman(minLevel);

Parameters:

  • minLevel (String, optional): Minimum verification level ('orb', 'document', or 'device', default: 'device')

Returns:

  • Boolean: True if the user is verified as human with the specified minimum level

Get Verification Status​

const status = await humanpass.verification.getStatus();

Returns:

  • Object:
    • worldId (Object): World ID verification status
    • wallet (Object): Wallet connection status
    • social (Object): Social account verification status

Request Verification​

const request = await humanpass.verification.requestVerification(params);

Parameters:

  • params (Object): Verification parameters

Returns:

  • Object: Verification request details

Wallet Module​

Connect Wallet​

const connection = await humanpass.wallet.connect(options);

Returns:

  • Object: Wallet connection details

Check Soulbound Token​

const hasSBT = await humanpass.wallet.hasSoulboundToken(address);

Parameters:

  • address (String, optional): Wallet address to check (default: connected wallet)

Returns:

  • Boolean: True if the wallet has a HumanPass Soulbound Token

Human Identity Score Module​

Get User Score​

const hisData = await humanpass.his.getUserScore();

Returns:

  • Object: Human Identity Score data

Event Handling​

// Register event listener
humanpass.on(eventName, callback);

// Available events:
// - verificationComplete: Fired when verification is completed
// - verificationCancelled: Fired when verification is cancelled
// - walletConnected: Fired when a wallet is connected
// - sbtMinted: Fired when a Soulbound Token is minted
// - error: Fired when an error occurs

Best Practices​

  1. Progressive Verification: Start with minimal verification requirements and progressively request more as needed
  2. Clear Communication: Clearly communicate to users why verification is necessary
  3. Error Handling: Implement proper error handling for all verification steps
  4. Privacy First: Only request the verification methods necessary for your application
  5. Testing: Thoroughly test your integration in development environments before deploying to production

For the latest updates on development progress, please refer to our roadmap or join our Discord.