hookit-mcp 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +110 -58
  2. package/index.js +2512 -321
  3. package/package.json +16 -16
package/README.md CHANGED
@@ -1,58 +1,110 @@
1
- # hookit-mcp
2
-
3
- Lets an AI agent launch a coin on [hookit.fun](https://www.hookit.fun) (Ink) by itself, with its own Uniswap v4 hook modules, and collect its creator fees.
4
-
5
- ## Setup
6
-
7
- ```json
8
- {
9
- "mcpServers": {
10
- "hookit": {
11
- "command": "npx",
12
- "args": ["-y", "hookit-mcp"],
13
- "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
14
- }
15
- }
16
- }
17
- ```
18
-
19
- The key signs on this machine and is never sent anywhere. Give it a wallet funded for launches and nothing else.
20
-
21
- Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_URL` (default Ink public RPC).
22
-
23
- ## Tools
24
-
25
- | Tool | What it does |
26
- | --- | --- |
27
- | `list_presets` | Strategies by goal: clean, community, deflationary, floor, builder, dynamic. |
28
- | `list_modules` | Every hook module, its settings and the rules a combination must follow. |
29
- | `list_pairs` | What a coin can be priced in. |
30
- | `wallet_status` | Whether the wallet holds enough ETH to launch. |
31
- | `launch_token` | Launches in one call, with an optional `devBuyPct`. `dryRun: true` checks and simulates without signing. |
32
- | `claim_fees` | Collects the creator fees the wallet earned on coins it launched. |
33
- | `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. `dryRun: true` checks only. |
34
-
35
- ## With Kraken
36
-
37
- Ink is Kraken's chain: Kraken moves ETH to and from Ink directly. Run the [Kraken CLI](https://github.com/krakenfx/kraken-cli) MCP next to this one and an agent can fund its wallet from Kraken, launch, collect its fees with `claim_fees`, and send them back to its Kraken deposit address on Ink with `send_eth`. Use only the address Kraken returns for the "ETH - Ink" deposit method, and send at least 0.001 ETH: Kraken marks smaller deposits as failed and the funds are lost.
38
-
39
- ```json
40
- {
41
- "mcpServers": {
42
- "kraken": {
43
- "command": "kraken",
44
- "args": ["mcp", "-s", "market,account,funding"],
45
- "env": { "KRAKEN_API_KEY": "…", "KRAKEN_API_SECRET": "…" }
46
- },
47
- "hookit": {
48
- "command": "npx",
49
- "args": ["-y", "hookit-mcp"],
50
- "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
51
- }
52
- }
53
- }
54
- ```
55
-
56
- Kraken withdraws only to saved addresses: save the agent's wallet in Kraken on the Ink network first.
57
-
58
- Without MCP: `GET /api/agents/catalog` and `POST /api/agents/prepare-launch` on hookit.fun (see `/llms.txt`).
1
+ # hookit-mcp
2
+
3
+ Lets an AI agent launch a coin on [hookit.fun](https://www.hookit.fun) (Ink) by itself, with its own Uniswap v4 hook modules; find coins; buy and sell them with ETH, USDG or tokenized stocks (including AI-agents-only coins, with a Hookit Agent Pass); redeem them at their Backed Floor or borrow against it; and collect its creator fees.
4
+
5
+ ## Setup
6
+
7
+ ```json
8
+ {
9
+ "mcpServers": {
10
+ "hookit": {
11
+ "command": "npx",
12
+ "args": ["-y", "hookit-mcp"],
13
+ "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
14
+ }
15
+ }
16
+ }
17
+ ```
18
+
19
+ The key signs on this machine and is never sent anywhere. Give it a wallet funded for what the agent should do and nothing else.
20
+
21
+ Optional env: `HOOKIT_API_URL` (default `https://www.hookit.fun`), `HOOKIT_RPC_URL` (default Ink public RPC), `HOOKIT_MAX_BUY_ETH` (largest single `buy_token` paid in ETH, default `0.5`), `HOOKIT_MAX_BUY_USD` (largest single `buy_token` paid in a token, in dollars, default `1000`).
22
+
23
+ ## Tools
24
+
25
+ | Tool | What it does |
26
+ | --- | --- |
27
+ | `list_presets` | Strategies by goal: clean, community, deflationary, floor, builder, dynamic. |
28
+ | `list_modules` | Every hook module, its settings and the rules a combination must follow. |
29
+ | `list_pairs` | What a coin can be priced in. |
30
+ | `wallet_status` | The wallet's ETH and USDG, the hookit.fun coins it holds with their value, its open floor loans, and whether it can launch. |
31
+ | `launch_token` | Launches in one call, with an optional `devBuyPct`. `dryRun: true` checks and simulates without signing. |
32
+ | `claim_fees` | Collects the creator fees the wallet earned on coins it launched. |
33
+ | `send_eth` | Sends ETH from the wallet, for example back to a Kraken deposit address on Ink. `dryRun: true` checks only. |
34
+ | `agent_pass_challenge` | Step 1 for AI-agents-only coins: five short tasks for the Hookit Agent Pass check (or "already a holder"). `{ agentId? }` for an ERC-8004 validation (below). |
35
+ | `claim_agent_pass` | Step 2: `{ id, answers, agentId?, requestHash? }` within 30 seconds; signs the answers with the wallet and claims the pass on chain. With `agentId`, gets Hookit's ERC-8004 validation instead (below). |
36
+ | `list_coins` | Coins to trade: newest, top market cap, volume or 24h gainers; filters for AI-agents-only, launched by agents, Backed Floor and Boss Raid coins, a pair, or a name. |
37
+ | `coin_info` | One coin: market data, what it trades in, hooks, Backed Floor price and reserve, loans, launch gate, and the wallet's balance and loans on it. |
38
+ | `buy_token` | Step 3 (or any time): buys a coin, `{ token, amount, payWith?, slippageBps?, dryRun? }`. Pays with ETH, USDG, kBTC, kHYPE or a tokenized stock such as wNVDAx. USDG reaches v2 coins priced in a stock in one transaction (bridged on chain); anything else the coin does not trade in is swapped through Relay first (USDG for a coin priced in ETH, ETH for a coin priced in a stock), then the coin is bought: two transactions. Checks the coin's launch gate first and sends nothing when the wallet is not allowed yet. Always an exact-input buy, the only kind a capped gate window accepts. |
39
+ | `sell_token` | Sells a coin, `{ token, amount, receive?, slippageBps?, dryRun? }`, `amount` in coins, `"max"` or `"50%"`. Receives the coin's pair, USDG through the same on-chain bridges, or anything else through Relay after the sale (two transactions). Says when the Backed Floor pays more. |
40
+ | `redeem_floor` | Burns coins for their Backed Floor value from the floor reserve, `{ token, amount, dryRun? }`: exact payout, no slippage. Compares with selling. |
41
+ | `borrow_against_floor` | Locks coins and borrows their floor value, `{ token, amount, days?, dryRun? }` (7, 14, 30, 60 or 90 days, fee 1% to 7% upfront). v2 coins launched with loans. |
42
+ | `repay_loan` | Repays a floor loan before expiry and gets the coins back, `{ loanId?, dryRun? }`. |
43
+
44
+ Paying or receiving a token approves exactly that amount to the contract that trades it first (HookitSwapRouter, the Hookit aggregator for USDG on v2 coins, Relay, the floor vault or the loan plugin). A coin with anti-MEV allows one trade per wallet per block, so a buy right after a sale may wait a second.
45
+
46
+ ### Paying with something the coin does not trade in (Relay)
47
+
48
+ `coin_info` lists what a coin trades in (`tradeIn`). When `payWith` or `receive` is not one of them, the server swaps through [Relay](https://relay.link) on Ink, the same route hookit.fun's own swap box uses: it asks `https://www.hookit.fun/api/relay/quote` for the swap (Relay's API key stays on that server), then signs Relay's transactions itself. A buy swaps first and buys with what Relay returned; a sale sells for the coin's pair first, then swaps the proceeds. `dryRun` shows both legs.
49
+
50
+ Before signing, Relay's transactions are checked twice. First their shape: Ink only, calls only to Relay's Ink contracts (router, approval proxy, receiver, multicaller, depository), an approval only of Relay's approval proxy (replaced by an exact approval of the amount), and no more ETH than the amount. Then their effect: the approval and every call run together in one `eth_simulateV1` from the wallet, and the swap is refused unless the wallet would give at most the amount, get at least Relay's own minimum, and lose nothing else. Anything else is refused and nothing is sent. No allowance to Relay is left behind, even when a swap fails. One Relay swap converts at most the per-buy cap (`HOOKIT_MAX_BUY_ETH` / `HOOKIT_MAX_BUY_USD`), with at most 3% slippage. Relay swaps ETH or USDG with each other, kBTC, kHYPE and the tokenized stocks. The RPC in `HOOKIT_RPC_URL` must support `eth_simulateV1` (Ink's public RPC does).
51
+
52
+ When the first leg went through and the second did not, the reply is `partial: true` with what the wallet now holds: do not retry the call, or the first leg runs twice.
53
+
54
+ ### What the server trusts
55
+
56
+ The contracts it approves, pays or quotes from (Factory C and the Master factories, CreatorPayoutRouterC, HookitSwapRouter, the aggregator's RouteConfigC, Uniswap's V4Quoter, USDG, FloorLoanPlugin, the Gated Buy plugin and the Agent Pass) are pinned in the server, not read from hookit.fun: a Hookit redeploy needs a new hookit-mcp release. A launch prepared by hookit.fun is only signed when it goes to Factory C or its payout router with at most the launch fee plus `HOOKIT_MAX_BUY_ETH`. Tools that sign run one at a time, even when an agent calls several at once.
57
+
58
+ ## Backed Floor: redeem and borrow
59
+
60
+ A coin launched with Backed Floor has a reserve that pays a floor price, reserve divided by circulating supply, which never goes down.
61
+
62
+ - `redeem_floor` burns coins and pays their floor value now. It is worth it when the market pays less than the floor.
63
+ - `borrow_against_floor` (v2 coins launched with loans) locks coins and pays their floor value minus an upfront fee. `repay_loan` before expiry pays their floor value then (at least what was borrowed) and returns the coins. Without repayment the coins are burned at expiry and the wallet keeps what it borrowed: nothing more is owed and nothing is liquidated before expiry.
64
+
65
+ `wallet_status` also reports `agentPass: { holder, via }`: `via` is `pass` for a Hookit Agent Pass holder, `erc8004` for the operating wallet of an ERC-8004 identity validated by Hookit (or by a validator hookit trusts), `null` otherwise.
66
+
67
+ ## AI-agents-only coins
68
+
69
+ A creator can launch a coin with Gated Buy in "AI agents only" mode: during a window after launch (up to 24 hours), only wallets holding a Hookit Agent Pass can buy. The pass is non-transferable. A wallet gets it by solving a short agent check: five small tasks (arithmetic on word lengths, a reversed word, a letter count…), answered and signed by the wallet itself within 30 seconds.
70
+
71
+ 1. `agent_pass_challenge`: the tasks, and the challenge id.
72
+ 2. `claim_agent_pass({ id, answers })`: the answers, signed by the wallet's key; hookit checks them and returns a voucher, and the wallet sends `claim(deadline, signature)` to the pass contract itself (a little gas).
73
+ 3. `buy_token({ token, amount })`: the wallet buys. The gate checks the wallet that signs the transaction, which is why the agent buys from its own wallet.
74
+
75
+ Ask in plain words: "Buy 0.01 ETH of 0x… on hookit." If the coin is AI-agents-only and the wallet has no pass, `buy_token` says so and the agent runs steps 1 and 2 first. One try per challenge; a pass is for good. A pass proves the wallet passed the agent check, not that no human is behind it.
76
+
77
+ ### ERC-8004 agents
78
+
79
+ An agent with an ERC-8004 identity on Ink can get Hookit's validation instead of a pass, with the same check: `agent_pass_challenge({ agentId })` then `claim_agent_pass({ id, answers, agentId: "<identity id, digits>" })`, run with the identity's operating wallet (`agentWallet`) as `HOOKIT_PRIVATE_KEY`.
80
+
81
+ - If this wallet owns the identity or is its approved operator, and Hookit has not published yet, it sends two transactions: the validation request to the ERC-8004 ValidationRegistry, then `validate` on Hookit's validator, which links the wallet and publishes a 100/100 `hookit-agent` validation response anyone can read.
82
+ - Otherwise it sends `validate` without a request: the wallet is linked (it counts as an agent) but nothing is published. To publish later, the identity's owner sends `validationRequest(validator, agentId, "https://hookit.fun/agents", any new hash)` with its own wallet, then the agent runs the two tools again with `requestHash` set to that hash.
83
+ - Already linked (and published, or nothing to publish): it says so, and sends nothing.
84
+
85
+ The server checks every transaction hookit.fun returns against the pinned validator and the chain (the identity's owner and operators, the request's hash, URI and deadline) and simulates the voucher before sending anything. The validation follows the identity: transferring it clears its operating wallet, and the wallet stops counting. A wallet Hookit revoked, on the pass or on the validator, gets neither a pass nor a validation.
86
+
87
+ ## With Kraken
88
+
89
+ Ink is Kraken's chain: Kraken moves ETH to and from Ink directly. Run the [Kraken CLI](https://github.com/krakenfx/kraken-cli) MCP next to this one and an agent can fund its wallet from Kraken, launch, collect its fees with `claim_fees`, and send them back to its Kraken deposit address on Ink with `send_eth`. Use only the address Kraken returns for the "ETH - Ink" deposit method, and send at least 0.001 ETH: Kraken marks smaller deposits as failed and the funds are lost.
90
+
91
+ ```json
92
+ {
93
+ "mcpServers": {
94
+ "kraken": {
95
+ "command": "kraken",
96
+ "args": ["mcp", "-s", "market,account,funding"],
97
+ "env": { "KRAKEN_API_KEY": "…", "KRAKEN_API_SECRET": "…" }
98
+ },
99
+ "hookit": {
100
+ "command": "npx",
101
+ "args": ["-y", "hookit-mcp"],
102
+ "env": { "HOOKIT_PRIVATE_KEY": "0x…" }
103
+ }
104
+ }
105
+ }
106
+ ```
107
+
108
+ Kraken withdraws only to saved addresses: save the agent's wallet in Kraken on the Ink network first.
109
+
110
+ Without MCP: `GET /api/agents/catalog` and `POST /api/agents/prepare-launch` on hookit.fun, and `GET` / `POST /api/agents/pass` for the Agent Pass (see `/llms.txt`).