> ## Documentation Index
> Fetch the complete documentation index at: https://shinydapps-bd9fa40b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LAW-N Behavioral Events

> CloudEvents 1.0 behavioral telemetry for AI agents. Reputation without authority.

# LAW-N Behavioral Events

LAW-N (SAGEWORKS AI) is a behavioral ledger for autonomous agents. Every L402 payment your agent makes can emit a signed CloudEvent — building a cryptographic audit trail that becomes an agent reputation score over time.

**No authority grants the reputation. The transactions are the proof.**

***

## How it works

```mermaid theme={null}
sequenceDiagram
    participant A as Your Agent
    participant M as l402-kit Middleware
    participant L as Lightning Network
    participant N as LAW-N Ledger

    A->>M: GET /api/data
    M-->>A: 402 + invoice
    A->>L: pay invoice
    L-->>A: preimage
    A->>M: GET /api/data + Authorization: L402
    M-->>A: 200 OK
    M->>N: CloudEvent (HMAC-signed) — fire and forget
    N->>N: behavioral pattern recorded
```

The event is emitted after every successful payment. It never blocks the response — if LAW-N is unavailable, your agent still gets the data.

***

## Enable on the client side

Available in **all 4 SDKs** as of `1.10.0`. Contract is identical: POST JSON + HMAC-SHA256 in `X-LAW-N-Signature` + random `X-LAW-N-Request-Id` + fire-and-forget (network errors swallowed so behavioral writes never block payments).

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { L402Client } from "l402-kit/agent";
    import { BlinkWallet } from "l402-kit/wallets";
    import { createLawNAdapter } from "l402-kit/integrations/law-n-adapter";

    const onEvent = createLawNAdapter({
      endpoint: "https://law-n.sageworks.ai/ingest/events",
      secret: process.env.LAWN_SECRET!,
    });

    const client = new L402Client({
      wallet: new BlinkWallet(process.env.BLINK_API_KEY!),
      agentId: "agent:myorg.myagent",
      onEvent,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from l402kit import L402Client
    from l402kit.wallets import build_wallet
    from l402kit.integrations import create_lawn_adapter

    on_event = create_lawn_adapter(
        endpoint="https://law-n.sageworks.ai/ingest/events",
        secret=os.environ["LAWN_SECRET"],
    )

    client = L402Client(
        wallet=build_wallet(),  # auto BLINK_API_KEY+BLINK_WALLET_ID or ALBY_TOKEN
        on_event=on_event,
    )
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    use l402kit::integrations::create_lawn_adapter;
    use std::time::Duration;

    // Requires Tokio runtime (already present in any axum/tonic app)
    let on_event = create_lawn_adapter(
        "https://law-n.sageworks.ai/ingest/events".into(),
        std::env::var("LAWN_SECRET").unwrap(),
        Duration::from_secs(5),
    );

    // Wire `on_event(event)` into your L402 middleware's event hook
    ```

    The `lawn-adapter` feature is enabled by default. To opt out (lighter binary), use `default-features = false` in `Cargo.toml`.
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
        "os"
        "time"

        l402kit "github.com/ShinyDapps/l402-kit/go"
    )

    func main() {
        onEvent := l402kit.CreateLawNAdapter(
            "https://law-n.sageworks.ai/ingest/events",
            os.Getenv("LAWN_SECRET"),
            5*time.Second,
        )

        // Wire onEvent(event) into your L402 middleware's event hook
        _ = onEvent
    }
    ```
  </Tab>
</Tabs>

***

## Event types

| Event                      | Emitted when                         |
| -------------------------- | ------------------------------------ |
| `l402.challenge.received`  | Server returned HTTP 402             |
| `l402.payment.initiated`   | Agent started paying the invoice     |
| `l402.payment.settled`     | Payment confirmed, preimage received |
| `l402.access.granted`      | Server accepted the L402 token       |
| `l402.budget.exhausted`    | Agent hit its spending cap           |
| `l402.token.reused`        | Agent retried with existing proof    |
| `l402.proof.reuse.attempt` | Attempted to reuse a spent preimage  |

***

## CloudEvents 1.0 format

```json theme={null}
{
  "specversion": "1.0",
  "type": "l402.payment.settled",
  "source": "l402-kit",
  "id": "req_a1b2c3d4",
  "time": "2026-05-10T14:32:00.000Z",
  "subject": "agent-payment-flow",
  "datacontenttype": "application/json",
  "data": {
    "agent_id": "agent:myorg.myagent",
    "session_id": "sess_8f3a1b2c",
    "request_id": "req_a1b2c3d4",
    "endpoint": "https://api.example.com/data",
    "event_type": "l402.payment.settled",
    "network": { "provider": "blink", "environment": "mainnet" },
    "payment": {
      "amount_sats": 100,
      "preimage_hash": "sha256:abc123...",
      "settled": true,
      "latency_ms": 487
    },
    "behavior": {
      "retry_count": 0,
      "proof_reuse_attempt": false,
      "budget_remaining": 900,
      "budget_exhausted": false
    }
  }
}
```

***

## What reputation looks like

Agents that consistently:

* Pay invoices on first attempt
* Respect budget constraints
* Do not attempt proof reuse
* Operate across diverse endpoints

...build reputation automatically. Agents that misbehave stop being able to access services.

No whitelist. No governance vote. No authority deciding who is trustworthy. The ledger is the proof.

***

## Activity dashboard

Public stats available at:

```bash theme={null}
curl https://l402kit.com/api/activity
```

```json theme={null}
{
  "total_events": 1420,
  "unique_agents": 12,
  "total_sats": 84200,
  "recent_events": [...],
  "top_agents": [
    { "agent_id": "agent:shinydapps.verity", "event_count": 847 }
  ]
}
```

Live dashboard: [l402kit.com/activity](https://l402kit.com/activity)