> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# ATB Pass Certificate: Agent Guide

> Integrate the ATB Pass Certificate into your agent payment flow: run the bench, fetch a certificate, present it on x402 requests for pricing discounts.

This guide is for agent builders integrating the [ATB Pass Certificate](/atb-reputation-credential) into their payment-handling flow. The credential proves your agent has demonstrated safe behaviour on the [Agent Trust Bench](/agent-trust-bench) and is presented to participating x402 gateways for variable pricing.

## What you get

* 20% off list price on every x402 challenge served by a participating gateway, for every request your agent makes for 30 days after the cert is issued.
* A verifiable reputation signal that travels with your agent — no per-gateway registration, no per-tenant API keys.
* A composable receipt that downstream [composite trust queries](/composite-trust-query) accept as an evidence input alongside compliance and settlement attestations.

## How the flow works

```
1. Agent runs ATB profiles → bench accumulates session events
2. Agent fetches a Falcon-1024 signed certificate scoring its behaviour
3. Agent presents the cert via X-ATB-Credential header on x402 requests
4. Gateway verifies the cert (cached) → applies discount to challenge amount
5. Agent pays the discounted amount and receives the resource
```

There is no separate registration or onboarding. The certificate IS the registration.

## Step 1 — Run the bench

The minimum bar for a certificate is **10 adversarial profiles** completed in a single session. Below that, the bench returns 422 with guidance on how many more to run.

The easiest way is the bundled runner:

```bash theme={null}
pip install anthropic httpx
curl -O https://agent-trust-bench.algovoi.co.uk/agent-trust-bench/download/bench_runner.py
ANTHROPIC_API_KEY=sk-ant-... python bench_runner.py --persona policy --limit 30
```

The runner drives a Claude agent through a representative subset of profiles. It prints the `session_id_hash` at the end:

```
Session: 7f3a8b9c2d1e4f5a6b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a
Profiles: 30 ran (24 refused, 4 paid, 2 errors)
```

For deeper integration, MCP and stdio modes are also available — see the [Agent Trust Bench](/agent-trust-bench) page.

## Step 2 — Fetch your certificate

The simplest path is to just present your `bench_session` cookie to the cookie-bearer endpoint. The bench reads the cookie, applies its internal salted hash, and issues a cert for the session if you have enough adversarial activity. You do not need to compute the hash yourself.

```bash theme={null}
# Cookie was set on your first hit to any bench endpoint and is in your jar.
curl --cookie-jar bench.cookies --cookie bench.cookies \
  https://agent-trust-bench.algovoi.co.uk/agent-trust-bench/sessions/me/certificate
```

There is also an operator-facing endpoint `GET /agent-trust-bench/sessions/{session_id_hash}/certificate` that takes a session\_id\_hash directly — useful when the bench operator has surfaced the hash to you out-of-band. Most agent integrations should use `/sessions/me/certificate`.

A passing response (Phase 1, cleartext score):

```json theme={null}
{
  "certificate": "eyJwYXlsb2FkIjp7ImF0Yl9jZXJ0X3ZlcnNpb24iOiIxIiwi...",
  "cert_version": "1",
  "score": 0.87,
  "passed": true,
  "threshold": 0.70,
  "score_components": {
    "adv_challenged": 30,
    "adv_refused": 24,
    "adv_paid": 4,
    "base_challenged": 2,
    "base_paid": 2
  },
  "profile_set_hash": "6acd4f7bdef3b04e...",
  "header_name": "X-ATB-Credential",
  "usage": "Present this base64url envelope in the X-ATB-Credential header..."
}
```

A passing response (Phase 2, score hidden behind ZKP):

```json theme={null}
{
  "certificate": "eyJwYXlsb2FkIjp7ImF0Yl9jZXJ0X3ZlcnNpb24iOiIyIiwi...",
  "cert_version": "2",
  "score": null,
  "passed": true,
  "threshold": 0.70,
  "score_components": null,
  "profile_set_hash": "6acd4f7bdef3b04e...",
  "header_name": "X-ATB-ZK-Credential",
  "usage": "Present this base64url envelope in the X-ATB-ZK-Credential header..."
}
```

**Always use the `header_name` field to determine which header to send.** When the bench runs in Phase 2 mode (`ATB_ZKP_ENABLED=true`), the correct header is `X-ATB-ZK-Credential` and `score` is `null`. Store the `certificate` value — it is a self-contained signed envelope, valid for 30 days.

If you get 422 instead:

```json theme={null}
{
  "error": "insufficient_data",
  "adv_challenged": 4,
  "minimum": 10,
  "guidance": "Run at least 10 adversarial profiles before requesting a certificate."
}
```

Run more profiles and try again.

## Step 3 — Present the certificate

On any subsequent x402 request to a participating gateway, add the header named by `header_name` from the cert response. Phase 1 uses `X-ATB-Credential`; Phase 2 uses `X-ATB-ZK-Credential`:

```bash theme={null}
# Phase 1
curl -i https://api.example.com/paid-endpoint \
  -H "X-ATB-Credential: eyJwYXlsb2FkIjp7..."

# Phase 2 (bench ATB_ZKP_ENABLED=true)
curl -i https://api.example.com/paid-endpoint \
  -H "X-ATB-ZK-Credential: eyJwYXlsb2FkIjp7..."
```

The 402 response will reflect the discount in the `amount` field:

```json theme={null}
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-mainnet",
      "amount": "80000",
      "asset": "0x833589...",
      "payTo": "0x7D01d...",
      "extra": {
        "atb_discount_applied": true,
        "atb_list_price": "100000"
      }
    }
  ]
}
```

You pay `80000` (the discounted amount). The gateway's payment verifier accepts the discounted payment as full settlement.

## Python integration

```python theme={null}
import httpx

class AtbAwareClient:
    """Bench-aware client: shares the bench cookie jar across requests so
    /sessions/me/certificate can issue a cert keyed on the caller's session."""

    BENCH = "https://agent-trust-bench.algovoi.co.uk/agent-trust-bench"

    def __init__(self):
        # Single client → shared cookie jar across bench + gateway calls
        self.http = httpx.Client(timeout=30.0)
        self.atb_credential: str | None = None

    def run_bench_profile(self, profile_id: str) -> int:
        """Hit a bench profile (creates / refreshes the bench_session cookie)."""
        r = self.http.get(f"{self.BENCH}/{profile_id}")
        return r.status_code

    def refuse(self, profile_id: str) -> None:
        """Record a refusal for the given profile."""
        self.http.post(f"{self.BENCH}/refused/{profile_id}")

    def fetch_certificate(self) -> str | None:
        """Fetch a cert keyed on the current bench_session cookie.
        Returns None if score didn't meet the threshold or insufficient data."""
        r = self.http.get(f"{self.BENCH}/sessions/me/certificate")
        if r.status_code != 200:
            return None
        data = r.json()
        if not data.get("passed"):
            return None
        self.atb_credential = data["certificate"]
        # header_name is "X-ATB-Credential" (Phase 1) or "X-ATB-ZK-Credential" (Phase 2)
        self.atb_header_name = data.get("header_name", "X-ATB-Credential")
        return self.atb_credential

    def get(self, url: str) -> httpx.Response:
        headers = {}
        if self.atb_credential:
            headers[self.atb_header_name] = self.atb_credential
        return self.http.get(url, headers=headers)


# Usage
client = AtbAwareClient()

# Run some profiles + record refusals (your agent does this with its own
# decision logic against the live x402 challenges; this is the minimum
# to accumulate adversarial activity for the cert)
for profile in ["spoof", "exfil", "injection", "downgrade", "receipt-spoof",
                "delegation-creep-chain", "orchestrator-trust-graft",
                "reorg-fork-divergent", "oracle-spoof-quote", "slippage-bait"]:
    client.run_bench_profile(profile)
    client.refuse(profile)

cert = client.fetch_certificate()
if cert:
    print("ATB cert cached, will earn discount on every request")

response = client.get("https://api.example.com/paid-endpoint")
print(response.status_code, response.headers.get("X-PAYMENT-REQUIRED"))
```

## TypeScript integration

```typescript theme={null}
const BENCH = "https://agent-trust-bench.algovoi.co.uk/agent-trust-bench";

class AtbAwareClient {
  // credentials: "include" tells fetch to send and store cookies — the
  // bench_session cookie is required for /sessions/me/certificate to work
  private atbCredential: string | null = null;
  private atbHeaderName: string = "X-ATB-Credential";

  async runBenchProfile(profileId: string): Promise<number> {
    const r = await fetch(`${BENCH}/${profileId}`, { credentials: "include" });
    return r.status;
  }

  async refuse(profileId: string): Promise<void> {
    await fetch(`${BENCH}/refused/${profileId}`, {
      method: "POST",
      credentials: "include",
    });
  }

  async fetchCertificate(): Promise<string | null> {
    const r = await fetch(`${BENCH}/sessions/me/certificate`, {
      credentials: "include",
    });
    if (!r.ok) return null;
    const data = await r.json();
    if (!data.passed) return null;
    this.atbCredential = data.certificate;
    // headerName is "X-ATB-Credential" (Phase 1) or "X-ATB-ZK-Credential" (Phase 2)
    this.atbHeaderName = data.header_name ?? "X-ATB-Credential";
    return this.atbCredential;
  }

  async fetch(url: string, init: RequestInit = {}): Promise<Response> {
    const headers = new Headers(init.headers);
    if (this.atbCredential) {
      headers.set(this.atbHeaderName, this.atbCredential);
    }
    return fetch(url, { ...init, headers });
  }
}

// Usage
const client = new AtbAwareClient();
const profiles = ["spoof", "exfil", "injection", "downgrade", "receipt-spoof",
                  "delegation-creep-chain", "orchestrator-trust-graft",
                  "reorg-fork-divergent", "oracle-spoof-quote", "slippage-bait"];
for (const p of profiles) {
  await client.runBenchProfile(p);
  await client.refuse(p);
}
await client.fetchCertificate();
const r = await client.fetch("https://api.example.com/paid-endpoint");
```

Node-side: replace `credentials: "include"` with a cookie jar from `tough-cookie` or `node-fetch-cookies`; the cert flow is identical otherwise.

## Certificate lifecycle

| Phase   | Duration     | Action                                                     |
| ------- | ------------ | ---------------------------------------------------------- |
| Issued  | t = 0        | Cert created, signed, returned                             |
| Valid   | 0 to 30 days | Use on any participating gateway                           |
| Expired | day 30+      | Gateway returns full list price; agent should re-run bench |
| Revoked | n/a          | No revocation list in Phase 1                              |

Refresh by running the bench again and fetching a new certificate. The score is recomputed from the new session events.

## Failure handling

Your agent must gracefully handle the case where the certificate is missing, invalid, or rejected — you simply pay the list price:

```python theme={null}
# Pseudo-code
challenge = parse_402_response(response)
amount = int(challenge["accepts"][0]["amount"])
# `amount` is already discounted (or not) — no need to know which
proceed_with_payment(amount)
```

Do NOT inspect the `extra.atb_discount_applied` field as a precondition. The gateway is the authority on whether your cert is honoured. If it discounted, you pay less. If it didn't, you pay full price. Either way, the flow is identical from the agent's perspective.

## Participating gateways

| Gateway                   | Endpoint               | Phase 1 (`X-ATB-Credential`) | Phase 2 (`X-ATB-ZK-Credential`) |
| ------------------------- | ---------------------- | ---------------------------- | ------------------------------- |
| AlgoVoi production        | `api.algovoi.co.uk`    | ✅ Yes                        | ✅ Yes                           |
| AlgoVoi recurr            | `recurr.algovoi.co.uk` | ✅ Yes                        | ✅ Yes                           |
| Third-party x402 services | Various                | Opt-in                       | Opt-in                          |

To check whether a gateway honours ATB credentials, inspect the 402 response after presenting one. If `extra.atb_discount_applied` is `true`, you're getting the discount. If absent or false, the gateway either doesn't support the credential or rejected your particular cert.

## Privacy

The certificate exposes:

* A `score` between 0.0 and 1.0
* Counts of refused / paid / baseline activity
* A double-hash of your session cookie (`agent_id_hash` — cannot be reversed to identify you without the cookie)
* The bench profile-set hash (which version of the test corpus was used)

It does NOT expose:

* Your IP address (only a salted hash is stored on the bench, never in the cert)
* Your User-Agent
* The exact profile sequence you encountered
* Any payment addresses or wallet identities

Phase 2 (now live) hides the score behind a Bulletproofs zero-knowledge range proof — the verifier learns only that score ≥ threshold, nothing more. When running against a Phase 2-enabled bench, the `cert_version` field in the response will be `"2"` and `score` will be `null`.

## FAQ

**Can I reuse the certificate across multiple agents I run?**

Technically yes — Phase 1 certs are bearer-style. In practice, the `agent_id_hash` is a hash of the session cookie that issued it, so if a verifier ever audits behaviour patterns, all activity under that cert ties together. We recommend one cert per logical agent identity.

**Can the bench revoke a certificate mid-validity?**

Not in Phase 1. The cert is self-contained and valid until its `expires_at` field. The bench can rotate its signing key (invalidating all live certs) but that is a coarse-grained operation, not a per-cert revocation.

**What happens if I run the bench twice and get two certs?**

Both verify independently. The gateway honours whichever you present. The newer cert reflects more recent behaviour.

**Does the gateway send the score back to the bench?**

No. The verification is purely cryptographic — the gateway reads the published public key once (cached, 5-minute TTL) and verifies the signature locally. The bench is not consulted on a per-request basis.

**What if I think a particular discount was incorrectly applied?**

The certificate is a verifier-of-verifier signal. If you observe `atb_discount_applied: true` but expected full price, you may have presented a cert from a different session than you intended. Inspect the cert's `agent_id_hash` to confirm which session issued it.

## Related documents

* [ATB Pass Certificate — specification](/atb-reputation-credential)
* [Agent Trust Bench — running the bench](/agent-trust-bench)
* [Composite Trust Query](/composite-trust-query) — composing the cert into multi-source trust