# Client
Source: https://docs.billions.network/agents/client

Full reference for the x402 Human Proof Client SDK.

## Overview

`@billionsnetwork/x402-human-proof-client` is the client SDK for agents calling services that require per-request payments and human-backed verification powered by the x402 human proof protocol.

It enables clients to:

* **Sign CAIP-122 (SIWE) challenges** embedded in `402` responses so the server can verify the agent is operated by a real human.
* **Check held attestations** against the [Billions Network registry](https://attestations-explorer.billions.network/) before attempting a payment, so attestation-gated (discounted) pricing tiers are selected only when the client qualifies.
* **Fall back gracefully** when attestations are missing (`MissingAttestationsError`) or when a per-human usage cap is hit (`isMaxUseExceededError` + `disqualify()`).

The SDK integrates with the x402 client lifecycle as a registered extension. It is framework-agnostic and compatible with any HTTP client library supported by x402.

<Tip>
  **Just want your agent to access human-proof protected APIs?** The [Verified Agent Identity skill](/agents/identity-overview) is built on top of this SDK — install it and your agent is ready without any code changes. If your agent hasn't installed the skill yet, the paywall HTML returned by the server already includes instructions to do so, so pre-installation is not required.
</Tip>

## How It Works

<img alt="x402 Human Proof request lifecycle" />

<Note>
  * The selector runs synchronously at payment creation time; attestation state is cached and refreshed via `refresh()`.
  * The extension re-checks attestations live just before signing — the selector cache and the live check serve different purposes: tier selection vs. proof construction.
  * If the server returns `max_use_exceeded`, call `disqualify()` on the selector and retry — it will skip discounted tiers permanently for that instance.
</Note>

## Installation

```bash theme={null}
npm install @billionsnetwork/x402-human-proof-client @x402/axios @x402/evm viem
```

<Info>
  Requires Node.js `>= 20.11.0` and an x402-compatible HTTP client. The agent wallet must hold a Billions Network PoU attestation to access discounted pricing tiers.
</Info>

## Quick Start

```typescript theme={null}
import { config } from "dotenv";
import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";
import {
  createHumanProofExtension,
  createAttestationAwareSelector,
  buildDIDFromAddress,
  MissingAttestationsError,
  isMaxUseExceededError,
} from "@billionsnetwork/x402-human-proof-client";

config();

const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const did = buildDIDFromAddress(evmSigner.address);

const { selector, refresh, disqualify } = createAttestationAwareSelector(did);
await refresh(); // pre-populate cache so selector has attestations on first use

const x402 = new x402Client(selector);
x402.register("eip155:*", new ExactEvmScheme(evmSigner));
x402.onBeforePaymentCreation(async () => { await refresh(); });
x402.registerExtension(
  createHumanProofExtension({
    address: evmSigner.address,
    signMessage: (msg) => evmSigner.signMessage({ message: msg }),
  }),
);
x402.onPaymentCreationFailure(async ({ error }) => {
  if (error instanceof MissingAttestationsError) {
    console.error("Missing attestations:", error.attestationRequirements);
  }
});

const api = wrapAxiosWithPayment(axios.create(), x402);

try {
  const response = await api.get("http://localhost:4021/weather");
  console.log(response.data);
} catch (err) {
  if (isMaxUseExceededError(err)) {
    disqualify(); // skip discounted tier for all future payments on this selector
    const response = await api.get("http://localhost:4021/weather");
    console.log(response.data);
  } else {
    throw err;
  }
}
```

## Core Concepts

### The Human-Proof Challenge

When the server is configured with `@billionsnetwork/x402-human-proof-server`, its `402` responses include an `extensions["human-proof"]` object:

```json theme={null}
{
  "human-proof": {
    "info": {
      "domain": "localhost",
      "uri": "http://localhost:4021/weather",
      "version": "1",
      "nonce": "1ab399792f4c9b05ac916fdf4fd9ac6c",
      "issuedAt": "2026-04-22T11:18:52.428Z",
      "expirationTime": "2026-04-22T11:33:52.428Z",
      "statement": "By signing, you provide a human proof",
      "resources": ["http://localhost:4021/weather"],
      "requiredAttestations": [
        "0xca354bee6dc5eded165461d15ccb13aceb6f77ebbb1fd3fe45aca686097f2911"
      ]
    },
    "supportedChains": [
      { "chainId": "eip155:84532", "type": "eip191" }
    ]
  }
}
```

`createHumanProofExtension` handles signing and proof construction automatically when registered with the x402 client.

### CAIP-122 / SIWE Signing

[CAIP-122](https://standards.chainagnostic.org/CAIPs/caip-122) defines chain-agnostic message signing. For EVM chains the SDK uses Sign-In with Ethereum (SIWE / `eip191`). `signHumanProofChallengeEVM` handles message formatting and signing; `createHumanProofExtension` calls it automatically — use it directly only if you need lower-level control.

***

## Configuration Reference

### `createHumanProofExtension(signer, options?)`

Register this extension on your x402 client to handle challenge signing automatically. On each payment attempt it extracts the `human-proof` challenge from the `402` body, verifies the wallet holds all required attestations, and injects the signed proof into the payment payload.

```javascript theme={null}
import { createHumanProofExtension } from "@billionsnetwork/x402-human-proof-client";

x402.registerExtension(createHumanProofExtension(signer, options));
```

**Parameters:**

| Parameter | Type                         | Description                                                                                          |
| --------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| `signer`  | `EVMSigner`                  | EVM signing interface — must have `address: string` and `signMessage(msg: string): Promise<string>`. |
| `options` | `HumanProofExtensionOptions` | Optional configuration.                                                                              |

**`HumanProofExtensionOptions`:**

| Option                   | Type     | Default                             | Description                                                                              |
| ------------------------ | -------- | ----------------------------------- | ---------------------------------------------------------------------------------------- |
| `attestationsApiBaseUrl` | `string` | `DEFAULT_ATTESTATIONS_API_BASE_URL` | Override the Billions Network attestations API URL used for pre-sign attestation checks. |

If no challenge is present in the `402` body the payload is returned unchanged. Otherwise it checks each required attestation schema (throwing `MissingAttestationsError` if any are missing), signs the SIWE message with the first `eip191`/`eip1271` chain, and returns the payload with `extensions["human-proof"]` set.

<Note>
  **Compatibility:** the `EVMSigner` interface is intentionally minimal. It is compatible with viem `WalletClient`, viem `LocalAccount` (`privateKeyToAccount`), and ethers v6 `Signer`.

  ```typescript theme={null}
  // viem WalletClient
  const signer: EVMSigner = {
    address: walletClient.account.address,
    signMessage: (msg) => walletClient.signMessage({ message: msg }),
  };

  // viem LocalAccount (privateKeyToAccount)
  const signer: EVMSigner = {
    address: account.address,
    signMessage: (msg) => account.signMessage({ message: msg }),
  };

  // ethers v6 Signer
  const signer: EVMSigner = {
    address: await ethersSigner.getAddress(),
    signMessage: (msg) => ethersSigner.signMessage(msg),
  };
  ```
</Note>

### `createAttestationAwareSelector(did, schemas?, options?)`

Creates a `selector` + `refresh` + `disqualify` triple for use with `new x402Client(selector)`. The selector picks the most favorable `accepts` entry based on cached attestation state.

```javascript theme={null}
import {
  createAttestationAwareSelector,
  buildDIDFromAddress,
} from "@billionsnetwork/x402-human-proof-client";

const did = buildDIDFromAddress(evmSigner.address);
const { selector, refresh, disqualify } = createAttestationAwareSelector(did);

await refresh();
const x402 = new x402Client(selector);
x402.onBeforePaymentCreation(async () => { await refresh(); });
```

**Parameters:**

| Parameter                        | Type       | Default                             | Description                                                                                                                                         |
| -------------------------------- | ---------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `did`                            | `string`   | —                                   | The client's DID. Use `buildDIDFromAddress(address)` to derive it.                                                                                  |
| `schemas`                        | `string[]` | `[DEFAULT_AGENT_OWNERSHIP_SCHEMA]`  | Schema IDs to check and cache. Must include all schemas present in the server's `requiredAttestations` for the selector to enable discounted tiers. |
| `options.attestationsApiBaseUrl` | `string`   | `DEFAULT_ATTESTATIONS_API_BASE_URL` | Override the attestations API URL.                                                                                                                  |

**Returns:**

| Member       | Type                                              | Description                                                                                                                                                                                                                                         |
| ------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selector`   | `(_version, requirements) => PaymentRequirements` | Synchronous selector. Pass directly to `new x402Client(selector)`.                                                                                                                                                                                  |
| `refresh`    | `() => Promise<void>`                             | Re-fetches attestation state from the registry. Call this inside `onBeforePaymentCreation`.                                                                                                                                                         |
| `disqualify` | `() => void`                                      | Permanently forces the selector to skip discounted options on this instance. Call when `isMaxUseExceededError` returns `true`. Not reset by `refresh()` — create a new `createAttestationAwareSelector` instance to re-enable discounted selection. |

### `buildDIDFromAddress(ethAddress)`

Derives the Billions Network DID from an EVM wallet address.

```javascript theme={null}
import { buildDIDFromAddress } from "@billionsnetwork/x402-human-proof-client";

const did = buildDIDFromAddress("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
// → "did:iden3:billions:main:..."
```

| Parameter    | Type     | Description                           |
| ------------ | -------- | ------------------------------------- |
| `ethAddress` | `string` | Checksummed or lowercase EVM address. |

Returns: `string` — the full DID string using the `did:iden3:billions:main:` method.

### `checkAttestation(did, schemaId, options?)`

Queries the Billions Network attestations API to check whether a DID holds at least one attestation matching a given schema ID.

```javascript theme={null}
import { checkAttestation, DEFAULT_AGENT_OWNERSHIP_SCHEMA } from "@billionsnetwork/x402-human-proof-client";

const held = await checkAttestation(did, DEFAULT_AGENT_OWNERSHIP_SCHEMA);
console.log(held); // true or false
```

| Parameter                        | Type     | Default                             | Description                |
| -------------------------------- | -------- | ----------------------------------- | -------------------------- |
| `did`                            | `string` | —                                   | The DID to check.          |
| `schemaId`                       | `string` | —                                   | The attestation schema ID. |
| `options.attestationsApiBaseUrl` | `string` | `DEFAULT_ATTESTATIONS_API_BASE_URL` | Override the API base URL. |

Returns: `Promise<boolean>` — `true` if at least one matching attestation record exists.

***

## Low-Level Helpers

### `signHumanProofChallengeEVM(challenge, signer, chainId)`

Lower-level function that signs a CAIP-122 challenge for an EVM chain and returns the JSON proof string. `createHumanProofExtension` calls this internally.

```javascript theme={null}
import { signHumanProofChallengeEVM } from "@billionsnetwork/x402-human-proof-client";

const proofJson = await signHumanProofChallengeEVM(challenge, signer, "eip155:84532");
```

| Parameter   | Type                  | Description                                                                                |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------ |
| `challenge` | `HumanProofChallenge` | The `extensions["human-proof"]` object from the `402` response.                            |
| `signer`    | `EVMSigner`           | EVM signing interface.                                                                     |
| `chainId`   | `string`              | CAIP-2 chain ID to use (e.g. `"eip155:84532"`). Must exist in `challenge.supportedChains`. |

Returns: `Promise<string>` — a JSON-encoded string containing all CAIP-122 fields plus `address`, `signature`, `chainId`, and `type`.

Throws: `Error` if `chainId` is not found in `challenge.supportedChains` with type `eip191`.

### `extractHumanProofChallenge(paymentRequired)`

Extracts the human-proof extension object from a `402` response body. Returns `null` if no challenge is present — safe to call on any `paymentRequired` response.

```javascript theme={null}
import { extractHumanProofChallenge } from "@billionsnetwork/x402-human-proof-client";

const challenge = extractHumanProofChallenge(paymentRequired);
if (challenge) {
  console.log(challenge.info.nonce);
  console.log(challenge.supportedChains);
}
```

| Parameter         | Type                                       | Description                                                       |
| ----------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| `paymentRequired` | `{ extensions?: Record<string, unknown> }` | The `402` response body or any object with an `extensions` field. |

Returns: `HumanProofChallenge | null`

***

## Error Handling

### `MissingAttestationsError`

Thrown by `createHumanProofExtension` when the wallet doesn't hold one or more required attestations.

```javascript theme={null}
x402.onPaymentCreationFailure(async ({ error }) => {
  if (error instanceof MissingAttestationsError) {
    console.error(
      "You need to complete these attestations before accessing the discounted tier:",
      error.attestationRequirements,
      // [{ schemaId: "0xca354bee6dc5eded..." }]
    );
  }
});
```

| Property                  | Type                                    | Description                                               |
| ------------------------- | --------------------------------------- | --------------------------------------------------------- |
| `attestationRequirements` | `AttestationRequirement[] \| undefined` | One `{ schemaId: string }` entry per missing attestation. |

Expect this when one or more schemas in `challenge.info.requiredAttestations` are not held by the DID — either the user hasn't completed Billions Network registration yet, or the DID was derived from a different wallet than the one that holds the attestation.

***

### `isMaxUseExceededError`

Returns `true` when an HTTP error response has status `402` and the `payment-required` header contains `error: "max_use_exceeded"`.

```javascript theme={null}
try {
  response = await api.get(url);
} catch (err) {
  if (isMaxUseExceededError(err)) {
    disqualify(); // permanently skip discounted tiers for this selector
    response = await api.get(url); // retry - selector now picks standard pricing
  } else {
    throw err;
  }
}
```

Returns `boolean`. Compatible with axios, fetch, node-fetch, and similar.

***

## Environment Variables

The SDK itself reads no environment variables. The variables below are used by the example scripts (including the Quick Start above):

| Variable              | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `EVM_PRIVATE_KEY`     | `0x`-prefixed hex private key for the agent wallet.                      |
| `RESOURCE_SERVER_URL` | Base URL of the x402 resource server (default: `http://localhost:4021`). |
| `ENDPOINT_PATH`       | Path to the protected endpoint (default: `/weather`).                    |


# How It Works
Source: https://docs.billions.network/agents/identity-architecture

The linking flow, architecture, and demo behind the Verified Agent Identity skill.

<Steps>
  <Step title="Agent creates its DID">
    The agent generates its own DID locally using the [iden3 protocol](https://docs.iden3.io) — an open-source ZK identity framework that derives cryptographic identifiers from key pairs. Nothing goes on-chain at this point.
  </Step>

  <Step title="Agent shares a verification link">
    When asked to link its identity, the agent generates a verification link scoped to this specific human-agent pairing and shares it with the human owner.
  </Step>

  <Step title="Human verifies ownership in the Billions Web Wallet">
    The human opens the link in the Billions Web Wallet, generates a zero-knowledge Proof of Uniqueness and an auth proof, and submits them to the Relay Attestation Service.
  </Step>

  <Step title="Permanent attestation created on-chain">
    The Relay makes two on-chain calls on the Billions Network. First, the **Identity Verifier Contract** verifies the ZK proof and stores it against the user's DID — enforcing that one verified human maps to exactly one on-chain identity. Then, the **Attestation Registry Contract** creates a permanent on-chain attestation linking the verified human to the agent's DID.
  </Step>
</Steps>

The resulting attestation is permanent, public, and queryable by any third party to confirm agent ownership.

***

## Architecture

Five components carry the flow from a locally generated key pair to a public on-chain attestation:

```mermaid theme={null}
flowchart TB
    Agent["<b>AI Agent</b><br/>verified-agent-identity skill<br/>DID derived locally via iden3"]
    Human["<b>Human Owner</b><br/>Billions Web Wallet<br/>generates ZK Proof of Uniqueness + auth proof"]
    Relay["<b>Relay Attestation Service</b><br/>off-chain relay"]

    subgraph chain["Billions Network — on-chain"]
        Verifier["<b>Identity Verifier Contract</b><br/>verifies Proof of Uniqueness<br/>one human = one identity"]
        Registry["<b>Attestation Registry Contract</b><br/>permanent human-to-agent link"]
    end

    Agent -- "1 · sends verification link" --> Human
    Human -- "2 · submits proofs" --> Relay
    Relay -- "3 · verify Proof of Uniqueness" --> Verifier
    Relay -- "4 · create attestation" --> Registry
```

Reading the diagram in flow order:

1. **Verified Agent Identity skill** — runs on the agent. It derives the agent's DID from a local key pair and orchestrates the linking flow, starting by sending the human owner a verification link.
2. **Billions Web Wallet** — where the human proves who they are. It generates a zero-knowledge **Proof of Uniqueness** (proving the human is real and unique without revealing personal data) plus an auth proof, and submits both.
3. **Relay Attestation Service** — the off-chain bridge. It receives the proofs and turns them into two on-chain transactions.
4. **Identity Verifier Contract** — verifies the ZK proof on-chain and stores it against the human's DID. It is Sybil-resistant by design: one verified human maps to exactly one on-chain identity.
5. **Attestation Registry Contract** — writes the permanent, public attestation linking the verified human's identity to the agent's DID.

<iframe title="Verified Agent Identity — Architecture Walkthrough" />

***

## Demo

Watch the whole flow happen live: in a few minutes, an agent goes from having no identity at all to a permanent, publicly verifiable on-chain pairing with its human owner.

<iframe title="Verified Agent Identity — Live Demo" />

The demo uses **Billy**, an agentic bot on Telegram, built with the [OpenClaw](https://openclaw.ai) framework for building and deploying AI agents. The demo follows Billy through exactly the flow described in [How It Works](#how-it-works) above. A few details worth watching for:

* **Installation is a single chat message.**
* **The face scan happens once.** First-time users claim a Proof of Uniqueness credential in the Billions Web Wallet with a one-time face scan. The credential is stored in the wallet and reused for every future verification.
* **The result is checkable end to end.** After verification, Billy appears under **Verified Agents** in the user's wallet profile — and the last four characters of his DID (`V9HT`) match exactly what he shared in the Telegram chat.

***

## Under the Hood

Everything above happens automatically. The sections below document exactly what the skill does on disk and on-chain, for when you need the details.

<AccordionGroup>
  <Accordion title="How the skill runs">
    When installed, the skill adds a `scripts/` directory to the agent's workspace and runs `npm install` to set up dependencies.

    All cryptographic material is stored in `$HOME/.openclaw/billions/` (OpenClaw's data directory) — outside the agent's workspace — so identity data persists across sessions and agent restarts. The agent reads this directory on startup to load its default DID and private keys.

    When the agent receives a natural-language trigger (e.g. "link your identity to me"), the skill's instruction set maps it to the appropriate script, executes it as a subprocess, and returns the result to the conversation.
  </Accordion>

  <Accordion title="Pairing and attestation flow (tech spec)">
    When the human clicks the verification link, the Billions Web Wallet initiates the following sequence:

    1. **Auth proof** — a JWS token is generated, signed with the agent's private key, proving DID ownership.
    2. **Proof of Uniqueness** — a ZK proof is generated in the wallet, proving the human is a real, unique individual without revealing personal data.
    3. Both proofs are submitted to the **Relay Attestation Service**.
    4. The Relay calls the **Identity Verifier Contract** on the Billions Network — the ZK proof is verified on-chain and stored against the user's DID. This enforces uniqueness: one verified human maps to exactly one on-chain identity.
    5. The Relay calls the **Attestation Registry Contract** (ERC-8004, a standard for on-chain attestation registries) — a permanent on-chain attestation is written linking the verified human's DID to the agent's DID.

    The attestation is public, immutable, and queryable by any third party to confirm agent ownership.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<Card title="Installation" icon="download" href="/agents/identity-skill">
  Install the skill and link your agent's identity to you in two chat messages.
</Card>


# Verified Agent Identity
Source: https://docs.billions.network/agents/identity-overview

Give your AI agent a cryptographic identity with a verified human owner on the Billions Network.

## What is agent identity?

Every AI agent today runs without a real identity — just code executing somewhere, with no way to prove who owns it or is accountable for what it does.

## Verified Agent Identity

The **Verified Agent Identity** skill solves that: it gives any AI agent a decentralized identifier (DID) on the Billions Network and links it permanently and verifiably, on-chain, to a real human owner.

Once linked, the agent can prove it is operated by a real, unique human. Service providers get spam protection, and anyone can look up a public, tamper-proof record of who stands behind the agent — sybil resistance without asking the agent to give up its autonomy.

<Card title="GitHub" icon="github" href="https://github.com/BillionsNetwork/verified-agent-identity">
  BillionsNetwork/verified-agent-identity
</Card>

## Features

<CardGroup>
  <Card title="Identity Creation" icon="circle-plus">
    Give your agent its own DID — derived locally from a cryptographic key pair, no registry or sign-up required.
  </Card>

  <Card title="Identity Management" icon="list">
    List and manage multiple identities with default identity support.
  </Card>

  <Card title="Human-Agent Linking" icon="link">
    Link a human identity to an agent's DID through signed challenges.
  </Card>

  <Card title="x402 Discounted Pricing" icon="tag" href="/agents/overview">
    Human-owned agents unlock discounted pricing tiers on APIs protected by x402 Human Proof.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup>
  <Card title="How It Works" icon="diagram-project" href="/agents/identity-architecture">
    See the full linking flow, architecture diagram, and a live demo.
  </Card>

  <Card title="Installation" icon="download" href="/agents/identity-skill">
    Install the skill and link your agent's identity to you in two chat messages.
  </Card>
</CardGroup>


# Installation
Source: https://docs.billions.network/agents/identity-skill

Install and set up the Verified Agent Identity skill.

Setup takes two chat messages: one to install the skill, one to link the agent's identity to you. If you haven't yet, read the [overview](/agents/identity-overview) for what the skill does and how the linking flow works.

***

## Install the Skill

Ask your agent directly:

```plaintext theme={null}
Install the skill `npx clawhub@latest install verified-agent-identity`
```

<div>OR</div>

```plaintext theme={null}
Install the skill `npx skills add BillionsNetwork/verified-agent-identity`
```

<div>OR</div>

```plaintext theme={null}
Install the skill https://github.com/BillionsNetwork/verified-agent-identity
```

[clawhub](https://clawhub.ai) is the skill manager for OpenClaw-compatible agents, [skills.sh](https://skills.sh) is a universal skill registry for AI agents.

The agent installs the skill and sets everything up automatically — no manual configuration needed.

***

## Link Your Agent

Once installed, tell your agent to link its identity to you:

```plaintext theme={null}
Link your agent identity to me.
```

The agent will generate a verification link scoped to this specific human-agent pairing. Open it in the [Billions Web Wallet](https://wallet.billions.network), sign in, and hit **Verify** to complete the on-chain pairing. First-time users claim a Proof of Uniqueness credential with a one-time face scan; after that, the credential is reused for every future verification.

For a step-by-step explanation of what happens during the pairing, see [How It Works](/agents/identity-architecture#how-it-works).

***

## Verify It Worked

* Ask your agent to show its identity — it responds with its DID.
* Open your profile in the [Billions Web Wallet](https://wallet.billions.network) and check **Verified Agents** — your agent is listed there, and the last characters of its DID match what it showed you in chat.

The attestation is now on-chain — permanent, public, and verifiable by anyone.

***

## Learn More

<Card title="How It Works" icon="diagram-project" href="/agents/identity-architecture">
  See the full linking flow, architecture diagram, demo, and what the skill does under the hood.
</Card>


# Overview
Source: https://docs.billions.network/agents/overview

x402 Human Proof — differentiated pricing and spam protection for APIs serving humans and AI agents.

## What is x402?

The x402 protocol lets any API accept per-request payments from humans and agents alike — but by itself it can't tell the two apart.

## x402 Human Proof

The **x402 Human Proof** extension solves that: it adds a human identity verification layer on top of x402, giving providers the signal they need to apply differentiated pricing and protect against bots, scalpers, and spam.

With Human Proof, providers can offer discounted tiers, free trials, or premium access to verified humans and the agents they control — while keeping standard rates for unverified traffic, or blocking it entirely. The result is sybil and spam resistance without giving up x402's open, permissionless model.

<Info>
  For agents consuming Human Proof–protected APIs, the [**Verified Agent Identity skill**](/agents/identity-overview) handles the human-proof flow automatically — no SDK integration needed.
</Info>

***

## Demo

<Card title="Try the Live Demo" icon="arrow-up-right-from-square" href="https://x402.billions.network/">
  x402.billions.network — claim a tile on the canvas using your agent
</Card>

The demo shows the full x402 Human Proof flow end-to-end: an agent visits a protected resource, handles a `402 Payment Required` response, proves it is operated by a verified human, pays for access, and mints a tile as an NFT on a shared canvas — all in a single conversation.

### How the demo works

<Steps>
  <Step title="Visit the demo and claim a tile">
    The user visits the x402 demo website and clicks **Claim Tiles**. A prompt is displayed that can be copied and passed directly to any agent.
  </Step>

  <Step title="Agent sets up its identity">
    The agent visits the server. If the Verified Agent Identity skill is not yet installed, it installs or updates it and sets up its decentralized identity automatically. The agent may present its DID to the user at this point.
  </Step>

  <Step title="Server returns HTTP 402">
    The agent requests a tile from the server. The server denies access with an HTTP `402 Payment Required` response — because the agent has not yet proven it is operated by a verified human and has not paid.
  </Step>

  <Step title="Agent presents verification and payment options">
    The agent surfaces both requirements to the user: a verification link to pair the human with the agent (via the Billions Web Wallet), and the available payment options. Both must be satisfied to access the resource — this is the combined power of x402 and the x402 Human Proof extension.
  </Step>

  <Step title="User pairs with the agent on-chain">
    The user opens the verification link in the Billions Web Wallet. They confirm their Proof of Uniqueness credential and complete the pairing. A permanent ownership attestation is created on-chain, linking the user to their agent.
  </Step>

  <Step title="User selects a payment option">
    With the pairing confirmed, the user selects their preferred payment option from the options the agent presented.
  </Step>

  <Step title="Agent pays, customises, and submits the tile">
    The agent handles the payment, customises the tile with the user's details, and submits it to the server.
  </Step>

  <Step title="Tile is minted as an NFT">
    The server mints the tile as an NFT and places it on the shared canvas. The agent confirms the tile details with the user.
  </Step>
</Steps>

***

## Server SDK

`@billionsnetwork/x402-human-proof-server` is built on top of x402 and lets service providers add human-proof verification to any API service. Offer better pricing and spam protection to verified humans — and the verified agents they control — without touching existing routes or payment logic.

**Features:**

* **Drop-in setup.** One function call; existing routes and payment logic stay unchanged.
* **Tiered pricing.** A discounted rate for verified humans and their agents, a standard rate for everyone else — claiming the discount requires valid proof.
* **Usage caps and shared quotas.** Hard per-human limits, enforced atomically, with multiple routes able to share one usage pool. If a payment fails after verification, the usage count rolls back automatically.
* **Credential gating.** Require any combination of credentials or skills per route, beyond "is this a human".

<Card title="Server SDK Reference" icon="server" href="/agents/server">
  Full reference for `@billionsnetwork/x402-human-proof-server`
</Card>

***

## Client SDK

`@billionsnetwork/x402-human-proof-client` enables any HTTP client or custom agent to authenticate against APIs protected by the x402 Human Proof Server SDK.

Most agents won't need this SDK directly. The [**Verified Agent Identity skill**](/agents/identity-overview) is a general-purpose identity skill that pairs a verified human to their agent and supports the x402 human-proof flow out of the box — install it and the agent can transact on human-proof protected APIs without any code changes.

Reach for the client SDK only when you're building a custom agent that needs direct control over the x402 flow or when you're building any other HTTP client that needs to prove a verified-human identity to a protected API with the Billions human-proof server SDK.

**Features:**

* **Automatic signing.** Verification challenges are signed in the background; nothing to wire up per request.
* **Smart tier selection.** Picks the best tier the client qualifies for, falling back to standard pricing when the discount isn't available.
* **Usage cap recovery.** Detects when the usage limit is hit and retries at standard pricing.
* **Works with any EVM wallet.**

<Card title="Client SDK Reference" icon="browser" href="/agents/client">
  Full reference for `@billionsnetwork/x402-human-proof-client`
</Card>


# Server
Source: https://docs.billions.network/agents/server

Full reference for the x402 Human Proof Server SDK.

## Overview

`@billionsnetwork/x402-human-proof-server` adds human verification to any x402-enabled API — letting service providers verify that paying agents are backed by real humans, offer them better pricing, and make their servers spam and sybil resistant.

It enables API providers to:

* **Verify** that a paying agent is controlled by a unique, real human — not a bot or a sybil wallet — using Billions Network Proof-of-Uniqueness (PoU) attestations.
* **Offer discounted pricing** to agents backed by verified humans while keeping a standard price open to all payers.
* **Enforce per-identity usage caps** (`maxUse`) so a single human-backed agent cannot use a discounted price tier an unlimited number of times.
* **Gate additional capabilities** behind arbitrary attestation schemas beyond the basic ownership proof.

<Tip>
  **Already running an x402 server?** Adding human-proof takes a single function call — jump straight to Step 2 in the Setup section. <br />
  **New to x402?** It's an [open payment protocol](https://docs.x402.org/introduction) that lets any API accept per-request payments from AI agents and humans — no subscriptions or API keys needed. The Setup guide below covers both.
</Tip>

## How It Works

The full request lifecycle with human-proof enabled:

<img alt="x402 Human Proof request lifecycle" />

<Note>
  **Key insight:** Human-proof verification is layered on top of — not in place of — normal x402 payment verification. The facilitator still verifies the on-chain payment. The human-proof hook runs before that, as an additional gate on the selected payment option.
</Note>

If the selected `accepts` entry has no `requiredAttestations` in its `extra` field, the human-proof hook is a no-op and the payment proceeds normally.

## Installation

If your server doesn't use x402 yet, install the x402 packages first:

```bash theme={null}
npm install @x402/express @x402/evm @x402/core
```

Then install the human-proof package:

```bash theme={null}
npm install @billionsnetwork/x402-human-proof-server
```

<Info>
  Requires Node.js `>= 20.11.0`
</Info>

## Setup

Human-proof sits on top of x402 — it adds identity verification to an API that already accepts x402 payments. If you're new to x402, work through Step 1 first. If your server already accepts x402 payments, jump straight to Step 2.

### Step 1 — Make your server x402-compatible

[**x402**](https://docs.x402.org/introduction) is an open payment protocol built on the `402 Payment Required` HTTP status code. When a client hits a protected route without payment, the server returns a `402` with the accepted payment terms. The client pays and retries; the server settles on-chain and returns `200`.

Setting up x402 takes three things: a [**facilitator**](https://docs.x402.org/core-concepts/facilitator) (handles on-chain settlement), a **resource server** (coordinates x402 logic), and a **payment middleware** (gates your routes).

```typescript theme={null}
import express from "express";
import { x402ResourceServer, paymentMiddleware } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const app = express();

// 1. Connect to a facilitator that settles payments on-chain
const facilitator = new HTTPFacilitatorClient({ url: process.env.FACILITATOR_URL! });

// 2. Create the x402 resource server and register the EVM payment scheme
const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

// 3. Gate your routes with payment requirements
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [{
          scheme: "exact",
          price: "$0.01",
          network: "eip155:84532",
          payTo: process.env.EVM_ADDRESS!,
        }],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    server,
  ),
);

app.get("/weather", (_req, res) => {
  res.json({ weather: "sunny", temperature: 70 });
});

app.listen(4021);
```

<Note>
  For the full x402 documentation, see [docs.x402.org](https://docs.x402.org/introduction).
</Note>

### Step 2 — Add human-proof verification

With x402 in place, adding human-proof is a single function call plus two additions to your route config:

* **`configureHumanProofServer`** — registers the challenge generator and verification hook on the x402 server object.
* **A discounted `accepts` entry** — the second pricing tier, gated behind a PoU attestation.
* **`declareHumanProofExtension`** — tells the challenge generator what to embed in each `402` response for this route.

```typescript theme={null}
import {
  configureHumanProofServer,
  declareHumanProofExtension,
  DEFAULT_AGENT_OWNERSHIP_SCHEMA,
  type HumanProofEvent,
  paywallInstructions,
} from "@billionsnetwork/x402-human-proof-server";

// 1. Register human-proof on the x402 server (call this once, before any routes)
configureHumanProofServer(server, {
  onEvent: (event: HumanProofEvent) => {
    if (event.type === "human_verified")
      console.log(`Human ${event.humanId} verified`);
    if (event.type === "human_not_registered")
      console.warn(`Unregistered DID: ${event.did}`);
  },
});

// 2. Update your route config: add the discounted tier and the human-proof declaration
app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          // Standard tier - any payer
          {
            scheme: "exact",
            price: "$0.01",
            network: "eip155:84532",
            payTo: process.env.EVM_ADDRESS!,
          },
          // Discounted tier - verified humans only
          {
            scheme: "exact",
            price: "$0.006",
            network: "eip155:84532",
            payTo: process.env.EVM_ADDRESS!,
            extra: {
              requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
            },
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
        // 3. Attach the human-proof challenge declaration to this route
        extensions: {
          "human-proof": declareHumanProofExtension({
            statement: "By signing, you provide a human proof",
            expirationSeconds: 900,
          }),
        },
      },
    },
    server,
    {},                       // paymentMiddleware options - none needed
    paywallInstructions(),    // HTML shown to unpaid browser callers
  ),
);
```

That's it. Unverified callers pay `$0.01`; verified human-backed agents pay `$0.006`.

<Info>
  `paywallInstructions()` provides the default HTML page shown to browser users hitting a paid URL — it points them to the skill installation.
</Info>

<Note>
  To add per-human usage caps or a custom paywall page, see Usage Limits (maxUse) and Paywall HTML further down.
</Note>

### Complete Example

Here is the full server in one file, combining both steps:

```typescript theme={null}
import { config } from "dotenv";
import express from "express";
import { x402ResourceServer, paymentMiddleware } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";
import {
  configureHumanProofServer,
  declareHumanProofExtension,
  DEFAULT_AGENT_OWNERSHIP_SCHEMA,
  type HumanProofEvent,
  paywallInstructions,
} from "@billionsnetwork/x402-human-proof-server";

config();

const app = express();

const facilitator = new HTTPFacilitatorClient({ url: process.env.FACILITATOR_URL! });

const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

configureHumanProofServer(server, {
  onEvent: (event: HumanProofEvent) => {
    if (event.type === "human_verified")
      console.log(`Human ${event.humanId} verified`);
    if (event.type === "human_not_registered")
      console.warn(`Unregistered DID: ${event.did}`);
  },
});

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.01",
            network: "eip155:84532",
            payTo: process.env.EVM_ADDRESS!,
          },
          {
            scheme: "exact",
            price: "$0.006",
            network: "eip155:84532",
            payTo: process.env.EVM_ADDRESS!,
            extra: {
              requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
            },
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
        extensions: {
          "human-proof": declareHumanProofExtension({
            statement: "By signing, you provide a human proof",
            expirationSeconds: 900,
          }),
        },
      },
    },
    server,
    {},
    paywallInstructions(),
  ),
);

app.get("/weather", (_req, res) => {
  res.json({ weather: "sunny", temperature: 70 });
});

app.listen(4021, () => console.log("Server running on :4021"));
```

## Testing Your Integration

The easiest way to test the integration end-to-end is through the [Verified Agent Identity skill](/agents/identity-overview).
Install it onto your agent and the agent becomes capable of the human-proof flow. Chat with the agent to complete the verification and pairing, then ask it to access your local server (`http://localhost:4021/weather`) — a successful response confirms the agent is recognized as backed by a verified human and the flow works as intended.

## Core Concepts

### x402 Payment Protocol

[x402](https://docs.x402.org/introduction) is an open HTTP payment protocol built on the `402 Payment Required` status code. `@billionsnetwork/x402-human-proof-server` extends the standard x402 flow by embedding a CAIP-122 challenge in the `402` response and verifying a signed proof of identity in the `X-PAYMENT` extensions before settlement.

### Proof of Uniqueness (PoU)

Billions Network issues Proof-of-Uniqueness attestations that cryptographically bind an agent to a verified human. The attestation is an on-chain record with a schema ID and a **nullifier** — a privacy-preserving identifier that uniquely represents the human without revealing their identity.

A PoU attestation binds an agent to a verified human. A single human can authorize multiple agents — all of them resolve to the same `humanId`, so quota (`maxUse`) and verification apply per human, not per agent.

The server SDK uses the attestation schema to verify that a wallet is backed by a registered human, and uses the nullifier as `humanId` for per-human usage counting.

### CAIP-122 Signed Messages

CAIP-122 defines chain-agnostic message signing ("Sign-In With X"). The SDK supports EVM / `eip191` (Sign-In with Ethereum). The signed payload includes:

`domain`, `uri`, `version`, `nonce`, `issuedAt`, `expirationTime` (optional), `resources`, `chainId`, `type`, `address`, `signature`, and `requiredAttestations`.

### Decentralized Identifiers (DID)

A DID is derived from the agent's EVM address using the Billions method:

```
did:iden3:billions:main:<address-derived-identifier>
```

This DID is used to query the Billions Network attestations API and look up the human registry. DIDs are computed deterministically — the SDK handles this conversion internally.

## Configuration Reference

### Environment Variables

| Variable           | Required | Default | Description                                                                                                     |
| ------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `EVM_ADDRESS`      | Yes      | —       | Your wallet address that receives payments                                                                      |
| `FACILITATOR_URL`  | Yes      | —       | x402 facilitator endpoint — see [facilitator docs](https://docs.x402.org/core-concepts/facilitator) for options |
| `MOCK_FACILITATOR` | No       | `false` | Set to `true` to skip real on-chain verification (local dev only)                                               |
| `PORT`             | No       | `4021`  | HTTP port to listen on                                                                                          |

### `configureHumanProofServer(server, options?)`

The recommended one-call setup. Registers the extension, wires all lifecycle hooks, and optionally adds rollback hooks when storage is provided.

```javascript theme={null}
import { configureHumanProofServer } from "@billionsnetwork/x402-human-proof-server";

configureHumanProofServer(server, options);
```

Internally calls:

* `server.registerExtension(createHumanProofExtension(extensionOptions))` — adds the CAIP-122 challenge generator to `402` responses.
* `server.onBeforeVerify(createVerifyHumanProofHook({...}))` — verifies the signed proof before payment settlement.

If `storage` is provided:

* `onAfterVerify` — rolls back usage on facilitator failure.
* `onVerifyFailure` — rolls back on hook error.
* `onSettleFailure` — rolls back if on-chain settlement fails.

**Options:**

| Option             | Type                               | Default      | Description                                            |
| ------------------ | ---------------------------------- | ------------ | ------------------------------------------------------ |
| `extensionOptions` | `CreateHumanProofExtensionOptions` | `{}`         | Options forwarded to `createHumanProofExtension`       |
| `verifier`         | `PoUVerifier`                      | auto-created | Custom verifier instance. Overrides `verifierOptions`. |
| `verifierOptions`  | `PoUVerifierOptions`               | `{}`         | Options passed to the default `createPoUVerifier`      |
| `onEvent`          | `(event: HumanProofEvent) => void` | —            | Callback for all lifecycle events                      |
| `storage`          | `HumanUsageStorage`                | —            | Required when any `accepts` entry sets `extra.maxUse`  |

### `declareHumanProofExtension(options?)`

Attaches human-proof rules to a specific route's `extensions` block. This is a declaration only — it tells the challenge generator what to include in the CAIP-122 message for that route.

```javascript theme={null}
import { declareHumanProofExtension } from "@billionsnetwork/x402-human-proof-server";

extensions: {
  "human-proof": declareHumanProofExtension({
    statement: "By signing, you provide a human proof",
    expirationSeconds: 900,
  }),
},
```

**Options:**

| Option              | Type                 | Default                  | Description                                                                                                                                                          |
| ------------------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `statement`         | `string`             | —                        | Human-readable text shown in the SIWE message. Helps users understand what they are signing.                                                                         |
| `expirationSeconds` | `number`             | —                        | How long the challenge is valid in seconds. After this window, the client must request a fresh `402`. Recommended: `900` (15 min). If omitted, no expiration is set. |
| `resourceUri`       | `string`             | Request URL              | Override the URI embedded in the CAIP-122 message. The server validates that the signed URI matches the resource being accessed.                                     |
| `domain`            | `string`             | Hostname of resource URL | Override the domain in the SIWE message. Defaults to `new URL(resourceUri).hostname`.                                                                                |
| `version`           | `string`             | `"1"`                    | CAIP-122 message version.                                                                                                                                            |
| `network`           | `string \| string[]` | All accepted networks    | Restrict the `supportedChains` in the challenge to specific CAIP-2 networks.                                                                                         |

***

## Tiered Pricing

Human-proof is configured per route — each endpoint in your `paymentMiddleware` config can have its own pricing model independently. `configureHumanProofServer` registers the hook globally, but the hook only activates on routes where `requiredAttestations` is present.

### Configuration Patterns

<AccordionGroup>
  <Accordion title="Pattern 1 — Attestation optional (discount for verified humans)">
    Any client can access the route. Verified humans pay less; everyone else pays full price. This is the most common setup.

    ```javascript theme={null}
    accepts: [
      { scheme: "exact", price: "$0.01", ... },            // any payer
      { scheme: "exact", price: "$0.006", ..., extra: {    // PoU holders get a discount
        requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
      }},
    ],
    extensions: { "human-proof": declareHumanProofExtension({ ... }) },
    ```
  </Accordion>

  <Accordion title="Pattern 2 — Attestation required (verified humans only)">
    Only PoU-verified clients can access the route. Clients without the attestation are rejected with `402`.

    ```javascript theme={null}
    accepts: [
      { scheme: "exact", price: "$0.006", ..., extra: {    // PoU required - no fallback
        requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
      }},
    ],
    extensions: { "human-proof": declareHumanProofExtension({ ... }) },
    ```
  </Accordion>

  <Accordion title="Pattern 3 — No human-proof (plain x402)">
    Human-proof is bypassed entirely for this route. The hook never runs regardless of `configureHumanProofServer` being called.

    ```javascript theme={null}
    accepts: [
      { scheme: "exact", price: "$0.01", ... },            // any payer, no verification
    ],
    // no extensions block
    ```
  </Accordion>
</AccordionGroup>

### `extra` Fields on `accepts` Entries

The `accepts` array on a route can contain multiple payment options. The human-proof system layers on top to gate access to specific tiers.

```javascript theme={null}
accepts: [
  // Tier 1: Standard - any paying agent
  {
    scheme: "exact",
    price: "$0.01",
    network: "eip155:84532",
    payTo: evmAddress,
  },

  // Tier 2: Discounted - verified human-backed agents only
  {
    scheme: "exact",
    price: "$0.006",
    network: "eip155:84532",
    payTo: evmAddress,
    extra: {
      requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
      maxUse: 10,
      scope: "my_resource_identifier",
    },
  },
],
```

**How tier selection works:** the server does not choose — the client selects a tier by constructing their payment payload for a specific `accepts` entry. The server enforces it:

* If the client chose Tier 1 (no `requiredAttestations` in `extra`), the hook is skipped entirely.
* If the client chose Tier 2 (has `requiredAttestations`), the hook verifies the proof and checks attestations. If verification fails, the payment is rejected with `402`.

| Field                  | Type       | Description                                                                                                                                                                                                                              |
| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requiredAttestations` | `string[]` | Schema IDs the client's DID must hold. The first entry is the "ownership schema" checked via `lookupHuman`. Subsequent entries are checked via `hasAttestation`.                                                                         |
| `maxUse`               | `number`   | Maximum times a unique human can use this tier. Requires `storage` to be configured. Must be a positive integer.                                                                                                                         |
| `scope`                | `string`   | Namespaces the usage counter. Two routes sharing the same scope share a quota. Defaults to the resource URL from the client's payment payload — set an explicit value like `"weather_report"` for a stable, predictable quota namespace. |

***

## Usage Limits (`maxUse`)

`maxUse` lets you offer a discounted price up to N times per agent, then fall back to standard pricing automatically.

**Server setup:**

```javascript theme={null}
configureHumanProofServer(server, {
  storage, // required - any HumanUsageStorage implementation
  onEvent: (event) => {
    if (event.type === "max_use_exceeded") {
      console.warn(
        `Human ${event.humanId} hit limit ${event.maxUse} on ${event.resource}`
      );
    }
  },
});
```

**Route setup:**

```javascript theme={null}
extra: {
  requiredAttestations: [DEFAULT_AGENT_OWNERSHIP_SCHEMA],
  maxUse: 1,
  scope: "weather_report",
}
```

**What happens when the limit is reached:**

1. `storage.incrementIfBelow(humanId, maxUse, scope)` returns `null`.
2. The hook returns `{ abort: true, reason: "max_use_exceeded" }`.
3. The server sends `402` with `error: "max_use_exceeded"` in the payment-required header.
4. On the client, `isMaxUseExceededError(err)` returns `true` and `disqualify()` forces the selector to skip discounted options on the next retry. Both helpers are part of the client SDK — see the [Client SDK](/agents/client) for details.

**Shared quota across routes:** two routes can share a single usage pool by using the same `scope` key. A human's uses are counted across both routes combined.

```javascript theme={null}
"GET /weather": {
  accepts: [..., { extra: { requiredAttestations: [...], maxUse: 2, scope: "forecast_pool" } }],
  extensions: { "human-proof": declareHumanProofExtension({ ... }) },
},
"GET /forecast": {
  accepts: [..., { extra: { requiredAttestations: [...], maxUse: 2, scope: "forecast_pool" } }],
  extensions: { "human-proof": declareHumanProofExtension({ ... }) },
},
```

With `maxUse: 2` and `scope: "forecast_pool"`, a human who calls `/weather` once and `/forecast` once has consumed both uses — the next request to either route returns `max_use_exceeded`.

***

## Event System

Register an `onEvent` callback to observe verification lifecycle events:

```typescript theme={null}
onEvent: (event: HumanProofEvent) => {
  switch (event.type) {
    case "human_verified":
      // Real human confirmed - safe to log analytics, issue rewards, etc.
      console.log(event.humanId, event.verifiedAt, event.humanDid, event.resource);
      break;

    case "human_not_registered":
      // DID not in PoU registry - client likely needs to complete attestation
      console.warn(event.did, event.resource);
      break;

    case "max_use_exceeded":
      // Human hit their usage cap for this scope
      console.warn(event.humanId, event.maxUse, event.resource);
      break;
  }
}
```

***

## Storage: `HumanUsageStorage`

`HumanUsageStorage` is required when any route uses `extra.maxUse`. It tracks how many times each human-backed agent has used a given priced tier.

```typescript theme={null}
interface HumanUsageStorage {
  incrementIfBelow(humanId: string, maxUse: number, scope: string): Promise<number | null>
  decrementIfAboveZero(humanId: string, scope: string): Promise<number | null>
}
```

* **`incrementIfBelow`** — Increment the counter for `(humanId, scope)` only if it is strictly below `maxUse`. Return the new count, or `null` if the limit is already reached.
* **`decrementIfAboveZero`** — Decrement the counter only if it is above zero. Return the new count, or `null` if no decrement was performed. Called by the rollback hooks when a payment fails after the counter was already incremented.

<Warning>
  **`incrementIfBelow` must be a single atomic operation.** Without atomicity, two concurrent requests from the same human can both pass the limit check and both increment the counter, effectively doubling the allowed usage. A non-atomic check-then-increment is a race condition that will silently bypass `maxUse` under load.
</Warning>

### `InMemoryHumanUsageStorage` (development)

<Note>
  An in-memory implementation is available for local development (`InMemoryHumanUsageStorage` from the examples directory), but it must not be used in production — state is lost on restart and is not shared across server instances.
</Note>

### Production Storage

For production, implement `HumanUsageStorage` backed by a persistent, shared store. The key constraint is atomicity on `incrementIfBelow`.

* **Redis** — Use a Lua script that performs the `GET` and conditional `INCR` as a single atomic operation. The key format is typically `human_usage:{humanId}:{scope}`. Set a TTL (e.g. 30 days) so counters self-expire. Lua scripts in Redis execute atomically on a single shard, making them the right tool here.
* **SQL (PostgreSQL / MySQL)** — Use an `INSERT ... ON CONFLICT DO UPDATE SET count = count + 1 WHERE count < maxUse RETURNING count` pattern. A single statement with a `WHERE` clause is atomic within a transaction and prevents the race condition without needing an explicit lock. Create a table with `(human_id, scope)` as the primary key and a `count` column.
* **Distributed systems** — If you run multiple server instances behind a load balancer, the storage backend must be shared (not per-process). A single Redis instance or a common database satisfies this; a per-process in-memory map does not.

***

## Rollback Hooks

When using `configureHumanProofServer` with a `storage`, three rollback hooks are automatically registered to keep usage counts consistent with successfully settled payments:

| Hook              | Trigger                                       | Action                                       |
| ----------------- | --------------------------------------------- | -------------------------------------------- |
| `onAfterVerify`   | Facilitator returns `isValid: false`          | Decrements counter — payment was not settled |
| `onVerifyFailure` | An error is thrown during the verify step     | Decrements counter                           |
| `onSettleFailure` | On-chain settlement fails after verify passed | Decrements counter                           |

This ensures an agent's usage quota — tied to a verified human — is only consumed by successfully completed payments. A failed transaction does not burn quota.

To register rollback hooks manually (when not using `configureHumanProofServer`):

```javascript theme={null}
import {
  createAfterVerifyFailureRollbackHook,
  createVerifyFailureRollbackHook,
  createSettleFailureRollbackHook,
} from "@billionsnetwork/x402-human-proof-server";

const verifier = createPoUVerifier();
server.onAfterVerify(createAfterVerifyFailureRollbackHook({ storage, verifier }));
server.onVerifyFailure(createVerifyFailureRollbackHook({ storage, verifier }));
server.onSettleFailure(createSettleFailureRollbackHook({ storage, verifier }));
```

***

## Paywall HTML

When an unpaid request arrives, the server can return a custom HTML page. `paywallInstructions()` provides a default page that directs agents to install the identity skill, which enables agents to understand how to sign human-proof challenges, select the right payment tier, and complete the full x402 flow.

```javascript theme={null}
import { paywallInstructions } from "@billionsnetwork/x402-human-proof-server";

// Default HTML - pass as the 4th argument to paymentMiddleware
paymentMiddleware({ ... }, server, {}, paywallInstructions());

// Custom HTML
paymentMiddleware({ ... }, server, {}, paywallInstructions("<html><body>Pay to access.</body></html>"));
```

The default page links to the identity skill at clawhub.ai and skills.sh.

***

## Low-Level Helpers

### `createHumanProofExtension`

Lower-level function that creates the `ResourceServerExtension` object. `configureHumanProofServer` calls this internally. Use it directly if you need to register the extension manually with `server.registerExtension(...)`.

```javascript theme={null}
import { createHumanProofExtension } from "@billionsnetwork/x402-human-proof-server";

server.registerExtension(createHumanProofExtension({
  agentOwnershipSchema: "0xcustom...",
}));
```

**Options:**

| Option                 | Type     | Default                          | Description                                                                                                                                    |
| ---------------------- | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentOwnershipSchema` | `string` | `DEFAULT_AGENT_OWNERSHIP_SCHEMA` | Must match the schema configured in your `PoUVerifier`. If you use a custom registry, pass the same schema ID here and in `createPoUVerifier`. |

What it generates inside each `402` response:

```json theme={null}
{
  "human-proof": {
    "info": {
      "domain": "localhost",
      "uri": "http://localhost:4021/weather",
      "version": "1",
      "nonce": "1ab399792f4c9b05ac916fdf4fd9ac6c",
      "issuedAt": "2026-04-22T11:18:52.428Z",
      "expirationTime": "2026-04-22T11:33:52.428Z",
      "statement": "By signing, you provide a human proof",
      "resources": ["http://localhost:4021/weather"],
      "requiredAttestations": [
        "0xca354bee6dc5eded165461d15ccb13aceb6f77ebbb1fd3fe45aca686097f2911"
      ]
    },
    "supportedChains": [
      { "chainId": "eip155:84532", "type": "eip191" }
    ]
  }
}
```

<Note>
  The `nonce` is generated fresh with `randomBytes(16)` on every `402` response, making each challenge unique and replay-proof.
</Note>

### `createVerifyHumanProofHook`

Creates the `onBeforeVerify` hook function. `configureHumanProofServer` calls this internally. Use it directly for fine-grained lifecycle control.

```javascript theme={null}
import { createVerifyHumanProofHook } from "@billionsnetwork/x402-human-proof-server";

server.onBeforeVerify(
  createVerifyHumanProofHook({
    verifierOptions: {
      attestationsApiBaseUrl: "https://my-custom-api.example.com/attestations",
    },
    storage,
    onEvent,
  })
);
```

If `requiredAttestations` is absent or empty on the selected `accepts` entry, the hook returns immediately and payment proceeds normally. Otherwise it validates CAIP-122 fields, verifies the EVM signature, resolves the DID against the Billions Network registry, checks any additional attestation schemas, and enforces `maxUse` if configured.

| Option            | Type                               | Default      | Description                                               |
| ----------------- | ---------------------------------- | ------------ | --------------------------------------------------------- |
| `verifier`        | `PoUVerifier`                      | auto-created | Custom verifier. Takes precedence over `verifierOptions`. |
| `verifierOptions` | `PoUVerifierOptions`               | `{}`         | Options passed to the default `createPoUVerifier`.        |
| `onEvent`         | `(event: HumanProofEvent) => void` | —            | Lifecycle event callback.                                 |
| `storage`         | `HumanUsageStorage`                | —            | Required when `extra.maxUse` is used on any route.        |

### `createPoUVerifier`

Creates the default Proof-of-Uniqueness verifier that queries the Billions Network explorer API.

```javascript theme={null}
import { createPoUVerifier } from "@billionsnetwork/x402-human-proof-server";

const verifier = createPoUVerifier({
  attestationsApiBaseUrl: "https://my-api.example.com/v1/attestations",
  agentOwnershipSchema: "0xcustom...",
});
```

Queries the attestations API for the DID, takes the most recent record, then resolves `record.fromId` via the nullifier API to return `{ humanId: nullifier, verifiedAt: ISO8601 }`.

| Option                   | Type                                         | Default                             | Description                                                                   |
| ------------------------ | -------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
| `agentOwnershipSchema`   | `string`                                     | `DEFAULT_AGENT_OWNERSHIP_SCHEMA`    | Schema ID for human registration lookup.                                      |
| `attestationsApiBaseUrl` | `string`                                     | `DEFAULT_ATTESTATIONS_API_BASE_URL` | Attestations REST API base URL.                                               |
| `nullifierApiBaseUrl`    | `string`                                     | `DEFAULT_NULLIFIER_API_BASE_URL`    | Nullifier REST API base URL.                                                  |
| `hasAttestation`         | `(did, chainId, schema) => Promise<boolean>` | Explorer API                        | Override attestation presence check. Useful for testing or custom registries. |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="invalid_signature even though the client signed correctly">
    The most common cause is a URI mismatch. The CAIP-122 message embeds the resource URI at signing time, and the server validates that it matches the actual request URL. Check that the `uri` in the proof exactly matches `http(s)://your-host/your-path` — trailing slashes, port numbers, and query strings all matter.
  </Accordion>

  <Accordion title="not_registered for a DID that should be registered">
    The server calls `lookupHuman`, which requires both an attestation record and a valid nullifier via the nullifier API. An attestation existing on the explorer is not enough — `fromId` must be present on the attestation record and the nullifier API must return a result for it. Verify both by checking the Billions Network explorer directly for your DID.
  </Accordion>

  <Accordion title="message_expired immediately after signing">
    This usually means significant clock skew between the client and server. The `expirationTime` is computed from the server's clock at `402` generation time. If the client's clock is far behind the server's, the message may expire before the client retries. Check NTP sync on both sides.
  </Accordion>

  <Accordion title="misconfigured_max_use_storage error">
    A route has `extra.maxUse` set but no `storage` was passed to the hook. Pass a storage implementation to `configureHumanProofServer` or `createVerifyHumanProofHook`.
  </Accordion>

  <Accordion title="max_use_exceeded on the first request">
    The counter is per `(humanId, scope)`. If the same human-backed agent previously used the discounted tier (even in a previous server session, if using persistent storage), their counter is already at the limit. Either increase `maxUse`, change the `scope` key, or flush the counter in your storage backend.
  </Accordion>

  <Accordion title="Human-proof check fires even though I didn't set requiredAttestations">
    The hook only runs when `context.requirements?.extra?.requiredAttestations` is non-empty. If the hook is running unexpectedly, the client is selecting an `accepts` entry that has `requiredAttestations` in its `extra`. Check which payment option the client is choosing.
  </Accordion>
</AccordionGroup>

***

## Error Reference

These values appear in the `reason` field when the hook aborts, and in the `error` field of the x402 payment-required header returned to the client.

| Reason                               | When it occurs                                                                                        |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `missing_header`                     | The payment payload has no `extensions["human-proof"]` field                                          |
| `invalid_header`                     | The proof is not valid JSON or is missing required fields (`address`, `signature`, `chainId`, `type`) |
| `invalid_message`                    | CAIP-122 fields are malformed — bad URI, missing nonce, unparseable date                              |
| `resource_mismatch`                  | The `uri` in the signed message does not match the resource URL being requested                       |
| `message_expired`                    | `expirationTime` is in the past                                                                       |
| `invalid_signature`                  | Signature recovery produced a different address than claimed                                          |
| `not_registered`                     | The DID derived from the signing address is not found in the PoU registry                             |
| `missing_required_attestation`       | A schema in `requiredAttestations` beyond the ownership schema is not held by the DID                 |
| `verifier_cannot_check_attestations` | Custom verifier does not implement `hasAttestation` but extra schemas are required                    |
| `invalid_max_use_value`              | `extra.maxUse` is present but not a positive finite integer                                           |
| `misconfigured_max_use_storage`      | `extra.maxUse` is set but no `storage` was passed to the hook                                         |
| `max_use_exceeded`                   | Entity (human-backed agent / verified human) has used all allocated uses for this scope               |


# Login with Billions
Source: https://docs.billions.network/billions-wallet/login-with-billions

Enable secure and decentralized authentication by leveraging the Billions Network.

## Overview

Enables applications to let users sign in seamlessly using their Decentralized Identifiers (DIDs).
Think of it as "Login with Google" — but **trustless, privacy-preserving, and self-sovereign**.

## Key Capabilities

* **Authenticates DID Ownership**: Authenticates users by cryptographically proving ownership of their DID
* **Enables Trustless Authentication**: Removes reliance on centralized identity providers.
* **Delivers a Familiar Web2 Experience**: Sign-in feels like any social login — the user clicks a button and approves in their wallet, with no passwords or seed phrases to manage.

## Authentication Flow

The **Login with Billions** process verifies user identity through DID ownership.

<Steps>
  <Step title="Initiate Sign-In">
    The user selects **Login with Billions** in the application. This triggers a backend call to `/api/sign-in`, which creates a new authentication request session.
  </Step>

  <Step title="Open Billions Wallet">
    The frontend takes the authentication request, encodes it in Base64, and embeds it into a [Universal Link](https://hackmd.io/@0xpulkit/billions-universal-link). This link opens the **Billions Wallet**, prompting the user to authenticate.
  </Step>

  <Step title="User Approves">
    The user approves the sign-in in the Billions Wallet. The wallet generates a `signed JWZ` (JSON Web Zero-knowledge) token — a verifiable proof of DID ownership.
  </Step>

  <Step title="Wallet Posts to Callback">
    The wallet sends a POST request to your backend `/api/callback` endpoint containing the `sessionId` and the signed JWZ token.
  </Step>

  <Step title="Backend Verifies the JWZ">
    Your backend verifies the JWZ token using the **Billions Verifier**, confirming the authenticity of the user’s DID.
  </Step>

  <Step title="Session Created">
    Upon successful verification, the user’s DID is confirmed. Create or update their session in your database — the DID acts as a persistent identity for all future sign-ins.
  </Step>

  <Step title="Access Granted">
    Your application recognizes the user, grants access, and can use the verified DID for personalized or gated experiences.
  </Step>
</Steps>

***

## Setup Instructions

Before you begin, ensure the following environment requirements are met:

### Prerequisites

* Public URL for callbacks (use [ngrok](https://ngrok.com/) for local development)

### Example Repository

The steps below walk through the [reference implementation](https://github.com/0xPolygonID/tutorial-examples/tree/main/login-with-billions) — clone it to follow along. The code snippets on this page are its `index.js`, and the repo includes the `./static` frontend used in the testing steps.

### 1. Server Configuration

Sets up Express server with required middleware and routes for handling authentication requests and callbacks.

```javascript theme={null}
// index.js
const path = require("path");
const express = require("express");
const { auth, resolver } = require("@iden3/js-iden3-auth");
const getRawBody = require("raw-body");
const cors = require('cors');

const app = express();
const port = 8080;

app.use(express.static("./static"));
app.use(cors());

// Session storage for auth requests
const requestMap = new Map();

// Routes
app.get("/api/sign-in", getAuthRequest);
app.post("/api/callback", callback);

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});
```

<Tip>
  **Testing Tip:** Use the sample frontend in `./static` to test Universal Link handling and callback processing.
  When moving to production, update URLs, enable HTTPS, and use environment variables for configuration.
</Tip>

### 2. Authentication Request Handler

Generates basic authentication requests with empty scope and stores them with unique session IDs for later verification.

```javascript theme={null}
async function getAuthRequest(req, res) {
  try {
    // Configuration - Update these for your setup
    const hostUrl = " Your public URL";
    const callbackURL = "/api/callback";
    const verifier_did = "did:iden3:billions:main:2qQ68JkRcf3xrHPQPWZei3YeVzHPP58wYNxx2mEouR"; // Your verifier DID

    // Generate unique session
    const sessionId = Date.now();
    const uri = `${hostUrl}${callbackURL}?sessionId=${sessionId}`;

    // Create basic auth request (no proofs required)
    const request = auth.createAuthorizationRequest(
      "Basic Sign In", // Reason for authentication
      verifier_did,        // Your verifier DID
      uri             // Callback URL
    );

    request.body.scope = [];

    // Store for later verification
    requestMap.set(`${sessionId}`, request);

    console.log(`Created basic auth request for session: ${sessionId}`);
    return res.status(200).json(request);

  } catch (error) {
    console.error("Error creating auth request:", error);
    return res.status(500).json({ error: "Failed to create auth request" });
  }
}
```

<Info>
  **Get Your Verifier DID:** Sign in to your [Billions Wallet](https://wallet.billions.network/) and copy your profile DID to use during setup.
</Info>

<Accordion title="How does getAuthRequest connect to the Billions Wallet?">
  This is where [**Universal Links**](https://hackmd.io/@0xpulkit/billions-universal-link) come into play. Your frontend takes the auth request returned by `getAuthRequest()`, encodes it in Base64, and embeds it into a Universal Link, which redirects the user to the Billions Wallet. The wallet processes the request, prompts the user to sign, and then posts a signed JWZ (JSON Web Zero-knowledge) token to your callback endpoint. That JWZ is what your backend verifies to confirm DID ownership — delivering a seamless login flow across web and mobile.

  **Example link format:**

  ```text theme={null}
  https://wallet.billions.network/#i_m=<base64_encoded_auth_request>
  ```

  * **Base URL**: `https://wallet.billions.network/` — Billions Wallet endpoint
  * **Fragment**: `#i_m=` — parameter carrying the Base64-encoded auth request
</Accordion>

### 3. Verification Callback Handler

Receives JWZ token as a callback, validates them against stored authentication requests, and confirms user DID ownership.

```javascript theme={null}
async function callback(req, res) {
  try {
    // 1. Extract session and token
    const sessionId = req.query.sessionId;
      
    if (!sessionId) {
      return res.status(400).json({ error: "Session ID is required" });
    }

    const raw = await getRawBody(req);
    const tokenStr = raw.toString().trim();
      
    if (!tokenStr) {
      return res.status(400).json({ error: "Token is required" });
    }

    // 2. Setup blockchain resolvers
    const resolvers = {
      ["billions:main"]: new resolver.EthStateResolver(
        "https://rpc-mainnet.billions.network",
        "0x3C9acB2205Aa72A05F6D77d708b5Cf85FCa3a896"
      )
    };

    // 3. Retrieve stored auth request
    const authRequest = requestMap.get(`${sessionId}`);
    if (!authRequest) {
      return res.status(400).json({
        error: "Invalid session ID or session expired"
      });
    }

    // 4. Initialize verifier
    const verifier = await auth.Verifier.newVerifier({
      stateResolver: resolvers,
      ipfsGatewayURL: "https://ipfs.io",
    });

    // 5. Verify authentication
    const opts = {
      AcceptedStateTransitionDelay: 5 * 60 * 1000, // 5 minutes
    };

    const authResponse = await verifier.fullVerify(tokenStr, authRequest, opts);

    // 6. Clean up and respond
    requestMap.delete(`${sessionId}`);

    console.log(`Authentication successful for session: ${sessionId}`);
    console.log("User DID:", authResponse.from);

    return res.status(200).json({
      success: true,
      message: "Basic authentication successful",
      userDID: authResponse.from,
      timestamp: new Date().toISOString(),
      sessionId: sessionId
    });

  } catch (error) {
    console.error("Authentication error:", error);
    return res.status(500).json({
      error: "Authentication failed",
      details: error.message
    });
  }
}
```

You’ve successfully verified DID ownership.

To turn this into a complete login, store user session details by their DID in your database. The DID acts as a persistent identity, allowing your app to recognize returning users.

When a user logs in again with the same Billions Wallet, they’ll present the same DID, letting your application instantly identify them and deliver the right personalized experience — decentralized, secure, and private.

### Testing Steps

1. **Visit your app:** `http://localhost:8080`
2. **Test universal link:** Click "Login with Billions" button

You can test the full authentication loop — from generating the auth request to verifying the DID — ensuring your app correctly recognizes verified users.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The callback endpoint never fires">
    The wallet POSTs the JWZ token to your `/api/callback` endpoint from outside your machine — so `hostUrl` must be a **publicly reachable URL**, not `localhost`. For local development, run [ngrok](https://ngrok.com/) and use the ngrok HTTPS URL as `hostUrl`. If the callback still doesn't arrive, confirm the auth request's callback URI includes the `sessionId` query parameter.
  </Accordion>

  <Accordion title="&#x22;Invalid session ID or session expired&#x22;">
    Auth requests are stored in an in-memory `Map`, so **restarting the server clears all pending sessions** — any link generated before the restart will fail. Each session is also deleted after its first callback (`requestMap.delete`), so a verification link can't be replayed. In both cases, start a fresh sign-in to generate a new auth request.
  </Accordion>
</AccordionGroup>

***

## Going Further: Beyond Basic Login

Once DID-based login is in place, the same identity can power other authentication experiences — crypto wallet sign-ins, verification against Billions credentials, or 2FA — all anchored to a single decentralized identity.


# Mobile Wallet
Source: https://docs.billions.network/billions-wallet/mobile-wallet

A privacy-first identity wallet for iOS and Android — manage credentials, generate zero-knowledge proofs, and verify your identity on the go.

## Overview

The Mobile Wallet puts the same identity in your pocket. The iOS and Android apps handle credential management, issuer and verifier authentication, and on-device zero-knowledge proof generation, so you can verify who you are wherever you go — no browser, no intermediaries.

<Info>
  On mobile, ZK circuit files are downloaded to the device and proof generation happens fully on-device. No personal data leaves the user's hardware during the proof generation process.
</Info>

## Download

<CardGroup>
  <Card title="iOS" icon="apple" href="https://apps.apple.com/in/app/billions/id6742451067">
    Download on the App Store
  </Card>

  <Card title="Android" icon="android" href="https://play.google.com/store/apps/details?id=com.billions.app.mobile">
    Get it on Google Play
  </Card>
</CardGroup>

***

<Info>
  **Credential Sync** — credentials sync automatically via end-to-end encrypted cloud storage. Sign in with the same account — Google, Apple ID, or crypto wallet — on the web or mobile wallet, and any credentials already claimed on one platform are immediately available on the other, with no need to re-claim them.
</Info>


# Billions Wallet
Source: https://docs.billions.network/billions-wallet/overview

Self-sovereign identity wallets for managing and verifying credentials on the Billions Network.

The Billions Wallet is a self-sovereign identity wallet for the Billions Network. Signing in derives a decentralized identifier (DID) from a cryptographic key pair, and every credential you claim is encrypted and stored under keys only you control. When a service asks you to prove something about yourself, the wallet generates a zero-knowledge proof on the spot: you decide what to share, and the proof confirms it without exposing the underlying data.

You can access the Billions Wallet from the **web** at [wallet.billions.network](https://wallet.billions.network) or through the [**mobile app**](/billions-wallet/mobile-wallet) on iOS and Android.

<Info>
  When the Web Wallet and the Mobile Wallet are signed in with the same account, credentials are synced — enabling effortless access across multiple devices.
</Info>

<CardGroup>
  <Card title="Web Wallet" icon="globe" href="/billions-wallet/web-wallet">
    Browser-based identity wallet for credential issuance, management, and verification.
  </Card>

  <Card title="Mobile Wallet" icon="mobile" href="/billions-wallet/mobile-wallet">
    iOS and Android wallet for managing credentials and generating zero-knowledge proofs on the go.
  </Card>
</CardGroup>

***

## Features

<CardGroup>
  <Card title="Seamless Authentication" icon="shield-halved">
    Sign in with Google, Apple ID, or a crypto wallet. An identity wallet is automatically derived and credentials are encrypted and stored for effortless multi-device access.
  </Card>

  <Card title="Privacy by Design" icon="lock">
    Users retain full control of their identity data. Credentials are exchanged directly between parties with no intermediaries and no centralized authority.
  </Card>

  <Card title="Credential Dashboard" icon="table-columns">
    View and manage all credentials from a unified dashboard — with full visibility into active, revoked, and expired credentials.
  </Card>

  <Card title="Zero-Knowledge Proofs" icon="shield-check">
    Generate cost-optimized ZK proofs for credential verification, enabling privacy-preserving authentication without exposing personal data.
  </Card>

  <Card title="Query Verification" icon="circle-check">
    Approve verification requests instantly by validating them against credentials stored in your wallet — on-chain or off-chain.
  </Card>

  <Card title="Credential Marketplace" icon="store">
    Proactively claim credentials in advance through the marketplace, making future verifications quicker.
  </Card>
</CardGroup>

***

## Credential Management

Credential management is the systematic process of creating, storing, protecting, rotating, and revoking digital credentials. The Billions Wallet handles this end-to-end — letting you claim, store, and present verifiable credentials that are privacy-preserving proofs about who you are, issued by trusted parties and verified on-chain or off-chain without exposing your underlying data.

### Available Credentials

<CardGroup>
  <Card title="Proof of Uniqueness" icon="fingerprint">
    Proves you are a real, unique human using a one-time face scan. The foundation for human verification across the Billions Network.
  </Card>

  <Card title="Verified Human" icon="user-check">
    Combines uniqueness with identity document verification for a higher level of trust.
  </Card>

  <Card title="Email" icon="envelope">
    Verifies ownership of an email address and links it to your decentralized identity.
  </Card>

  <Card title="Social Accounts" icon="share-nodes">
    Verify and link your Discord, Twitter (X), and Telegram accounts to your identity — provable without revealing account credentials.
  </Card>
</CardGroup>

***

## How to Claim Credentials

<Steps>
  <Step title="Open the Wallet">
    Visit [wallet.billions.network](https://wallet.billions.network) or open the Billions Mobile Wallet. Sign in with Google, Apple ID, or a crypto wallet.
  </Step>

  <Step title="Identity Loads">
    An identity wallet is derived from your account and any existing credentials are retrieved from encrypted cloud storage.
  </Step>

  <Step title="Browse Available Credentials">
    View the credentials available to claim.
  </Step>

  <Step title="Initiate Claiming">
    Select a credential and start the issuance flow. Depending on the credential type, this may involve a face scan (Proof of Uniqueness), document upload (Verified Human), or an OAuth connection (Email, Social Accounts).
  </Step>

  <Step title="Credential Issued and Stored">
    The issuer verifies the information and issues a signed credential directly to your wallet. It is encrypted and stored in cloud storage — ready to use in any verification flow without needing to be claimed again.
  </Step>
</Steps>

***

## Demo Application

Experience the full verification flow through the live demo at [demo.billions.network](https://demo.billions.network), which showcases **Human**, **Verified Human**, and **Uniqueness** verification flows end-to-end.

***

## Credential Storage

All credentials are encrypted and stored in cloud storage — accessible across multiple devices and serving as a reliable backup. Upon sign-in, an identity is derived and storage keys are generated from the authenticated account.

<Info>
  **End-to-End Encrypted Cloud Storage**

  * **Signature scheme:** ed25519
  * **Encryption:** AES256-GCM
  * **Access:** Only the user holding the storage keys can decrypt and access their credentials

  No credentials are stored in plaintext at any point. The cloud storage acts solely as a secure, encrypted repository — the decryption keys never leave the user's control.
</Info>


# Web Wallet
Source: https://docs.billions.network/billions-wallet/web-wallet

A secure, browser-based identity wallet for credential issuance, management, and verification — powered by zero-knowledge cryptography.

## Overview

The Web Wallet runs entirely in the browser, letting you claim, manage, and present credentials without installing anything. It verifies against both on-chain and off-chain requests, so the same wallet plugs into dApps and traditional web services alike.

## Quick Start

The Web Wallet is accessible at [wallet.billions.network](https://wallet.billions.network). To get started, sign in with Google, Apple ID, or a crypto wallet, and create your identity.

<Info>
  Zero-knowledge proof generation runs entirely in the browser using a WebAssembly-compiled circuit client. No personal data or cryptographic material leaves the user's device at any point during proof generation.
</Info>

<Info>
  **Credential Sync** — credentials sync automatically via end-to-end encrypted cloud storage. Sign in with the same account — Google, Apple ID, or crypto wallet — on the web or mobile wallet, and any credentials already claimed on one platform are immediately available on the other, with no need to re-claim them.
</Info>


# Billions Developer Docs
Source: https://docs.billions.network/index

Build with Billions — a network for humans and AI agents, powered by privacy-preserving identity and zero-knowledge technology.

<div>
  <div>
    <svg>
      <path />

      <path />

      <path />

      <g>
        <path />

        <path />
      </g>
    </svg>
  </div>
</div>

<div>
  <div>
    Billions Developer Docs
  </div>

  <div>
    A network for humans and AI agents. Build with privacy-preserving identity, verifiable credentials, and agentic trust infrastructure.
  </div>

  <CardGroup>
    <Card title="Billions Wallet" icon="wallet" href="/billions-wallet/overview">
      Web and mobile wallet for managing your verifiable identity credentials.
    </Card>

    <Card title="Login with Billions" icon="key" href="/billions-wallet/login-with-billions">
      Enable secure and decentralized authentication by leveraging the Billions Network.
    </Card>

    <Card title="Agents" icon="robot" href="/agents/identity-overview">
      Give AI agents verifiable identities and build trust in the agentic economy.
    </Card>
  </CardGroup>

  <div>
    <a href="https://github.com/BillionsNetwork">
      <svg>
        <path />
      </svg>

      GitHub
    </a>

    <a href="https://x.com/billions_ntwk">
      <svg>
        <path />
      </svg>

      Follow on X
    </a>

    <a href="https://www.linkedin.com/company/billions-ntwk">
      <svg>
        <path />
      </svg>

      LinkedIn
    </a>
  </div>
</div>