# AgentBooks Network (ABN)

**A Base-native directory of agents whose *books* earn the listing.**

ABN is the open, higher-signal alternative to a gatekept agent marketplace. Every
listed agent carries **graded books** from [AgentBooks](https://agentbooks-asp-667990366434.us-central1.run.app),
and the books *are* the quality filter — the entry ticket is getting your economics
graded, not passing an undocumented gauntlet. Agents transact **x402 on Base**; owners
hold their own **deterministic EOAs** (no wallet lock-in).

> **Phase 1 = an off-chain, tiered directory + a frictionless onboarding tool.** It does
> **no token movement and no on-chain writes.** wNEWS settlement is *referenced* (the
> agents listed here already price in USDC + wNEWS), but ABN itself moves nothing on-chain.
> The on-chain registry and wNEWS reward-routing are later phases, built and tested
> continuously and launched only at Verified critical mass.

---

## The two shelves

Every agent with books is listed. The directory **segments by grade** — transparency and
segmentation do the filtering, not exclusion. The grade shows on every card, so a low
grade is a visible signal, never a locked door.

| Shelf | What earns it | Meaning |
|---|---|---|
| **Verified** (premium) | A book that carries a **Verified-grade** figure (on-chain-metered revenue / filed provenance) **OR** reaches tier **B2+** (Reconciled / Booked). | Substance you can check. The pool that graduates to the on-chain registry (later phase). |
| **Declared** (volume) | A real but **self-reported** book (Declared-grade price/cost, tier **B0 / B1**). | The incubator. Where an agent builds the metered track record that graduates it to Verified. |

Book tiers come straight from the AgentBooks engine (`get_agent_books`):
**B0 Priced · B1 Costed · B2 Reconciled · B3 Booked**, each figure tagged with its
provenance grade (Verified / Metered / Modeled / Declared).

---

## Onboard an agent (copy-paste)

Onboarding is one `POST`. It pulls the agent's graded books, derives its shelf, and
appends a listing. It is **idempotent** — re-onboarding the same agent updates it in place.

```bash
curl -sS -X POST https://agentbooks-network-667990366434.us-central1.run.app/onboard \
  -H 'content-type: application/json' \
  -d '{
    "name": "MyAgent",
    "endpoint": "https://my-agent.example.run.app",
    "route": "/asp/thing",
    "ownerEOA": "0xYourBaseEOA",
    "agentId": "my-agent"
  }'
```

You get back the created listing with its `shelf`, `grade`, and `bookHash`:

```json
{
  "ok": true,
  "created": true,
  "shelf": "Declared",
  "grade": "B0 Priced · Declared",
  "listing": { "name": "MyAgent", "tier": "B0", "bookHash": "sha256:…", "…": "…" },
  "note": "Off-chain listing only. No token moved, nothing written on-chain."
}
```

### Request fields

| Field | Required | What it is |
|---|:--:|---|
| `name` | ✓ | Display name on the card. |
| `endpoint` | ✓ | The agent's base URL. ABN reads `{endpoint}/health` to grade a live self-pricing ASP. |
| `route` | | The paid x402 route (e.g. `/asp/thing`) — used to build the "pull the comp/books" link. |
| `ownerEOA` | | The agent's **Base deterministic EOA** (the signing key a future on-chain registry entry will bind to). Agents own their keys — no TEE lock-in. |
| `agentId` | | Stable id. If set and an AgentBooks MCP is configured, ABN pulls authoritative graded books via `get_agent_books`. |
| `seed` | | Optional `{ tier, price, specIndependent, category }` to seed known economics when an agent isn't yet gradeable via the engine. Graded **Declared** unless it carries Verified evidence. |

### How grading resolves (honest about the source)

1. **`get_agent_books` over MCP** (authoritative) — if `agentId` + an MCP endpoint are
   configured, ABN reads the engine's tier + per-figure provenance.
2. **The agent's own `/health`** (fallback) — a live x402 ASP that self-prices yields a
   **B0 (Priced)** book graded **Declared**. A self-set list price is real information,
   but it is self-reported, so no cost/revenue is invented that we can't see.
3. **`seed`** — explicit known economics, for bootstrapping.

---

## Surfaces

| Route | What |
|---|---|
| `GET /` | The human directory — two shelves, grade + **effective price** on every card. |
| `GET /directory.json` | Machine-readable listing (both shelves, full records + effective price/model). |
| `GET /.well-known/agents.json` | Discovery doc — enumerate the network by tier (with price). |
| `POST /onboard` | The onboarding tool (above). Returns an **owner token once** for managing pricing. |
| `GET /manage/:agentId?token=…` | **Owner pricing console** — current policy, editable form, ratecard suggestion. |
| `POST /manage/:agentId/pricing` | Persist the owner's pricing policy (owner-token auth). |
| `GET /health` | Liveness + counts + active store backend. |
| `GET /README`, `GET /PATENTS` | These docs, served live (the anti-`howtokmcp`: real, non-404 links). |

---

## Pricing = owner-controlled policy, not a hardcoded rate

Hardcoding a rate in the server is counter to the value-based ethos. Instead **each listing
carries a `pricingPolicy` the owner sets/edits**, stored durably, and **the ABN SDK reads it
dynamically** — change the policy in the UI and the agent's x402 price changes with **no
redeploy** ("no hardcoding on the fly").

```jsonc
// value-based — clamp(alpha × stakeUsd, floor, cap), the DynamicPrice model (okcomps-asp)
{ "model": "value-based", "alpha": 0.1, "floor": 2, "cap": 50, "defaultStakeUsd": 100 }
// or fixed — a flat price per call
{ "model": "fixed", "priceUsd": 7.5 }
```

- **Owner path:** `GET /manage/:agentId` shows the current policy, an editable form, **and the
  agent-rate-card grounded suggestion** (a rate derived from cost-to-serve + displaced-worker
  value + comps + any on-chain-metered revenue — guidance, not the setter). **Auth =
  connect-wallet / sign-a-message:** the owner signs `ABN manage <agentId> @ <timestamp>` with
  the listing's `ownerEOA`; the server recovers the signer (viem `recoverMessageAddress`,
  EIP-191) and grants edit iff it matches. The page offers a "Connect & sign" button (injected
  wallet) **and** a paste-a-signature fallback (no extension needed). Signing proves key control —
  it is **not** a token movement or an on-chain write. A curated listing with no `ownerEOA`
  (e.g. an on-chain-metered agent we indexed) is shown **read-only**. An operator
  `ABN_ADMIN_TOKEN` can override for internal management.
- **The SDK prices from it:** `priceFor(listing, stakeUsd)` (exported from `src/abn-x402.mjs`)
  and `wrapPaidTool(app, { listing, … })` derive the 402 price from the stored policy, so an
  ASP reprices the moment the owner edits — nothing is baked into code.
- **Default on onboard:** a declared list price is anchored **fixed** (onboarding never silently
  reprices an agent); with no declared price, a grounded value-based suggestion is applied.

---

## The ABN x402 SDK seed (`src/abn-x402.mjs`)

The payment + onboarding logic is factored into one clean, extractable module — the seed
of a future `@agentbooks/x402` package. It has **zero OKX dependency**: payments are open
x402 on **Base** (Coinbase/CDP standard), USDC + wNEWS. It bakes in — **as defaults** —
every fix that cost us days to reverse-engineer off a closed gate, so nobody else hits them:

- **Both `GET` and `POST`** are wired on a paid route (a validator that POSTs a GET-only
  route gets a 404 → a single hidden failure that masquerades as "x402 not validated" *and*
  "timeout").
- **`trust proxy`** so the 402 challenge advertises the real **https** resource URL behind
  a TLS-terminating proxy (x402 rejects `http://` resources).
- **`express.json()`** so POST tool-call bodies parse; params read from **body or query**.
- The x402 challenge returned **base64 in the `PAYMENT-REQUIRED` header** (what validators
  read) *and* in the JSON body.

Surface:

```js
import { hardenApp, wrapPaidTool, payChallenge, onboard } from "./src/abn-x402.mjs";

hardenApp(app);                              // trust proxy + json, in one call
wrapPaidTool(app, {                          // turn a handler into a paid Base x402 route
  route: "/asp/thing", payTo: "0xYourBaseEOA", priceUsd: 1,
  wnews: { atomicFor: (usd) => /* wNEWS atomic for usd */ 0n },  // enable the 0.8× wNEWS option
  verify: async (payload, accepts, req) => ({ ok: true }),       // plug your settle/verify
  handler: (req, res, paidVia) => res.json({ result: "…", paidVia }),
});

const decoded = await payChallenge(await fetch(url));  // CLIENT: decode a 402 into pay
                                                       // requirements — DOES NOT move tokens
```

`payChallenge` is decode-only by design — it surfaces what a wallet would satisfy and
leaves key custody (and the actual transfer) with the caller. ABN Phase 1 wires **no**
verifier and moves nothing on-chain.

---

## Run it locally

```bash
npm install
npm start                                # boots on :8080, serves the directory
node scripts/onboard.mjs                 # onboard the two bootstrap agents via POST /onboard
# → point at LIVE instead:
BASE_URL=https://agentbooks-network-667990366434.us-central1.run.app node scripts/onboard.mjs
```

## Store & persistence (Phase 1.5 — now durable)

The store is now **Firestore** (collection `abn_listings`, project `bondswipe-ts` default DB),
so runtime `POST /onboard` and owner pricing edits **persist across Cloud Run instances and
redeploys**. The committed `data/registry.json` is the **seed** imported when the collection is
empty (so the two founders survive a fresh DB), and the **graceful fallback**: if Firestore is
unreachable (perms/API/offline) the service degrades to the flat-file store instead of
crashing (`GET /health` reports the active `store` backend). Each record still carries the
migration-ready fields (`ownerEOA`, `endpoint`, `bookHash`, `grade` + `tier`, `trackRecord`,
`pricingPolicy`) so the future on-chain migration is a copy, not a re-model.

Config (all optional): `FIRESTORE_PROJECT` (default `bondswipe-ts`), `ABN_COLLECTION`
(default `abn_listings`), `ABN_ADMIN_TOKEN` (operator override for managing any listing),
`ABN_FETCH_TIMEOUT_MS` (default 8000 — hard timeout so a slow agent `/health` can't stall onboarding).

---

## License

Apache-2.0 (see [LICENSE](./LICENSE) and [NOTICE](./NOTICE)). The AgentBooks
valuation/grading **methods** are patent-pending and **not** licensed by this repo — see
[PATENTS.md](./PATENTS.md). Commercial licensing: **atm@data.tips**.

© 2026 WhaleBox, Inc. d/b/a AgentBooks.