# ProofPack & Agent Delegation

ProofPack is a library and format that enables services to verify that agents are authorized by real humans, and to accept selective identity claims without seeing full personal data.

If you're building a service that accepts requests from agents, or if you're building an agent that needs to prove authorization, this guide is for you.

## The Problem: Distinguishing Bots from Authorized Agents

Every day, services face a dilemma:

* **Requests from agents**: Could be legitimate (human-authorized) or malicious (bot)
* **Traditional authentication**: Requires the human to log in repeatedly (bad UX for agents)
* **API tokens**: Easy to steal, don't prove human authorization
* **OAuth to social providers**: Requires centralized identity providers, slow, privacy-invasive

**ProofPack solves this:** Agents carry cryptographic proof that a verified human authorized them. Services verify locally, with zero latency and full privacy.

## What is ProofPack?

ProofPack is a **JSON format + library** for:

1. **Selective Disclosure**: Share only specific identity claims (age, nationality, AML status) without full ID
2. **Cryptographic Verification**: Merkle trees prove data hasn't been tampered with
3. **Delegation Proof**: IsDelegate attestations prove human → agent authorization
4. **On-Chain Trust**: All attestations anchor to blockchain (EAS on Base) for immutable verification

## The Two Verification Paths

### Path 1: Quick Check (Wallet Only)

**Question:** "Is this wallet acting for a verified human?"

Use the agent's wallet address and `verifyByWallet()`. No JWS required.

{% content-ref url="/pages/WV1z2z2wEXngjQrNAb9N" %}
[Path 1: Wallet-only (JavaScript)](/tools-and-integrations/proofpack-agent-delegation/path1-wallet-only-javascript.md)
{% endcontent-ref %}

**Use cases:** MCP servers, connection handshakes, rate limiting, quick bot detection.

**Alternative: Simple REST API** — If you prefer not to use the library, see [IsDelegate REST API](/fundamentals/security/attestations/is-delegate-rest-api.md). It requires trusting Zipwire's validation; for independent verification use ProofPack.

### Path 2: Full Proof (With Claims)

**Question:** "Is this agent authorized by a human, and does that human meet these criteria (age, nationality, AML)?"

The agent sends a proof in the request header. **ProofPack supports both JWS and JWT**; use the standard `Authorization: Bearer <token>` pattern—any client or gateway that handles Bearer tokens works. The token contains specific identity claims, Merkle proofs, and the delegation chain. Your service verifies it and reads the revealed claims.

{% content-ref url="/pages/vHjbCV4bV7welWu86ldI" %}
[Path 2: JWS with claims (JavaScript)](/tools-and-integrations/proofpack-agent-delegation/path2-jws-claims-javascript.md)
{% endcontent-ref %}

**Use cases:** Payments, regulated services (KYC, compliance), premium features, any service that needs specific identity attributes.

## Installation

See [ProofPack Examples → Installation](/tools-and-integrations/proofpack-agent-delegation/installation.md) for npm, dotnet, and Rust.

## Setting Up Verification

Configure trusted roots and create the verifier/reader: [Quick setup: verification context](/tools-and-integrations/proofpack-agent-delegation/quick-setup-verification-context.md).

## Integration Examples

* **Express.js** — Middleware for `x-agent-wallet` or `Authorization: Bearer <token>` (JWS or JWT): [Express.js middleware](/tools-and-integrations/proofpack-agent-delegation/express-middleware.md)
* **ASP.NET Core** — Controller with wallet and JWS/JWT verification: [ASP.NET Core agent verification](/tools-and-integrations/proofpack-agent-delegation/aspnet-core-agent-verification.md)

## Common Use Cases

Time tracking, payment verification, compliance (KYC/AML), and MCP server integration: [Common use cases](/tools-and-integrations/proofpack-agent-delegation/common-use-cases.md).

## Troubleshooting

### "Agent not authorized by human"

**Causes:**

* Agent's wallet has no IsDelegate attestations
* IsDelegate was revoked
* IsDelegate points to an untrusted root
* IsDelegate is expired or invalid

**Fix:**

* Verify the human created the IsDelegate on [EAS](https://base.easscan.org)
* Check the refUID points to a valid IsAHuman attestation
* Check the Zipwire attester address matches your trusted roots

### "Invalid JWS signature"

**Causes:**

* JWS is tampered with
* Agent didn't sign it with their key
* JWS format is wrong

**Fix:**

* Verify the JWS comes directly from the agent
* Check the agent signed with their private key
* Verify JWS format: header.payload.signature

### "Merkle root mismatch"

**Causes:**

* Claims in the proof don't match on-chain attestation
* Proof was redacted incorrectly
* Attestation and proof were created separately

**Fix:**

* Verify the agent created the proof using the correct Mint API
* Check the Merkle root in the proof matches the on-chain attestation
* Ensure the agent is using the latest ProofPack library

## Security Best Practices

1. **Validate early**: Check agent authorization at the API entry point
2. **Trust roots carefully**: Only trust attesters you control or deeply trust
3. **Check revocation**: Revoked delegations should fail validation
4. **Use HTTPS**: Always transport proof tokens (JWS or JWT) over secure connections
5. **Log verifications**: Keep audit logs of what agents did
6. **Rate limit by verification**: Humans (verified) can request more than unverified agents

## Performance & Latency

* **Wallet-only check**: <100ms (no RPC calls needed with EAS GraphQL caching)
* **Full proof verification**: <200ms (local Merkle proof validation)
* **No IdP calls**: Zero latency waiting for external identity providers

ProofPack verification is **fast enough for request-path authentication**.

## The Future: Chained Agents

As agents become more sophisticated, sub-delegation becomes important:

```
Human (IsAHuman)
  ↓ IsDelegate
Primary Agent
  ↓ IsDelegate
Task-Specific Sub-Agent
  ↓ IsDelegate
Analysis Sub-Agent
```

ProofPack validates the entire chain, so services can trust requests from deep sub-agents.

***

## Related Documentation

* [ProofPack Examples](/tools-and-integrations/proofpack-agent-delegation/proofpack-examples.md) — copy-paste code for Path 1, Path 2, Express, ASP.NET Core, setup, use cases
* [IsDelegate Attestations](/fundamentals/security/attestations/isdelegate-agent-delegation.md)
* [For AI Agents](/use-cases/for-agents.md)
* [ProofPack GitHub](https://github.com/zipwireapp/ProofPack)
* [Zipwire Attest](https://zipwire.io/attest)

***

**Get Started:**

1. Install ProofPack library
2. Configure trusted roots
3. Add verification middleware to your API
4. Start accepting authorized agents!

**Questions?** Check the [ProofPack docs](https://github.com/zipwireapp/ProofPack) or contact Zipwire support.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zipwire.io/tools-and-integrations/proofpack-agent-delegation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.