@oracle-agent/oracle 0.14.1 → 0.15.0

package/docs/adding-a-chain.md

@@ -1,229 +0,0 @@
-# Adding a chain
-
-Oracle treats a chain as **configuration**. You do not write an integration.
-
-## The short version
-
-```js
-import { registerCustomChain } from "@oracle-agent/oracle/scanner";
-
-registerCustomChain({
-  key: "mychain",
-  chainId: 7777,
-  name: "My Chain",
-  rpcEnv: ["MYCHAIN_RPC_URL"],
-  nativeCurrency: { symbol: "MYC", decimals: 18 },
-});
-```
-
-That chain now has block reads, native and ERC-20 balances, on-chain token
-resolution, log scanning, and structural risk checks. No code was written.
-
-```bash
-export MYCHAIN_RPC_URL=https://rpc.mychain.example
-oracle-scan head mychain
-```
-
-## Config fields
-
-| Field | Required | Notes |
-|---|---|---|
-| `key` | yes | lowercase slug, used on the CLI |
-| `chainId` | yes | positive integer |
-| `name` | yes | display name |
-| `rpcEnv` | yes | env var names, `UPPER_SNAKE`. Never a literal URL |
-| `nativeCurrency` | no | `{ symbol, decimals }` |
-| `explorer` | no | base URL |
-| `dexscreenerSlug` | no | enables pool discovery — see below |
-| `venues` | no | verified routers/quoters — required for routing value |
-
-**RPC URLs live in the environment, never in config.** A repo carrying an endpoint
-is both a leak and a rate-limit problem for whoever else uses that key.
-
-## Why `dexscreenerSlug` matters
-
-Pool discovery goes through market data rather than walking a factory. A factory
-walk finds pools that *exist*; a trader needs pools with *liquidity*.
-
-The slug is DexScreener's own chain identifier — not the chain id, and not always
-the obvious name. If you don't know it, **leave it out**. Pool discovery then
-reports `UNAVAILABLE`, which is honest. A wrong slug silently returns another
-chain's pools, which is worse than no answer.
-
-## Adding venues (routing value)
-
-A chain with no verified venue is **fail-closed**: read and research work, routing
-value does not. That is a safe default, not a gap.
-
-To enable routing you must record *provenance*:
-
-```js
-venues: [
-  {
-    kind: "router",
-    address: "0x...",
-    verified: {
-      method: "eth_getCode + protocol /chains API",
-      source: "https://li.quest/v1/chains",
-      date: "2026-07-30",
-    },
-  },
-]
-```
-
-Validation **refuses** a venue without `verified`. This is not bureaucracy: the
-destination allowlist is the highest-leverage control in the system, and
-allowlisting a spoofed router makes every other guard irrelevant.
-
-### How to actually verify
-
-1. **Bytecode exists** — `eth_getCode` must return real code. `0x` means nothing is
-   deployed at that address on that chain.
-2. **The protocol's own API or docs** names that address, for that chain, today.
-   Query the source (e.g. LI.FI's `/v1/chains` returns each chain's official
-   `diamondAddress`) rather than trusting a blog post or a model's recollection.
-3. **Constructor-bound addresses match** — read `factory()`, `WETH9()` back off the
-   deployed contract and confirm they're what you expect.
-4. **Per chain, separately.** An address verified on Arbitrum is not verified on
-   Ethereum, even when the canonical deployment shares an address across chains.
-
-Record how and when. The audit trail has to outlive your session.
-
-## Capabilities
-
-Ten capabilities exist. The generic EVM scanner provides seven out of the box:
-
-| Capability | Generic? | Why |
-|---|---|---|
-| `blockNumber` | yes | standard RPC |
-| `nativeBalance` | yes | standard RPC |
-| `tokenBalance` | yes | ERC-20 is ERC-20 |
-| `resolveToken` | yes | reads metadata off the contract |
-| `resolvePools` | yes* | needs `dexscreenerSlug` |
-| `scanBlocks` | yes | chunked `eth_getLogs` |
-| `scoreRisk` | yes | structural checks |
-| `quote` | venue | needs a verified router |
-| `sellSimulation` | venue | needs a verified router |
-| `prepareUnsignedTx` | venue | needs a verified router |
-
-Calling an unimplemented capability **throws**, naming what is supported. It never
-returns `undefined` that a caller could mistake for "no result."
-
-## Enabling quote / sell / prepare
-
-Add a verified router plus two fields:
-
-```js
-{
-  key: "base",
-  chainId: 8453,
-  // ...
-  venueKind: "uniswap-v2",
-  wrappedNative: "0x4200000000000000000000000000000000000006",
-  venues: [{ kind: "router", address: "0x...", verified: { /* ... */ } }],
-}
-```
-
-`src/scanner/chains.config.mjs` ships **Base** wired this way as the reference. It
-gets all 10 capabilities; every other built-in stays at 7 and fail-closed until
-someone verifies a venue for it.
-
-What you get:
-
-- **`quote`** — live exact-input pricing via `getAmountsOut`
-- **`sellSimulation`** — a state-free round trip (buy then sell back) that catches
-  the honeypot signature: buy leg quotes fine, sell leg fails. This is the single
-  most valuable check on a low-cap venue, because most losses are not bad entries
-  but tokens that cannot be exited
-- **`prepareUnsignedTx`** — an **unsigned** swap with a `minOut` computed from the
-  live quote, a deadline, and an explicit `approve` step listed separately so
-  "approved" and "swapped" are never collapsed into one claim
-
-`scoreRisk` also upgrades automatically: with a router it reports real sellability
-instead of `UNKNOWN`.
-
-### The slippage ceiling is hard
-
-A supplied `slippageBps` is a **maximum**, capped at 100 bps. Above that,
-`prepareUnsignedTx` throws rather than widening:
-
-```
-slippageBps 250 exceeds the 100 bps ceiling. Block and requote or split
-the order -- do not widen the guard to force a fill.
-```
-
-A cap that yields under pressure is decoration.
-
-### V3 / V4 / custom quoters
-
-Two adapters ship:
-
-| `venueKind` | Requires | Prices via |
-|---|---|---|
-| `uniswap-v2` | `router` | `getAmountsOut` on the router |
-| `uniswap-v3` | `quoter` **and** `router` | `quoteExactInputSingle` on QuoterV2 |
-
-V3 is **not** V2 with different addresses: it has no `getAmountsOut`, prices through
-a separate Quoter contract, and needs an explicit fee tier per hop. Encoding a V3
-swap with V2 assumptions yields a transaction that reverts, or worse routes through
-the wrong pool. That is why they are sibling adapters.
-
-The V3 adapter searches all four fee tiers (100 / 500 / 3000 / 10000) and keeps the
-best. This is necessary, not a nicety — liquidity concentrates in one tier and which
-tier varies by pair and chain. On Arbitrum WETH→USDC the 500 tier returns ~2.4% more
-than the 100 tier; defaulting to 0.3% because it is the common choice silently
-misprices stable and exotic pairs alike.
-
-A V3 chain needs **both** a quoter and a router. A router alone stays fail-closed:
-it could encode a swap, but with no priced expectation to guard against — exactly
-the state that produces an unbounded fill.
-
-**V4 and custom-quoter venues still need their own adapter.** Some forks require an
-off-chain signed quote you cannot produce locally. Write a sibling module rather
-than bending an existing one; silently mis-encoding a swap is far worse than
-declaring the capability unsupported.
-
-### Verifying a venue: run the prober
-
-`scripts/verify-v3-venues.mjs` probes candidate addresses on every chain and prints
-a pass/fail with the live price it got:
-
-```bash
-node scripts/verify-v3-venues.mjs
-```
-
-**Codesize is not verification.** The canonical mainnet QuoterV2 address returns
-2109 bytes of bytecode on Base — it is *some* contract, just not a working quoter
-for that chain. A codesize check waves it through; the functional probe caught it
-and pointed at Base's real quoter (8273 bytes, prices WETH→USDC correctly).
-
-The rule: **a contract that correctly prices a pair you can sanity-check IS the
-thing you think it is.** Anything less is a guess with an address attached.
-
-## Honest evidence
-
-Every finding carries a label. Respect the distinction:
-
-- `LIVE` — read this call
-- `CACHED` — recent, within stated TTL
-- `STALE` — older than TTL; usable only with the caveat stated
-- `UNKNOWN` — we tried and could not determine it
-- `UNAVAILABLE` — this chain/provider cannot answer at all
-
-`UNKNOWN` and `UNAVAILABLE` are different facts. Collapsing them is how people end
-up sizing against stale reserves.
-
-Risk verdicts are coarse on purpose — `PASS` / `CAUTION` / `FAIL` / `UNKNOWN`. A
-score like "risk 62/100" invites trading a number nobody understands.
-
-**`UNKNOWN` is not `PASS`.** The generic scanner returns `UNKNOWN` for sellability
-because it cannot prove exitability without a verified router. A token is not
-tradeable until a round-trip sell simulation succeeds.
-
-## Contributing a chain upstream
-
-Append to `CHAIN_CONFIGS` in `src/scanner/chains.config.mjs` and open a PR. Tests
-already assert every built-in config validates and that none embeds an RPC URL, so
-CI will catch a malformed entry.
-
-If you add venues, put the verification method and date in the PR body.

package/docs/architecture.md

@@ -1,139 +0,0 @@
-# Architecture
-
-Three planes. The boundary between them is enforced by a test, not a convention.
-
-```
-                    user's wallet
-                         ^
-                         | signs (only the user can)
-                         |
-   +---------------------+---------------------+
-   |            unsigned artifacts             |
-   |                                           |
-   |  PUBLIC (this repo)                       |
-   |                                           |
-   |  data plane      read / quote             |
-   |  policy plane    allowlists, guards,      |
-   |                  attestations, grants     |
-   |  control plane   grant lifecycle,         |
-   |                  session keys, AA, router |
-   +-------------------------------------------+
-                         |
-                         x  no import may cross
-                         |
-   +-------------------------------------------+
-   |  OWNER-LOCAL (private infrastructure)     |
-   |  separately installed by the owner        |
-   |  key-vault / hl-exec / oracle-vault       |
-   +-------------------------------------------+
-```
-
-## Why three planes
-
-The design assumption is that **the model can be wrong or adversarially steered**.
-Everything follows from treating it as an untrusted proposer.
-
-If the model is untrusted, then authorization cannot come from the model. It comes
-from an owner signature over a bounded grant. And if authorization is separate from
-proposal, then the code that proposes must be unable to reach the code that signs —
-otherwise the separation is aspirational.
-
-That is why the boundary is a test (`test/custody-boundary.test.mjs`) rather than a
-paragraph in a README. It walks the import graph from every shipped entrypoint and
-fails on:
-
-- any public module importing signer or key material
-- a dangling local import that reaches a signer from a shipped entrypoint
-- a secret-shaped literal anywhere
-- a packed npm artifact that still contains signer/vault modules
-
-## Data plane
-
-`src/data/` — 70 provider modules covering 219 unique protocols/venues, each
-declaring an honest tier. One module can cover many protocols: the Jupiter
-module alone routes 98 Solana venues.
-
-| Tier | Meaning |
-|---|---|
-| `read-only` | data only; no execution claim |
-| `quote-only` | can price a route; no reviewed transaction builder |
-| `prepare` | returns a policy-bound unsigned transaction |
-| `intent` | returns typed data to sign (CoW orders, GMX orders) |
-
-The tier is load-bearing. "We support protocol X" is ambiguous and has caused real
-confusion; the tier is not. **API coverage ≠ execution support.**
-
-`src/data/catalog.mjs` is the registry; `dataHealth()` probes liveness. Note the
-distinction in health output: a promise that resolved with `{ok: false}` is
-*degraded*, not healthy — and an HTTP 200 serving an explorer error page is not a
-successful read.
-
-## Policy plane
-
-The moat. Holds no keys; constrains what a signer may be asked to do.
-
-- **Destination allowlist** (`src/venues.mjs`) — per chain, fail-closed. An empty
-  allowlist refuses everything. It never means "allow anything."
-- **Auto-slippage** (`src/auto-slippage.mjs`) — a guard computed from live depth and
-  volatility per leg, recomputed before each broadcast. A caller-supplied tolerance
-  is a *maximum*, not the selected value. Hard ceiling 100 bps; over that, block and
-  requote rather than widen.
-- **Attestations** (`route-`, `vault-`, `gmx-attestation.mjs`) — dynamic execution
-  targets require an attestation minted inside the trusted boundary. Model-authored
-  JSON is not authorization.
-- **Approval guard** — exact-amount approvals, never unlimited by default, with
-  allowance read back after the approve lands.
-
-Guards are re-checked at **sign and broadcast** time. A stale minimum is not a
-minimum.
-
-## Control plane
-
-`src/public-control/` — grant schema and rendering, session-key model, ERC-4337
-adapter, bundler client, grant indexer.
-
-`src/router/` — model routing with a custody firewall. `risk-classifier.mjs` scores
-an action's risk; `proposal.mjs` refuses to construct a proposal containing
-dangerous fields (private keys, mnemonics, bearer tokens) at any nesting depth. The
-router can propose, simulate, explain, and draft. It cannot authorize.
-
-## Scanner framework
-
-`src/scanner/` — makes a chain data rather than an integration.
-
-- `contract.mjs` — 10 capabilities, a validator, a registry, coverage matrix
-- `evm-scanner.mjs` — one generic implementation for any EVM JSON-RPC chain
-- `chains.config.mjs` — the 11 built-ins as config, plus `registerCustomChain()`
-
-Unimplemented capabilities are **absent, not faked**: calling one throws a message
-naming what *is* supported. A caller can never mistake `undefined` for a negative
-result.
-
-Evidence labels (`LIVE` / `CACHED` / `STALE` / `UNKNOWN` / `UNAVAILABLE`) and risk
-verdicts (`PASS` / `CAUTION` / `FAIL` / `UNKNOWN`) exist to stop the collapse that
-causes losses: **`UNKNOWN` is not `PASS`**, and "we could not check" is a different
-fact from "there is nothing there."
-
-## Agent mesh
-
-`profiles/` + `skills/` — seven installable Hermes lanes plus a template.
-
-A lane is narrow on purpose: smaller context is cheaper and more accurate, per-lane
-memory doesn't cross-contaminate, and a grant scoped to one lane can't be spent by
-another.
-
-Every lane ships DISARMED, and every grant action a lane may request is read,
-simulate, or prepare. No lane may request broadcast or signing — enforced in
-`test/profiles.test.mjs`, so widening custody cannot pass review quietly.
-
-No lane pins a model. `profile.json` carries a capability *class*
-(`strong-reasoner`, `fast-tool-caller`), so the installer never writes a vendor into
-a user's config.
-
-## What is not in the public package
-
-House custody, an always-on exec server, and capability minting are not shipped.
-Owner-local signer modules (`key-vault`, `hl-exec`, `oracle-vault`) live only in
-separately installed private infrastructure on the owner's machine. They are not
-published on npm or available to holder installs. This prepare package has
-nothing to steal: it never takes a key and never broadcasts.

package/docs/buzz-integration.md

@@ -1,115 +0,0 @@
-# Buzz integration
-
-Oracle exposes an unsigned public HTTP contract for Buzz. Buzz calls Oracle over
-HTTP; it does not import or embed the private signer/executor.
-
-## Current boundary
-
-- Plane: public read, connect, grant, auth verification, and audit.
-- Custody: user signs grants and capabilities in the user's wallet.
-- Posture: `DISARMED`.
-- Private keys: never accepted.
-- Broadcast: unavailable from the public server.
-- Conversational Oracle embedding: separate Buzz client work; the HTTP contract
-  alone does not create a persistent Oracle chat session.
-
-Source: `src/public-api/buzz-integration.mjs`.
-
-## Start locally
-
-```bash
-oracle public serve --port 8799
-curl -fsS http://127.0.0.1:8799/public/health
-curl -fsS http://127.0.0.1:8799/public/buzz
-```
-
-The server binds to loopback. Source code or a static Oracle website is not proof
-that the API is running. Check `/public/health` on the deployment you intend to
-use before enabling a Buzz client.
-
-## Discovery and capability flow
-
-Buzz begins with:
-
-```http
-GET /public/buzz
-```
-
-The returned discovery object is the contract source of truth for the running
-server. The current API family includes:
-
-- `GET /public/health`
-- `GET /public/config`
-- `POST /public/connect/request`
-- `POST /public/connect/assemble`
-- `POST /public/grants/active`
-- `POST /public/grants/get`
-- `POST /public/buzz/auth/preimage`
-- `POST /public/buzz/auth/verify`
-- `POST /public/buzz/audit/append`
-- `POST /public/buzz/audit/verify`
-- `POST /public/buzz/audit/entries`
-
-Do not hardcode this list without checking discovery; a deployment can lag the
-source tree.
-
-The client asks Oracle for the exact capability preimage, the owner wallet signs
-that preimage, and Oracle verifies the supplied capability. The server never
-mints a capability with a house key.
-
-## Audit contract
-
-Buzz public events append to a SHA-256 hash chain. The server restricts public
-audit actions and scans details for secret material before append and response.
-A valid audit entry proves the hash-chain record exists; it does not prove an
-on-chain action executed. On-chain success still requires a real transaction
-hash, successful receipt, and expected state change.
-
-## Hard prohibitions
-
-Buzz must never use this integration to:
-
-- reach a private executor or owner wallet;
-- request, store, or forward private keys, seed phrases, vault passphrases,
-  signer tokens, provider keys, or bot tokens;
-- mint server-side capabilities with a house key;
-- treat a verified capability as blanket execution authority;
-- expose Oracle's loopback service directly to the internet;
-- mix holder sessions, memories, portfolios, grants, or audit streams;
-- describe prepare, sign-request, or queue state as execution.
-
-## Hosted deployment
-
-For a hosted Buzz integration, place Buzz's authenticated backend in front of
-Oracle's loopback public server. Use TLS, strict origin and audience binding,
-short-lived sessions, rate limits, request-size caps, redacted logs, and a
-controlled proxy that overwrites forwarded-IP headers.
-
-A hosted Buzz service requires server-side authentication and per-user isolation.
-Locals Only ownership only changes Oracle's integrator fee and does not grant or
-restrict Buzz access.
-
-## Conversational Oracle in Buzz
-
-Embedding the full Oracle conversation requires a separate bridge:
-
-1. Buzz authenticates the user and holder session.
-2. Buzz assigns a distinct Oracle session/profile namespace per user.
-3. Buzz streams responses and renders structured tool results as Buzz cards.
-4. The Oracle session receives only public read/prepare tools.
-5. Wallet review and signatures stay in the Buzz client or user's wallet.
-6. Owner/operator tools and DEMI's sessions are never mounted into that tenant.
-
-Until that bridge exists and passes isolation tests, say **“Buzz HTTP contract
-available”**, not **“Oracle chat is integrated into Buzz.”**
-
-## Release verification
-
-```bash
-npm run test:boundary
-npm test
-npm run scan:secrets
-```
-
-Then verify the exact deployed URL and discovery response. A passing source test
-does not prove a remote deployment is live.

package/docs/cli.md

@@ -1,143 +0,0 @@
-# Oracle unified CLI
-
-Root command: `oracle <noun> <verb> [args]`.
-
-The public `@oracle-agent/oracle` CLI is standalone and prepare-only. Hermes is
-optional. The public package does not import a signer, hold a wallet key, submit,
-or broadcast.
-
-## Install and first run
-
-```bash
-npm i -g @oracle-agent/oracle            # Node >= 20.19
-oracle --version
-oracle auth login claude               # or codex / grok
-oracle
-oracle doctor
-```
-
-API-key users can run `oracle auth api-key <provider>`; interactive input is
-hidden. Do not pass credentials as command-line arguments. Linux, Windows, and
-macOS apps are in beta.
-
-## Command groups
-
-### Chat and model authentication
-
-```bash
-oracle
-oracle chat
-oracle chat -q "research HYPE funding"
-oracle auth login claude|codex|grok
-oracle auth api-key openrouter|openai|xai|deepseek|gemini|custom
-oracle auth status [--json]
-oracle auth logout <provider>
-oracle model
-oracle model --show
-oracle model --provider <provider> --model <model>
-```
-
-OAuth and stored API keys use the OS credential store when available and a
-private `0600` local fallback otherwise. Status output never prints credentials.
-
-### Chain selection
-
-```bash
-oracle chain list
-oracle chain use hyperliquid
-oracle chain show
-oracle chain clear
-```
-
-Inside chat, `/chain` lists or selects the active chain. Chain selection changes
-routing context, not custody or authorization.
-
-### Read, research, and prepare
-
-```bash
-oracle scan --help
-oracle route --help
-oracle data serve
-oracle public serve --port 8799
-oracle doctor [--json]
-```
-
-`oracle data serve` binds the local read plane to `127.0.0.1:8787`.
-`oracle public serve` binds the unsigned public HTTP plane to loopback. Neither
-command creates authentication. Do not expose either port directly.
-
-### Optional Hermes integration
-
-```bash
-oracle bootstrap [--status|--upgrade]
-oracle init                 # dry run
-oracle init --apply
-oracle setup
-oracle setup telegram --allowed-users <id>
-oracle setup messaging
-oracle setup gateway [status|start|stop|restart]
-```
-
-`oracle bootstrap` installs an isolated compatibility runtime and never modifies
-system Python. `oracle init --apply` writes specialist profiles and local
-attestation configuration; it does not write a wallet private key.
-
-Messaging token prompts are hidden. Avoid `--token` in a normal shell because
-arguments can be retained in history or visible to other local users.
-
-### MCP connectors
-
-```bash
-oracle mcp install claude-code
-oracle mcp install claude-desktop
-oracle mcp install codex
-oracle mcp install chatgpt
-oracle mcp install cursor
-oracle-data-mcp
-```
-
-See [connectors.md](connectors.md). Connector installation exposes public
-read/prepare tools only unless a separate owner-operated boundary is explicitly
-installed and verified.
-
-## Chat commands
-
-- `/chain` — list or select the active chain.
-- `/setup` — optional messaging setup.
-- `/model` — switch models; the persona remains Oracle.
-
-Terminal and configured messaging channels can enter the same Hermes profile,
-but the transport and selected model never create authority. Shared hosted
-sessions must remain isolated and read/prepare-only.
-
-## Exit codes
-
-| Code | Meaning |
-|---:|---|
-| `0` | success |
-| `1` | usage, configuration, or general error |
-| `2` | separately installed operator reported an error |
-| `3` | private operator command requested but unavailable |
-| `4` | required local data server not running |
-
-## Doctor semantics
-
-A standalone public install can legitimately warn that the optional data server,
-Hermes runtime, profiles, or signer are absent. A Node-version failure is
-blocking. Signing readiness is not required for the public package.
-
-## Safety semantics
-
-- Read, quote, simulate, and prepare are not execution.
-- The wallet address in a preparation request must be the real signer.
-- A prepared artifact is inert until a user-controlled wallet signs it.
-- A signature request or transaction hash is not a successful receipt.
-- No CLI flag turns a public install into DEMI's operator lane.
-- A shared hosted service needs server-side authentication and per-user isolation.
-
-## More
-
-- [Full setup](../SETUP.md)
-- [Public surface and environment variables](public-surface.md)
-- [Locals Only 0% fee waiver](locals-only-fee-waiver.md)
-- [Buzz integration](buzz-integration.md)

package/docs/connectors.md

@@ -1,13 +0,0 @@
-# Oracle AI-client connectors
-
-ChatGPT is hosted and can NEVER sign or reach your keys. This connector is read/prepare only; anything it prepares is unsigned until you sign it locally.
-
-```bash
-oracle mcp print --target claude-code
-oracle mcp install claude-code
-oracle mcp install codex
-oracle mcp install chatgpt
-oracle mcp install claude-code --with-control   # requires local operator
-```
-
-Oracle does not create tunnels for hosted clients.

package/docs/hyperliquid-builder-code.md

@@ -1,50 +0,0 @@
-# Hyperliquid builder code
-
-Oracle's Hyperliquid order preparer discloses and attaches this builder code to eligible perp orders:
-
-- Builder address: `0x4d47B6757aFd42c3dbd9691b71B43d74Afa4b6b2`
-- Oracle perps fee: **5 basis points** (`0.05%`)
-- Hyperliquid order wire value: `builder: { "b": "0x4d47B6757aFd42c3dbd9691b71B43d74Afa4b6b2", "f": 50 }`
-
-Hyperliquid expresses `f` in tenths of a basis point, so `f: 50` means 5 basis points. This is separate from the 10 basis point same-chain swap tier and from Hyperliquid's own trading fees.
-
-## Locals Only
-
-Locals Only ownership only changes Oracle's integrator-fee rate. It does not waive the Hyperliquid builder fee, which is a separate venue mechanism. Eligible holder and non-holder perp orders carry the same disclosed builder parameter. This is not an access gate. Holders and non-holders use the same public package, markets, order preparation, and wallet handoff.
-
-## One-time approval
-
-Before Hyperliquid accepts an order carrying this builder code, the user must approve a maximum fee for the builder address with an `ApproveBuilderFee` action:
-
-```json
-{
-  "type": "approveBuilderFee",
-  "builder": "0x4d47B6757aFd42c3dbd9691b71B43d74Afa4b6b2",
-  "maxFeeRate": "0.05%",
-  "nonce": 0
-}
-```
-
-The nonce is replaced at preparation time. Hyperliquid requires the **main wallet**, not an agent or API wallet, to sign this approval. The approval is revocable. Oracle prepares the action but never signs or submits it.
-
-The approved maximum can be checked with Hyperliquid's read-only info request:
-
-```json
-{
-  "type": "maxBuilderFee",
-  "user": "0xUSER",
-  "builder": "0x4d47B6757aFd42c3dbd9691b71B43d74Afa4b6b2"
-}
-```
-
-## Builder-account requirements
-
-Hyperliquid requires the builder address to:
-
-1. Use Manual / Standard account mode.
-2. Maintain at least 100 USDC in perps account value.
-3. Use standard account abstraction for builder-fee accrual.
-
-The public preparer does not inject a signature, approval, API-wallet credential, or broadcast call. `hlPrepareBuilderFeeApproval()` returns the unsigned approval envelope, while `hlPreparePerpOrder()` and `hlPrepareBracketOrder()` disclose the builder address and fee before wallet review.
-
-Official specification: [Hyperliquid builder codes](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes).