Developer API

Welcome to the Humanity Protocol Developer API. This is a simple, authenticated HTTP API for integrating Proof-of-Humanity into your applications. You can verify whether an EVM wallet address belongs to a unique, palm-verified human, enabling Sybil-resistant airdrops, fair governance, and more.

Getting Started

To get started, you will need an API key. You can request one by filling out this form.

Important: All API requests must include your API key in the X-HP-API-Key header.

Base URL

https://api.hptestingsite.com

Authentication

The API uses API key authentication. Include your API key in the request header:

Copy
X-HP-API-Key: your_api_key_here

Public Endpoints

Verify Wallet Address

Endpoint: GET /v1/human/verify

Description: Returns whether the supplied wallet address is associated with a palm-verified Humanity Protocol user. This is the primary endpoint for dApps and services to integrate Proof-of-Humanity checks.

Parameters

Parameter	Type	Required	Description
wallet_address	string	Yes	EIP-55 compliant wallet address to verify

Example Request

Copy
curl -X GET "https://api.hptestingsite.com/v1/human/verify?wallet_address=0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B" \
  -H "X-HP-API-Key: your_api_key_here"

Example Response

Copy
{
  "wallet_address": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
  "is_human": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
wallet_address	string	The wallet address that was checked
is_human	boolean	True if the wallet belongs to a palm-verified user
user_id	string	UUID of the verified user

Response Codes

Code	Description
200	Success - Wallet verification status retrieved
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key disabled or insufficient permissions
404	Not Found - Wallet address not found in registry

Error Responses

All error responses follow this format:

Copy
{
  "error": "Error message describing what went wrong"
}

Common Error Messages

• Missing API key - The X-HP-API-Key header was not provided
• Invalid / disabled API key - The provided API key is invalid or has been disabled
• Wallet not found - The wallet address is not registered in the Humanity Protocol

Integration Examples

JavaScript/Node.js

Copy
const axios = require('axios');

async function verifyHuman(walletAddress) {
  try {
    const response = await axios.get('https://api.hptestingsite.com/v1/human/verify', {
      params: { wallet_address: walletAddress },
      headers: { 'X-HP-API-Key': 'your_api_key_here' }
    });
    
    return response.data.is_human;
  } catch (error) {
    console.error('Verification failed:', error.response?.data?.error);
    return false;
  }
}

// Usage
const isHuman = await verifyHuman('0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B');
console.log('Is human:', isHuman);

Python

Copy
import requests

def verify_human(wallet_address):
    url = "https://api.hptestingsite.com/v1/human/verify"
    headers = {"X-HP-API-Key": "your_api_key_here"}
    params = {"wallet_address": wallet_address}
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        return response.json()["is_human"]
    except requests.exceptions.RequestException as e:
        print(f"Verification failed: {e}")
        return False

# Usage
is_human = verify_human("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B")
print(f"Is human: {is_human}")

Solidity Smart Contract

Copy
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IHumanityOracle {
    function isHuman(address wallet) external view returns (bool);
}

contract SybilResistantAirdrop {
    IHumanityOracle public humanityOracle;
    mapping(address => bool) public hasClaimed;
    
    constructor(address _oracleAddress) {
        humanityOracle = IHumanityOracle(_oracleAddress);
    }
    
    function claimAirdrop() external {
        require(humanityOracle.isHuman(msg.sender), "Must be verified human");
        require(!hasClaimed[msg.sender], "Already claimed");
        
        hasClaimed[msg.sender] = true;
        // Distribute tokens...
    }
}

Use Cases

Sybil-Resistant Airdrops

Ensure each airdrop recipient is a unique human, preventing bot farms and duplicate claims.

Fair Governance

Implement one-person-one-vote systems where each vote represents a real human.

Human-Only Access

Gate premium features or content to verified humans only.

Anti-Bot Protection

Prevent automated abuse of your platform by requiring human verification.

Rate Limits

• Rate Limit: 1000 requests per hour per API key
• Burst Limit: 10 requests per second

Rate limit headers are included in responses:

• X-RateLimit-Limit: Total requests allowed per hour
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets

Support

• Documentation: developers.hptestingsite.com
• Website: humanity.org
• Email: developer@humanity.org

For technical support or questions about integrating the API, please reach out to our developer support team.