@pickhooks/sdk 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pickhooks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,419 @@
-# Temporary Holding Version
+# @pickhooks/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Read, quote, trade and launch on [pickhooks](https://pickhooks.com) from a bot, a launchpad or a trading terminal. BNB Chain, TypeScript, built on [viem](https://viem.sh).
+
+Every pickhooks product, one client:
+
+* **hook any coin** (`ph.any`): a PancakeSwap Infinity pool next to any coin that already trades. After every swap the pool's hook closes the gap to the coin's PancakeSwap V2 pair in the same transaction (**arb recapture**) and books a quarter of that profit to the trader. Fees and recapture profits are split between the pool's opener, a **partner** that brought the pool, a **router** that sent the trade, and pickhooks. A second line takes flap tax coins, their tax included.
+* **sticky rules** (`ph.sticky`): coins whose rules stick to the coins, not to the wallet. Launch one from templates, read its table, and ask the coin which rule would stop a trade before anyone signs.
+* **coins with rules** (`ph.coins`): the v1 and v2 coins, with their rules in the coin (also find the dev and CZ mode coins). Rules as sentences, the rule that would refuse a trade, launches.
+* **pools** (`ph.pools`) and **curve calls** (`ph.calls`): coins with their rules in the pool's hook; renting a step of a coin's curve.
+* **Lever** (`ph.lever`, the first lever: `ph.leverV1`): longs and shorts on a coin's own liquidity.
+* **dip bids** (`ph.dips`): floors at a strike, bought from a maker's bid.
+* **agents** (`ph.agents`): coins run by an agent that rewrites their rule program live, inside limits the chain checks. Read a coin's program as sentences, **be the agent yourself** (`brief` hands any model the pickhooks pilot's own prompt, `act` sends what it decided), veto a change or fire the agent as a holder, launch an agent coin with your own bot as its pilot.
+* **watch** (`ph.watch`): live events for terminals and bots: every launch on the pad, every trade of a coin, everything that happens to an agent coin.
+* **wallet** (`ph.wallet`): one address in, everything it holds on pickhooks out: coins by mode with what is sellable right now, BNB owed by the hooks, coins locked at the agents desk, dip bid floors.
+
+For a terminal the point is the same everywhere: before a trade is signed, the SDK asks the coin, and a refusal comes back as the rule's sentence ("Refused by the rule "Max per buy". No buy over 0.5% of supply.") instead of "honeypot".
+
+```bash
+npm install @pickhooks/sdk viem
+```
+
+```ts
+import { createPickhooks } from "@pickhooks/sdk";
+import { createWalletClient, http, parseEther } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { bsc } from "viem/chains";
+
+const walletClient = createWalletClient({ account: privateKeyToAccount(KEY), chain: bsc, transport: http() });
+const ph = createPickhooks({ walletClient });
+
+const [pool] = await ph.any.pools({ limit: 1 });
+const r = await ph.any.buy({ pool, bnbIn: parseEther("0.05") });
+console.log(r.amountOut, r.recapture); // coins bought; the recapture of this transaction and your share of it
+await ph.any.claim(); // your recapture shares (and, as an opener or partner, those shares)
+```
+
+Without a `walletClient` everything that only reads works. Every write also exists as a builder (`ph.any.build.*`, `ph.sticky.build.*`) that returns plain `{ to, data, value, extraGas }` for wallets, multicalls and your own router contracts.
+
+## Who earns what (hook any coin)
+
+| who | what | how it is paid |
+|---|---|---|
+| the trader | 25 % of every recapture its swap made possible | `claim()` |
+| the opener | 35 % of the pool's BNB fees and of what is left of each recapture after the trader's share (part of it can feed a jackpot) | `claim()` |
+| a partner | its listed share (up to 50 %) of the pickhooks part of every fee and recapture in pools opened with it | `claim()` |
+| a router | its listed share (up to 50 %) of the pickhooks part of the fee of every buy it sends, and of the recapture profit its trades create | `claimRouter()` from the payout wallet |
+
+The trader share applies to pools opened from now on (factory `traderBps`, each pool keeps its own). Partners and routers are listed by pickhooks (`partnerBps(partner)`, `router(contract)`): ask to be listed.
+
+**A router is the contract that calls the pool manager.** Trades through PancakeSwap's UniversalRouter come from the UniversalRouter; a terminal with its own router contract is listed by that contract's address and gets paid to a wallet it names. Buy fees are credited at the swap and funded when the pool's fees are collected (`collect`: anyone can call it, and pickhooks' keeper runs it); recapture shares are funded at once. `earnings(payout).routerClaimable` is what `claimRouter()` pays now.
+
+## Gas: the recapture room
+
+The hook recaptures inside the trader's transaction, after the swap, with its own gas budget (600k plus a 250k reserve). A wallet's plain estimate leaves that out, so the swap goes through without a recapture. Trades built by the SDK carry `extraGas: 900_000n`; `sendTx` uses estimate x 1.3 + extraGas. Only the gas used is paid (a recapture uses about 400k). Pass `recapture: false` to trade without the room. A terminal that routes through its own contract leaves at least 850k gas for the hook's `afterSwap`.
+
+## hook any coin: `ph.any`
+
+Reading
+
+```ts
+await ph.any.terms();                 // { owner, platformWallet, openerBps, traderBps, hook }
+await ph.any.pools({ limit, offset }); // newest first: id, key, token, symbol, config, counters, positions, price
+await ph.any.pool(id);                // one pool, or null
+await ph.any.poolsOf(token);          // every pool of a coin (one per slot)
+await ph.any.check(token);            // can this coin get a pool? price, price source, depth, free slot, pair
+await ph.any.earnings(wallet);        // { owed, routerCredit, routerClaimable, partnerBps }
+await ph.any.router(contract);        // { payout, bps }
+await ph.any.partnerBps(partner);
+await ph.any.bonusOf(pool, wallet);   // lock to earn
+await ph.any.pendingFees(pool);       // what a collect would book now
+```
+
+Trading (BNB in for buys, BNB out for sells; `pool` is an id, a key or a pool from `pools()`)
+
+```ts
+const q = await ph.any.quote({ pool, side: "buy", amount: parseEther("0.1"), from: me }); // quote = fill
+const b = await ph.any.buy({ pool, bnbIn: parseEther("0.1"), slippageBps: 100 });
+const s = await ph.any.sell({ pool, amount: b.amountOut / 2n });  // approves Permit2 once, then the router for 30 days
+// b.amountOut, b.recapture { profit, toTrader, soldHere }, b.routerCredit, b.hash, b.receipt
+```
+
+Building instead of sending
+
+```ts
+const key = await ph.any.key(poolId);
+const tx = ph.any.build.buy({ key, bnbIn, minOut });  // { to: UniversalRouter, data, value, extraGas }
+const approvals = await ph.any.sellApprovals(owner, key.currency1, amount); // TxRequest[]
+ph.any.readTrade(receipt);                              // the trade, the recapture and the router credit of a receipt
+```
+
+Opening a pool (as a launchpad or bot, with yourself as the partner)
+
+```ts
+const c = await ph.any.check(coin);                   // c.ok, c.text, c.depth (BNB in the coin's main pool)
+const need = ph.any.depthNeeds(c, "ladder10", c.freeSlot!); // coins a pool needs to be as deep (the factory refuses a shallower one)
+const { id } = await ph.any.open({ token: coin, tokenAmount: need.coins, partner: MY_PARTNER_WALLET });
+ph.any.partnerLink(MY_PARTNER_WALLET);                // the site's open form with you named as partner
+```
+
+Options and their defaults (the site's): `range` `"ladder10"` (coins only, up to 10x; `"ladder"` no top; `"around"` with BNB), `feeBps` 30, `holderFeeBps` 5 for wallets with `holderMin` 10,000 $hooks, `chestBps` 200 (the fire), `bonus` 5 % locked 7 days for buys from 0.05 BNB (`false` for none), `jackpot` off, `recapture` true, `maxMoveBps` 100. Each position stays in the pool 30 days.
+
+Payouts and pool tools: `claim()`, `claimRouter()`, `collect(pool)`, `settleJackpot(pool)`, `fundPot(pool, wei)`, `feedChest(token, amount)`, `fundBonus(pool, amount)`, `lockBonus(pool, amount)`, `unlockBonus(pool)`, `addLiquidity(pool, range, coins, bnb)`, `removeLiquidity(pool, index)`, each also under `build`.
+
+### The tax line (flap tax coins)
+
+Flap tax coins keep their tax in a pickhooks pool: buyers and sellers pay it like on the coin's main pool, and the tax goes where the coin sends it. They open on a second factory with its own hook (`addresses.anyTaxFactory`; `ph.any.taxLineOn` says whether it is set). The SDK routes for you: `check(token)` names the line (`line: "main" | "tax"`, with the coin's live tax in `tax`), and `pools()`, `pool()`, `quote()`, `buy()` and `sell()` work on both.
+
+```ts
+const c = await ph.any.check(taxCoin);           // c.line === "tax", c.tax { buyBps, sellBps, ... }
+const t = await ph.any.taxOf(taxCoin);           // the tax as it runs now
+const fit = fitLadder(c, coins, c.freeSlot!, t.sellBps); // the range a ladder of `coins` needs to be as deep as the main pool
+const q = await ph.any.quote({ pool, side: "buy", amount }); // { amountOut (after tax), gross, taxBps }
+await ph.any.sell({ pool, amount });             // while the anti-farmer tax runs: pays the coins in first, then swaps
+await ph.any.claim({ line: "tax" });             // the opener's side of the tax line's fees
+```
+
+While a coin's anti-farmer tax runs, a sell in its pickhooks pool must pay its coins in first; a plain router sell is refused with `PayFirst`. The SDK's `sell()` does it right; terminals that route themselves sell such coins in their main pool.
+
+## sticky rules: `ph.sticky`
+
+```ts
+import { TEMPLATES } from "@pickhooks/sdk";  // hold, sniper, devlock, drip, maxbuy, maxwallet, window, hours, burn, dipdrop, lucky, wakeup
+
+const picks = [
+  { id: "sniper", params: { b: 20, h: 24 } },  // buys in the first 20 blocks are marked; marked coins cannot sell for 24 h, in any wallet
+  { id: "devlock", params: { d: 7 } },         // the creator's first buy cannot sell for 7 days
+  { id: "lucky", params: { pot: 2, n: 25, share: 100 } },
+];
+const table = ph.sticky.compile(picks);       // { rows, release, problems }
+await ph.sticky.validate(table.rows, table.release); // null, or the validator's reason as a sentence
+const { token } = await ph.sticky.launch({ name, symbol, metadata: "https://…/meta.json", picks, devBuy: parseEther("0.05") });
+```
+
+A launch costs the factory's seed (0.01 BNB, into the coin's V2 pair) plus the creator's first buy; the creator gets half of the fees the coin's pool earns (`keepBps` of it, the rest buys back and burns $hooks). `metadata` is a link to the coin's JSON (name, symbol, description, image, website, twitter, telegram): host your own, or let pickhooks.com host it: `prepareMetadata({ name, symbol, description, website, twitter, telegram, image })` returns `{ metadata, image }`.
+
+```ts
+await ph.sticky.coins({ limit });            // newest first: rows as sentences, scanner color, holders, pot, price
+await ph.sticky.coin(token);
+await ph.sticky.wallet(token, who);          // balance, sellable now, lots (amount, locked, since, marks)
+const v = await ph.sticky.check({ token, side: "sell", wallet, amount });
+// { ok: true } or { ok: false, row: 1, text: "Refused by rule 2: Sniper jail. A sell is refused when …" }
+await ph.sticky.buy({ token, bnbIn });       // quote, check, then the buy through the better of the coin's two venues
+await ph.sticky.sell({ token, amount });     // check first: a refusing rule stops it before anything is signed
+await ph.sticky.quote({ token, side: "sell", amount }); // { amountOut, venue: "v3" | "v2", v3, v2 }: the V3 pool and the V2 pair, the better one wins
+await ph.sticky.lift(token, row);            // the creator lifts a row for good
+```
+
+**Hook script: your own rows.** With the factory's custom switch on (`terms().custom`, on since 08.10.2026), a coin can carry the creator's own rows after the templates, written like the site's editor:
+
+```ts
+import { ACT, ON, OP, VAR, VARS } from "@pickhooks/sdk";   // VARS: every variable with its unit (minutes, % of supply, x, ...)
+
+const noBigSells = { on: ON.SELL, act: ACT.DENY, arg: 0, conds: [{ v: VAR.AMOUNT, op: OP.GE, x: 1 }] }; // no sell of 1 % of supply or more
+await ph.sticky.launch({ name, symbol, metadata, picks: [{ id: "devlock", params: { d: 7 } }], script: [noBigSells], devBuy });
+```
+
+The editor's checks run first (a row the site would refuse stops before anything is signed, in words), then the validator on chain. Rows that lock shares take `scriptHours` (10 minutes to 30 days).
+
+**The test run, before the launch.** The launcher's test run, offline: the table on a fresh coin with random trades (the creator's first buy, three snipers in the first blocks, wallets that buy, hold and sell, bags split to fresh wallets). It runs the coin's own rule engine, checked against the contract trade by trade. The same seed gives the same run.
+
+```ts
+const run = ph.sticky.testRun({ picks, script, devBuyBnb: 0.05, seed: 7, trades: 200 });
+run.report;   // refusals per row, longest wait to sell, snipers, split bags, when everyone is free, burn, pot, a scanner's test
+run.text;     // the same as sentences: "A scanner's test: its sell right after the buy is refused by rule 1, Hold time: it can show a honeypot."
+```
+
+Numbers left out of a pick take the template's defaults (`{ id: "hold" }` is a hold time of 30 minutes); `ph.sticky.table({ picks, script })` returns the rows and release a launch would send.
+
+Sticky coins trade in a PancakeSwap V3 pool of 1 % and a V2 pair, so any router can trade them. For a terminal the point is `check()`: instead of "honeypot", show the row that stops the trade, in words.
+
+**A quote that a rule refuses.** PancakeSwap's QuoterV2 runs the swap, so a buy a rule refuses fails in the quoter, and the quoter does not pass the coin's reason on (it says "Unexpected error"). `quote()` of sticky coins and of coins with rules then checks the buy again with `estimateBuy(token, bnbIn)` (the pool's liquidity at its price) and throws the rule's sentence (`code: "Blocked"`). Pass `wallet` to check for that wallet. The estimate names rules; never use it as a minimum.
+
+## Coins with rules: `ph.coins`
+
+The v1 and v2 coins (`pickhooks.com/launch`): up to eight rules live in the coin itself and apply to every transfer with its PancakeSwap V3 pool.
+
+```ts
+import { RULES } from "@pickhooks/sdk";             // the catalog: id, kind, name, fields (also @pickhooks/sdk/coin-rules)
+
+await ph.coins.coins({ version: 2, limit: 20 });     // newest first: rules as sentences, holders, price
+const c = await ph.coins.coin(token);                // c.version, c.rules [{ name, text, ended }], c.extras
+const v = await ph.coins.check({ token, side: "buy", wallet, amount: await ph.coins.estimateBuy(token, bnbIn) });
+// { ok: true } or { ok: false, kind: 2, name: "Max per buy", text: "Refused by the rule "Max per buy". No buy over 0.5% of supply." }
+await ph.coins.buy({ token, bnbIn });                // quote, check, buy; a refusing rule stops it before anything is signed
+await ph.coins.sell({ token, amount });
+```
+
+`check()` runs the coin's own transfer in an `eth_call` (a buy: the coins leaving the pool to the wallet), so the answer is the coin's, not a copy of its logic.
+
+Launching (v2):
+
+```ts
+const rules = [
+  { id: "max_wallet", values: { cap: 1 } },              // % of supply
+  { id: "max_tx", values: { cap: 0.5 } },
+  { id: "buyout", values: { rules: "2", price: 0.1 } },  // anyone can buy rule 2 off for 0.1 BNB
+];
+const L = await ph.coins.launch({ name, symbol, metadata, rules, devBuy: parseEther("0.02") });
+// L.token, L.burned: rules that need $hooks burn it in the launch, bought with BNB (payBurnIn: "hooks" uses yours)
+```
+
+`burnFor(mask)` says what a set of rules burns and the BNB it costs. After launch: `wallet(token, who)`, `pendingFees(token)`, `collect(token)` (anyone; the creator gets its side), `claim(token)`, `buyout(token, kind)`, `fundPot(token, "jackpot" | "rewards", wei)`, `settleJackpot`, `withdrawRewards`, `poke`, `alive`, `release`, and under `build` the vote, duel, floor and payroll steps.
+
+## Pools and curve calls: `ph.pools`, `ph.calls`
+
+Pool coins carry their rules in a PancakeSwap Infinity pool's hook instead of the coin; they trade through the UniversalRouter (Permit2 for sells).
+
+```ts
+await ph.pools.knownKinds();                          // the rules a pool can carry (Max wallet needs the coin, so no)
+const P = await ph.pools.launch({ name, symbol, metadata, rules: [{ id: "max_tx", values: { cap: 0.5 } }], devBuy });
+await ph.pools.check({ token, side: "buy", wallet, amount }); // the quoter runs the hook as the buyer and names the rule
+await ph.pools.buy({ token, bnbIn }); await ph.pools.sell({ token, amount });
+await ph.pools.owed(creator); await ph.pools.claim();  // the creator's share, booked on every swap
+```
+
+`ph.calls` is the same for curve calls coins, plus the desk:
+
+```ts
+const steps = await ph.calls.steps(token);            // the steps above the price that are open (none in a coin's first 10 minutes)
+const q = await ph.calls.quoteCall(token, step, coins, seconds); // { premium, liquidity }
+const { id } = await ph.calls.openCall({ token, step, coins, seconds });
+await ph.calls.payout(id, me);                        // what closing pays now
+await ph.calls.closeCall(id);                         // the payout and the bond come back
+await ph.calls.withdraw();                            // anything the desk holds for you (ph.calls.pending(me))
+```
+
+## Lever: `ph.lever` and `ph.leverV1`
+
+```ts
+const m = await ph.lever.coin(token);                 // the Lens: price, room for longs and shorts, open longs and shorts
+const o = await ph.lever.quoteOpen(token, "long", gross, 2); // o.reason 0 = it opens; otherwise o.text says why
+const { id } = await ph.lever.open({ token, side: "short", gross, leverage: 2 });
+await ph.lever.positions(token);                      // { longs, shorts }: owner, margin, trigger, closeNet (what closing pays now)
+await ph.lever.close({ token, side: "short", id });
+await ph.lever.sell({ token, amount });               // sellPlan() splits a sale around open shorts when it must
+await ph.lever.claim(token, "creator");               // "creator" | "refund" | "platform"
+```
+
+`grossForMargin(margin, leverage)` is the BNB to send for a margin. `ph.leverV1` is the first lever (engine curve, longs only): `quoteBuy`, `quoteSell`, `quoteOpen`, `buy`, `sell`, `openLong`, `closeLong`, `closeExpired`, `claimRefund`, `claimCreator`, `launch`.
+
+## Dip bids: `ph.dips`
+
+A maker posts a bid: BNB that buys coins at a strike, in floors that holders buy for a premium. A holder with a floor can sell up to its cover at the strike while it runs, even after a dip.
+
+```ts
+const { id } = await ph.dips.post({ token, price: 0.000000003, duration: 86_400, premiumBps: 500, until, minCover, deposit });
+await ph.dips.bids(token);                            // the coin's bids
+const q = await ph.dips.quote(id, coins);             // { cover, premium, fee, payout }
+const f = await ph.dips.buyFloor(id, coins);          // f.id: the floor
+await ph.dips.exercise({ floorId: f.id, coins, token }); // approval, a dry run, then the coins go to the maker for BNB
+await ph.dips.close(id);                              // the maker takes the free BNB back
+```
+
+`strikeFromPrice(bnbPerCoin)`, `coverOf(strike, coins)` and `coinsFor(strike, cover)` convert; the strike is BNB wei per whole coin.
+
+## HOOKS infra: `ph.infra`
+
+On mainnet since 09.10.2026 (executor `0xCCea8f8195Dd3c62C28e218C002316e67B95bb36`, floor factory `0xcaA38326d43071e5a7a940c144042a14DC42086F`; `ph.infra.on` says which part is live).
+
+* **Floors:** a BNB reserve under a coin (one per coin, anyone can open and feed it). A holder hands coins in for reserve / circulating, less 2 % (1 % stays and lifts the floor, 1 % to the protocol); the coins go to 0xdead. No owner, no withdraw: the floor only rises.
+* **Protected buy:** one transaction buys through PancakeSwap's own routers and a dip floor for what arrived. pickhooks.com picks the route and the bid; `protect()` sends what the site built, after checking it goes to the executor.
+
+```ts
+const f = await ph.infra.floorOf(token);          // { floor, reserve, circulating, perCoin, totalFed, totalPaid, totalRedeemed }
+await ph.infra.quoteRedeem(token, coins);         // { payout, kept, protocolFee }
+await ph.infra.redeem({ token, coins });          // approval, then the hand in (quote less 0.5 % as the minimum)
+await ph.infra.feed(token, parseEther("1"));      // more BNB under the coin
+await ph.infra.open({ token, seed });             // the coin's first floor
+const o = await ph.infra.offer({ token, bnbIn }); // the route, the bids that can cover it, the transaction
+await ph.infra.protect({ token, bnbIn });         // { coins, floorId, premium }
+```
+
+## sticky 2 and its desks: `ph.sticky2`, `ph.cover`, `ph.auction`, `ph.dark`, `ph.launchDesk`
+
+On mainnet since 11.10.2026 (factory `0xB9b90378Cf621a625a4AcBA9B95a7f204e6Df54c`, dev cover `0xf6e66a4DadfB0700603342D244dE6F999B2725DF`, rule auction `0x874CA64571774f2ae0A3fFa0A578B046910aDb35`, dark launch `0x304c6604e96627FDdc7a94b7a691A0673A80F765`, launch desk `0x81508f3fCc535c29a49226E61D39188b6D479d61`). On a fork, pass other addresses with `createPickhooks({ addresses })`.
+
+* **sticky 2** (`ph.sticky2`): everything `ph.sticky` does, on the second factory. The coin also counts what its creator sold, from any wallet the DEV coins went through, and can carry switch rows: rows that are off until a switcher (the rule auction) turns one on.
+* **dev cover** (`ph.cover`): a writer puts BNB on a coin against its creator selling. A holder buys a policy for a premium; when the creator's sold share reaches the offer's mark (10, 25, 50 or 100 %), the policy pays its cover. Posted by the creator itself, it is a dev bond. A policy can only cover what the holder's coins are worth.
+* **rule auction** (`ph.auction`): holders burn coins for one of the coin's switch rows; at the end of each round the game with the most burned is turned on.
+* **dark launch** (`ph.dark`): a round before the coin exists. Bids show their BNB but seal their top price to a drand round that is signed only after the bidding. Once signed anyone opens the bids, everyone buys at one price, and the coin is born at that price with BNB on both sides. The round's BNB sits in the coin's V2 pair, so right after the birth a sell routes there (`quote` picks the venue; a sell into the one sided V3 curve would get almost nothing). Terminals do the same by themselves.
+* **launch desk** (`ph.launchDesk`): a wallet's BNB that the pad's reply bot may launch with, only for that wallet, within the limits the wallet set.
+
+```ts
+await ph.sticky2.devCounters(token);                  // { bought, sold, soldBps, at: { 10, 25, 50, 100 } }
+await ph.sticky2.switches(token);                     // { mask, on, switcher }
+await ph.sticky2.launch({ name, symbol, metadata, picks: [{ id: "lucky" }, { id: "dipdrop" }, { id: "wakeup" }], switchRows: [1, 3, 5] });
+                                                      // drop rows that switch; the rule auction runs them
+
+const { id } = await ph.cover.post({ token, mark: 25, premiumBps: 300, duration: 86_400, stopBps: 1000, deposit });
+await ph.cover.offers(token);                         // with `bond` when the creator wrote it, `live` when it sells
+const q = await ph.cover.quote(id, cover);            // { premium, fee, payout }
+const p = await ph.cover.buy(id, cover);              // pays exactly the quoted premium; p.id is the policy
+await ph.cover.claim(p.id);                           // once the creator's sold share reached the mark
+
+await ph.auction.state(token);                        // { round, endsAt, burned[8], mask, on, settleable }
+await ph.auction.burn(token, game, amount);           // approval, then the burn
+
+await ph.dark.round(roundId);                         // endsAt, drandRound, state (0 bidding, 1 born, 2 failed), step, token
+await ph.dark.prices();                               // BNB per coin at each of the 24 steps
+const b = await ph.dark.bid({ roundId, step: 9, deposit }); // seals step 9 to the round's drand round, then bids
+await ph.dark.owedOf(b.id);                           // { coins, paid, claimableNow }
+await ph.dark.claim(b.id);
+const o = await ph.dark.opener(roundId);              // once drand signed: the open transaction (anyone may send it)
+```
+
+The seal is time-lock encryption to drand quicknet, the same scheme as find the dev. `@pickhooks/sdk/tlock` holds it on its own entry (`encrypt`, `decrypt`, `darkMessage`, `fetchRoundSig`, `roundAt`), so the main import does not load BLS12-381.
+
+## Agents: `ph.agents`
+
+On mainnet since 09.10.2026 (factory `0x5965e2D2128248ac2CB4FFf312CFB098a1eDA232`). An agent coin is a plain ERC20 in a PancakeSwap Infinity pool whose hook runs a **program**: the fee on each side (1 % up to the coin's cap), where the coin's part of every fee goes (burn, liquidity the coin owns for good, its HOOKS floor, a rewards pot, a jackpot, the creator, the treasury) and up to eight pool rules. The **pilot** (any wallet: the pickhooks agent, your bot, a model behind an MCP server) proposes a whole new program; the desk checks it against the coin's **envelope** (limits fixed for good at launch: max fee, max creator share, allowed rules, notice, gap, veto and fire shares) and the limits every agent coin lives with (sells can never be closed for good, no rule names a wallet, BNB never leaves the coin). The change is announced and lands after the notice; holders lock coins to **veto** it or to **fire** the pilot. Every router trades the coin.
+
+```ts
+const c = await ph.agents.coin(token);               // program as sentences (c.lines), env, pending change, fire tally, buckets, runs, price
+await ph.agents.coins({ limit: 20 });                // newest first
+await ph.agents.quote({ token, side: "buy", amount: parseEther("0.01"), from });   // a refusing rule comes back as its sentence
+await ph.agents.buy({ token, bnbIn }); await ph.agents.sell({ token, amount });    // through the UniversalRouter, rules checked first
+
+// be the agent: the pickhooks pilot's prompt for any model, its answer back into a transaction
+const b = await ph.agents.brief(token);              // { system, user, schema, look, profile }
+const answer = await yourModel(b.system, b.user, { schema: b.schema });            // { title, body, action, plan, move, expect }
+const { tx, proposal } = await ph.agents.act(token, answer);                       // propose / move / null for "none"
+if (tx) await ph.send(tx);                           // from the pilot's wallet (or ph.agents.pilot(token, answer) in one go)
+
+// or write the program yourself, in plain units
+await ph.agents.propose(token, { buy_fee_pct: 1.5, sell_fee_pct: 2, route: { burn: 50, lp: 20, floor: 10 }, rules: [{ id: "max_buy", values: { cap_pct: 1 } }] }, { title, body });
+ph.agents.problemsOf(program, env);                  // the limits' problems, offline; checkProgram(token, program) asks the desk (eth_call as the pilot)
+await ph.agents.move(token, "treasury", "burn", wei); await ph.agents.cancel(token); await ph.agents.handOver(token, to);
+
+// holders
+await ph.agents.veto(token, coins); await ph.agents.fire(token, coins); await ph.agents.withdraw(token);
+await ph.agents.activate(token);                     // anyone lands a change that is due (the pickhooks keeper does too)
+await ph.agents.burn(token); await ph.agents.addLiquidity(token); await ph.agents.feedFloor(token);   // the runs anyone may trigger
+
+// launch with your own pilot
+const { metadata } = await ph.agents.prepareMetadata({ name, symbol, image, agent: { name: "whiskers", personality: "degen", objectives: ["depth"], mission } });
+await ph.agents.launch({ name, symbol, metadata, plan, envelope: { maxFeeBps: 500, notice: 1800 }, pilot: myBot, devBuy });
+```
+
+`ph.agents.catalog()` is the vocabulary as plain data: the 18 rules an agent may use with their fields, the limits, the buckets, the personalities and objectives of a profile, the ABI tuples, the answer schema. The catalog, the pilot's prompt and the answer schema are a checked port of the site's and the keeper's (`npm run check`), so a bring your own agent runs on the same text the pickhooks agent does. The main import holds it all; `AGENT_RULES`, `toProgram`, `describeProgram`, `systemPrompt`, `ANSWER_SCHEMA`, `noteHash`, `parseAnswer` are exported on their own.
+
+## Live events: `ph.watch`
+
+Each watcher polls the RPC (HTTP is enough; `pollingInterval` default 3 s) and returns a function that stops it.
+
+```ts
+const stop = ph.watch.launches((l) => console.log(l.mode, l.symbol, l.token), { modes: ["sticky", "agents"] });
+const stop2 = await ph.watch.trades(token, (t) => console.log(t.buy ? "buy" : "sell", t.coins, t.bnb ?? t.fee, t.trader));
+const stop3 = await ph.watch.agent(token, (e) => console.log(e.event, e.args));   // Proposed, Activated, Vetoed, PilotFired, Burned, ...
+```
+
+`launches` covers every factory (sticky, rules v2 and v1, pools, curve calls, Lever, agents, hook any coin's new pools; `ph.watch.modes` lists the live ones) and reads name and symbol from the token. `trades` finds the coin's mode itself: the hook's `Traded` events for pools, curve calls, agents and hook any coin pools, the `Swap` events of the PancakeSwap V3 pool and V2 pair for sticky and rules coins.
+
+## One address: `ph.wallet`
+
+```ts
+const w = await ph.wallet(address);
+w.coins      // every pickhooks coin it holds: mode, name, symbol, balance, sellable now (sticky: the unlocked lots; others: the coin asked for the whole balance, the refusal in words), price, value, page
+w.claims     // BNB owed: hook any coin (recapture shares, router credits), pools, curve calls, agents; totalBnb
+w.locks      // coins locked at the agents desk, per coin, and what they back (a veto, the firing)
+w.floors     // dip bid floors it holds
+w.scanned    // the factories covered and how many of their coins (the newest `limit` each, default 300)
+```
+
+## Building blocks: `ph.blocks`
+
+The vocabulary of every rule, as plain data and offline: sticky rules' 12 ready blocks (numbers with their ranges, the sentence, the rows they make, what scanners show), the hook script grammar (triggers, actions, marks, variables with their units, operators, the checks a table must pass) and the rule book of coins with rules (each rule with its fields).
+
+```ts
+const c = ph.blocks.catalog();          // { version, sticky: { blocks, script, promises, limits }, coinRules: { groups, rules } }
+ph.blocks.block("sniper");              // { name, line, example, params, rows, scanner, sticky }
+await ph.api.blocks();                  // the same object from pickhooks.com/api/blocks, once the site serves it
+```
+
+It is built from the same files as the site's launchers (a checked copy), so a terminal, a bot or an agent can explain a coin's rules or compose a table without guessing.
+
+## pickhooks.com's API: `ph.api`
+
+`launches({ since, before, limit })`, `launch(address)`, `coins()`, `activity()`, `official()`, `burners()`, or `get(path, query)`. No key; a limit per address per minute.
+
+## Errors
+
+Every failure is a `PickhooksError` with `code` (the contract's error name, or `wallet`, `funds`, `pancake`, `reverted`, `input`) and a sentence as `message`. `explain(err)` turns any error (also from your own viem calls) into `{ code, text }`, including hook errors that PancakeSwap wraps.
+
+## Addresses (BNB Chain)
+
+| | |
+|---|---|
+| hook any coin v3 factory | `0x1662668Ab8FaA612A7F615F1AccB90ceC20be117` |
+| hook any coin v3 hook | `0x49892253A5E71f5DF0Fbc118bd7c15acAF55F767` |
+| sticky factory | `0x385C273bDaBC5a0788dfBb648F05bE0C5EE018fd` |
+| sticky validator | `0x057007a21330EA770f2Fcb61c8925C28c270480f` |
+| coins with rules v1 factory | `0xecED45Ae3e85D947038009710594a50d422A54D8` |
+| coins with rules v2 factory | `0x23cC366e1DDBc41CFD70011C4AaC14B79998B24F` |
+| pools factory | `0x3F97831C8296D934d84357B619CfC44D32d0241B` |
+| curve calls factory | `0x98D49C17458def2e5fdF00F20479658693498301` |
+| Lever factory | `0x03EbF1558E2f9337E4d2FfCAcE3A5114aC32A87A` |
+| Lever Lens | `0x3f1a660FC365Af192acE4E761657cE61A6ED0F13` |
+| lever (v1) factory | `0xeaB93e923170bd5331Db4300aF6F2555eBBF9615` |
+| dip bids desk | `0xc73bcB859C3fD5Bd38A10B0aD9A862EAAf6765bf` |
+| HOOKS executor (protected buy) | `0xCCea8f8195Dd3c62C28e218C002316e67B95bb36` |
+| HOOKS floor factory | `0xcaA38326d43071e5a7a940c144042a14DC42086F` |
+| agents factory | `0x5965e2D2128248ac2CB4FFf312CFB098a1eDA232` |
+| the pickhooks agent (pilot wallet) | `0x85b85b75806446BB7AFa324D67B20cc1C29eCFB5` |
+| $hooks | `0x07bcB8E8226f671300e135b4A61Dc157359b7777` |
+
+All verified on BscScan. `BSC_MAINNET` holds these and PancakeSwap's; `createPickhooks({ addresses })` points the SDK elsewhere (a fork). The tax line's factory is not set yet (`anyTaxFactory` is zero until it is on mainnet). ABIs: `@pickhooks/sdk/abis`; the drand time-lock: `@pickhooks/sdk/tlock`; the sticky encoder alone: `@pickhooks/sdk/rules`; the rule catalog of coins with rules: `@pickhooks/sdk/coin-rules`.
+
+## Examples
+
+* `examples/terminal.mjs`: pools, routing a buy, sticky rows and coins with rules with the rule that refuses a trade, a wallet's earnings (read only)
+* `examples/bot.mjs`: quote, buy with the recapture room, sell, claim
+* `examples/launchpad.mjs`: a sticky launch from templates, a pool with you as the partner, the partner's claim
+
+They send nothing without `--send`.
+
+## Tests
+
+`npm test` (offline: pool ids, ranges, building, errors, the rule compiler, the time-lock against the site's copy). On a local BSC fork (`scripts/fork.sh`, anvil) against the live contracts: `npm run fork-proof` (hook any coin and sticky rules) and `npm run fork-proof-2` (coins with rules, pools, dip bids, Lever, lever v1, curve calls, and the tax line, which it deploys on the fork from a throwaway key). `npm run fork-proof-infra` runs floors and the protected buy on the infra rehearsal fork (`script/infra/rehearsal-fork.sh`, contracts deployed there by a throwaway key) against a dev server of the site. `npm run check` confirms the rule catalogs and the building blocks catalog are the site's, and that the agents catalog and the pilot's prompt behave like the site's and the keeper's. `node test/mainnet-read-agents.mjs` reads the agents, watch and wallet parts against mainnet (nothing sent); the fork proof of those parts lives with the MCP server (`mcp/test/fork-proof-agents.mjs`: launch, trades, a model's answer landing through the desk, veto, fire, the watchers seeing it all).