Know Your Human
HomeDemoExplorerAPI Docs
📖 REST APIx402 Payments

API Documentation

Full reference for the KYC Gateway REST API. All endpoints support HTTPS and return JSON.

Base URLhttps://knowyourhuman.xyz💸 x402 Required

Endpoints

POST/api/verification

Request a new KYC verification session for a user. Returns a session ID and verification URL to send to the user. Payment via x402 required ($0.001–$0.75 cUSD depending on level).

Request Body

Request Body
json
{
  "userAddress": "0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf",
  "agentAddress": "0x3fA8B653F9abf91428800C8bB0AB9d8fE8c7A8c3",
  "level": "standard",
  "webhookUrl": "https://my-agent.xyz/kyc-callback"
}

// Fields:
// userAddress  (required) - Wallet address of the user to verify
// agentAddress (optional) - Wallet address of the requesting agent
// level        (required) - "starter" | "basic" | "standard" | "enhanced"
// webhookUrl   (optional) - POST webhook when verification completes

Response

Response (200 OK)
json
{
  "sessionId": "kyc_x7k2m9p4n1q8r3s5",
  "status": "pending",
  "level": "standard",
  "verifyUrl": "https://knowyourhuman.xyz/verify/kyc_x7k2m9p4n1q8r3s5",
  "expiresAt": "2026-03-18T04:01:00Z",
  "fee": {
    "amount": "1.50",
    "currency": "cUSD",
    "network": "celo"
  }
}

cURL Example

Terminal
bash
# Step 1: Initial request (will get 402)
curl -X POST https://knowyourhuman.xyz/api/verification \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf",
    "level": "standard",
    "webhookUrl": "https://my-agent.xyz/kyc-callback"
  }'

# Step 2: Pay via x402 and retry
# Use the x402-fetch library for automatic payment handling:
# npm install x402-fetch

Integration Guides

x402Auto-Payment with x402

Use the x402-fetch library to handle payments automatically. No manual payment logic needed.

x402-integration.ts
typescript
import { withPaymentInterceptor } from "x402-fetch";

// Wrap fetch with x402 auto-payment
const fetch = withPaymentInterceptor(globalThis.fetch, {
  walletPrivateKey: process.env.AGENT_PRIVATE_KEY, // cUSD balance needed
  network: "celo",
});

// This will:
// 1. Make initial request
// 2. Handle 402 automatically (pay $1.50 cUSD)
// 3. Retry with X-PAYMENT header
// 4. Return successful response
const response = await fetch("https://knowyourhuman.xyz/api/verification", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    userAddress: userWalletAddress,
    level: "standard",
    webhookUrl: "https://your-agent.xyz/kyc-webhook",
  }),
});

const { sessionId, verifyUrl } = await response.json();
// Send verifyUrl to user via email, Telegram, etc.

🤖 AgentFull Agent Workflow

Complete example: request verification, notify user, and poll for completion or receive webhook.

agent-workflow.ts
typescript
// Complete agent workflow — request KYC and monitor
async function requestKYC(userAddress: string) {
  // 1. Request verification (auto-pays via x402)
  const res = await fetch("https://knowyourhuman.xyz/api/verification", {
    method: "POST",
    body: JSON.stringify({ userAddress, level: "standard" }),
    headers: { "Content-Type": "application/json" },
  });
  const { sessionId, verifyUrl } = await res.json();
  
  // 2. Send verify link to user
  await sendToUser(verifyUrl);
  
  // 3. Poll for completion
  let verified = false;
  while (!verified) {
    await sleep(5000);
    const status = await fetch(
      `https://knowyourhuman.xyz/api/verification?id=${sessionId}`
    ).then(r => r.json());
    
    if (status.status === "completed") {
      verified = true;
      console.log("User verified!", status.attestationHash);
    }
  }
}

// Or use webhooks (recommended)
// POST webhookUrl receives: { event: "verification.completed", attestationHash }

Coming SoonSDK (TypeScript/Python)

@knowyourhuman/sdk
typescript
// npm install @knowyourhuman/sdk (coming soon)
import { KYH } from "@knowyourhuman/sdk";

const gateway = new KYH({
  apiKey: process.env.KYC_GATEWAY_KEY,
  agentAddress: process.env.AGENT_ADDRESS,
  network: "celo",
});

// Simple one-liner
const result = await gateway.verify(userAddress, "standard");

if (result.isVerified) {
  console.log("✅ User verified on Celo:", result.attestationHash);
}

Pricing

LevelFee (cUSD)
basic$0.25
standard$1.50
enhanced$5.00