# @captainhook/sdk

TypeScript source for building on Captain Hook, on [viem](https://viem.sh). It does four things:

- reads a token's pool;
- quotes with the contracts' own maths;
- builds ready-to-send buy, sell, approve, claim and launch calls;
- ships the contracts' ABIs and addresses.

It never signs or sends anything: you pass its calls to your own wallet client.

Captain Hook runs on Robinhood Chain mainnet (chain id 4663). Docs: https://www.captainhook.tech/docs. For AI agents there's also a skill file: https://www.captainhook.tech/skill.md.

## Use it

It's source, not a published npm package. Copy `src/` into your project, or depend on this folder. It needs `viem` 2.

```ts
import { createPublicClient, createWalletClient, custom, http, parseEther } from "viem";
import { buy, deadline, minOut, quoteBuy, readPool, robinhood } from "./captainhook-sdk";

const client = createPublicClient({ chain: robinhood, transport: http() });
const pool = await readPool(client, "0xToken…");
if (!pool) throw new Error("Not a Captain Hook token");

// What 0.05 ETH buys now. `over` says if a size cap would refuse it.
const q = quoteBuy(pool, 0.05);

const wallet = createWalletClient({ chain: robinhood, transport: custom(window.ethereum) });
const [account] = await wallet.getAddresses();
const call = buy({ key: pool.key, eth: parseEther("0.05"), minOut: minOut(q.out), to: account, deadline: await deadline(client) });
// Simulate first: it gives the exact amount and catches a refusal before you pay gas.
const { request } = await client.simulateContract({ ...call, account });
await wallet.writeContract(request);
```

## What's in it

| Export | What it does |
|---|---|
| `ADDRESSES`, `robinhood` | Captain Hook's hook, factory, router and Uniswap's pool manager, v2's in `ADDRESSES.v2`, and the chain |
| `factoryAbi`, `hookAbi`, `routerAbi`, `tokenAbi`, `poolManagerAbi`, `factoryV2Abi`, `hookV2Abi`, `routerV2Abi`, `vaultAbi` | The contracts' ABIs |
| `poolKey(token, hook)`, `poolId(key)` | A token's v4 pool key and id |
| `readPool(client, token)` | Its version, rules, caps, payouts and payees, v2's Wallet Cap and Exit Clock, price, reserves and launch time; `undefined` if it isn't a Captain Hook token |
| `readWallet(client, pool, account)` | On v2: what a wallet has bought under Wallet Cap, and its Exit Clock holding |
| `quoteBuy(pool, eth, now, wallet)`, `quoteSell(pool, tokens, now, wallet)` | Out-amount, fee, tax and exit fee, Auto Burn, and any size cap the swap breaks |
| `buy`, `sell`, `approveFor`, `approveRouter`, `routerFor`, `claim`, `claimFrom`, `claimCode`, `launch`, `launchV2` | Calls for viem's `simulateContract` / `writeContract` |
| `minOut(quote, slippage)`, `deadline(client)` | A swap's minimum out, and a deadline by the chain's own clock |
| `PLAIN`, `PLAIN_V2`, `LaunchParams`, `LaunchParamsV2` | Launch settings with no blocks, to spread and change |

## Things to know

- **A quote is an estimate.** A swap can still be refused if:
  - others used up Anti-Snipe's per-second cap first;
  - the wallet hit Max Transaction's per-second cap;
  - the price moved past `minOut`.

  Simulate before sending.
- **Two versions:** tokens launched on v1 stay on v1; v2 sits beside it on the same pool manager. A pool's version is its hook (`pool.version`). `buy` and `sell` pick the right router from the pool key; approve `routerFor(key)` before a sell.
- **v2 extras:** Wallet Cap caps what each wallet buys in all while its window lasts, and Exit Clock charges sells by how long the seller has held its own buys. Buy into the wallet you'll sell from: a buy with another `to` gives that wallet no time held. Pass `readWallet(...)` to the quotes for both. Buys with Buyback & Burn on can set off a buyback, which adds about 100k gas: pad gas estimates. On v2, `buy` and `sell` take a `referrer`, which ties the trader to them on their first referred trade.
- **Use Captain Hook's router on v2.** Swaps through any other router or contract can't trade during an Allowlist Phase, can't buy while Wallet Cap is on, and pay Exit Clock's full starting fee.
- **The creator is whoever sends `launch`.** Send it from the creator's own wallet, never through a forwarder or multicall contract.
- **Units:** fees, taxes and shares are in pips (1,000,000 = 100%). Windows are in seconds. Token amounts are in base units (18 decimals).
- **Launch settings:** `factory.toRules(settings, supply)` checks them without launching. It reverts with `BadSetting(name)` on the first one out of range.
- **Generated files:** `src/abi.ts` and `src/deployments.ts` come from the deployed contracts. Don't edit them.