Verify an Agent in Your App

import express from "express";

const app = express();
app.use(express.json());

// ...routes from the steps below...

app.listen(3000, () => console.log("Listening on :3000"));

import { randomBytes } from "node:crypto";

// Nonces you have issued and not yet seen back. Use a shared store
// (Redis, a database) if you run more than one instance.
const issuedNonces = new Map();
const NONCE_TTL_MS = 5 * 60 * 1000;

// GET /api/v1/instructions: no DID required to call this
app.get("/api/v1/instructions", (req, res) => {
  const nonce = randomBytes(16).toString("hex");
  const now = Date.now();
  issuedNonces.set(nonce, now);

  res.json({
    info: {
      domain: "rewards.example.com",
      uri: "https://rewards.example.com/claim",
      version: "1",
      nonce,
      issuedAt: new Date(now).toISOString(),
      expirationTime: new Date(now + NONCE_TTL_MS).toISOString(),
      statement: "Sign to prove you control this agent's key.",
      requiredAttestations: ["0xca354bee6dc5eded165461d15ccb13aceb6f77ebbb1fd3fe45aca686097f2911"],
    },
    supportedChains: [{ chainId: "eip155:84532", type: "eip191" }],
  });
});

import { privateKeyToAccount } from "viem/accounts";
import { signHumanProofChallengeEVM } from "@billionsnetwork/x402-human-proof-client";

// The SDK's signer is { address, signMessage(message: string) }.
const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const evmSigner = {
  address: account.address,
  signMessage: (message) => account.signMessage({ message }),
};

// Where your application runs. Defaults to the local server from the setup block.
const APP = process.env.APP_URL ?? "http://localhost:3000";

const challenge = await fetch(`${APP}/api/v1/instructions`).then((r) => r.json());
const header = await signHumanProofChallengeEVM(challenge, evmSigner, "eip155:84532");

const res = await fetch(`${APP}/api/v1/claim`, {
  method: "POST",
  headers: { "HUMAN-PROOF": header },
});
console.log(res.status, await res.text());

import {
  verifyHumanProofRequest,
  createPoUVerifier,
  HUMAN_PROOF_HEADER,
} from "@billionsnetwork/x402-human-proof-server";

const verifier = createPoUVerifier({
  attestationsApiBaseUrl: "https://attestations-api.billions.network/api/v1/attestations",
  nullifierApiBaseUrl: "https://attestations-api.billions.network/api/v1/nullifier",
});

app.post("/api/v1/claim", async (req, res) => {
  const header = req.headers[HUMAN_PROOF_HEADER.toLowerCase()] ?? null;

  // 1. Your own checks. The SDK checks the signed uri, but it does not
  //    track nonces or check the domain.
  if (!header) {
    return res.status(400).json({ error: "missing_header" });
  }
  let proof;
  try {
    proof = JSON.parse(header);
  } catch {}
  if (!proof?.nonce) {
    return res.status(400).json({ error: "invalid_header" });
  }

  const issuedAt = issuedNonces.get(proof.nonce);
  issuedNonces.delete(proof.nonce); // single use, whatever happens next
  if (issuedAt === undefined || Date.now() - issuedAt > NONCE_TTL_MS) {
    return res.status(403).json({ error: "unknown_or_expired_nonce" });
  }
  if (proof.domain !== "rewards.example.com" || proof.uri !== "https://rewards.example.com/claim") {
    return res.status(403).json({ error: "wrong_domain_or_resource" });
  }

  // 2. Signature, DID derivation and pairing lookup.
  const result = await verifyHumanProofRequest(verifier, {
    resource: "https://rewards.example.com/claim",
    humanProofHeader: header,
  });

  if (!result.allowed) {
    return res.status(403).json({ error: result.reason });
  }

  // result.did: the agent's DID, recovered from the signature
  // result.resolution.humanId: the verified human behind it
  res.json({ verified: true, agentDid: result.did });
});

node server.mjs

AGENT_PRIVATE_KEY=$(node -e "import('viem/accounts').then((m) => console.log(m.generatePrivateKey()))") node agent.mjs

403 {"error":"not_registered"}

import { randomBytes } from "node:crypto";
import { recoverMessageAddress } from "viem";

const API = "https://attestations-api.billions.network/api/v1";
const OWNERSHIP_SCHEMA = "0xca354bee6dc5eded165461d15ccb13aceb6f77ebbb1fd3fe45aca686097f2911";

// Challenges you have issued and not yet seen back.
// Use a shared store (Redis, a database) if you run more than one instance.
const issued = new Map();
const TTL_MS = 5 * 60 * 1000;

// Throws on an error status, so an outage is never read as "not registered".
async function getJson(url) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Attestations API returned ${res.status}`);
  return res.json();
}

app.get("/api/v1/challenge", (req, res) => {
  const nonce = randomBytes(16).toString("hex");
  const message =
    `rewards.example.com wants you to prove control of your agent key.\n` +
    `Resource: https://rewards.example.com/claim\n` +
    `Nonce: ${nonce}\n` +
    `Issued At: ${new Date().toISOString()}`;
  issued.set(nonce, { message, at: Date.now() });
  res.json({ nonce, message });
});

app.post("/api/v1/claim", async (req, res) => {
  const { nonce, signature } = req.body ?? {}; // Express 5 leaves req.body undefined with no JSON body

  // Control: the nonce is yours, unused and recent.
  const entry = issued.get(nonce);
  issued.delete(nonce); // single use, whatever happens next
  if (!entry || Date.now() - entry.at > TTL_MS) {
    return res.status(403).json({ error: "unknown_or_expired_nonce" });
  }

  // Control: recover the signer from the signature over the message you issued.
  let address;
  try {
    address = await recoverMessageAddress({ message: entry.message, signature });
  } catch {
    return res.status(403).json({ error: "invalid_signature" });
  }

  // Pairing: look up an ownership attestation addressed to that signer.
  // An API failure means "can't tell right now", never "not registered".
  let data;
  try {
    const url = `${API}/attestations?schemaId=${OWNERSHIP_SCHEMA}&recipientEthereumAddress=${address}`;
    ({ data } = await getJson(url));
    if (!Array.isArray(data)) throw new Error("Unexpected response from the Attestations API");
  } catch {
    return res.status(503).json({ error: "verification_unavailable" });
  }
  const pairing = data.find((a) => a.toEthereumAddress.toLowerCase() === address.toLowerCase());
  if (!pairing) {
    return res.status(403).json({ error: "not_registered" });
  }

  // Optional: the human's nullifier, for per-human limits.
  let humanId;
  try {
    ({ nullifier: humanId } = await getJson(`${API}/nullifier?userId=${pairing.fromId}`));
  } catch {
    return res.status(503).json({ error: "verification_unavailable" });
  }

  // Verified, not paid: paying the reward and one claim per human are separate steps.
  res.json({ verified: true, agentDid: pairing.toDid, humanDid: pairing.fromDid, humanId });
});

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY); // viem account, or any EIP-191 signer

const APP = process.env.APP_URL ?? "http://localhost:3000";

const { nonce, message } = await fetch(`${APP}/api/v1/challenge`).then((r) => r.json());
const signature = await account.signMessage({ message });

const res = await fetch(`${APP}/api/v1/claim`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ nonce, signature }),
});
console.log(res.status, await res.text());