v1 to v14

+ version: 14

+ POST https://api.hood.markets/api/agent/resolve-deploy-image

+ POST https://api.hood.markets/api/agent/claim-for-recipient (anyone — fees to catalog recipient)

+ POST https://api.hood.markets/api/agent/claim (fee recipient wallet only)

+ See `references/API-HOST.md` before any HTTP call. Security: `references/AUTH-BOUNDARY.md`, `references/PROMPT-INJECTION.md`, `references/RESPONSE-SAFETY.md`.

+ | **Simple launch** | Uniswap V3 via `0xcFE4…9f09` factory — DexScreener-friendly; **5%** platform / **95%** creator |

+ 4. **Deploy:** `preflight-deploy` first — **409 + `blocks[]` only** = do not deploy. **`warnings[]` with `canDeploy: true`** (e.g. 2nd launch in 24h → platform fees) = warn, then deploy after user confirms yes — never invent a wallet cooldown block.

+ 7. Deploy (X): extract `media_url_https` from tweet → `resolve-deploy-image` with `tweetId` + `tweetImageUrl` → `prepare-deploy` → `confirmReplyHint` → deploy after yes. **Never claim no image without calling API with tweetId first.**

+ 9. Claim **own** fees: haiku JWT or X wallet → POST /api/agent/claim

+ 10. Claim **for someone else** (help EA get fees): POST /api/agent/claim-for-recipient with tokenAddress only — no fee-recipient wallet needed

+ 11. **Claim success:** if API returns `ok: true`, post **`replyHint`** verbatim (same as deploy). Fields: `completed: true`, `bankrWalletSubmitRequired: false`. **Never** `/wallet/submit`. **Never** say "I didn't submit a transaction" when `ok: true`. Read `references/CLAIM-BANKR.md`.

+ ## X — token logo (CRITICAL for @bankrbot)

+

+ Bankr receives the **full Tweet object** from X. The logo is in the media fields — extract it **before** calling the API.

+

+ ### Step A — read media from Bankr's X payload (preferred)

+

+ | X API | Where the image lives |

+ |-------|----------------------|

+ | **v1.1** | `tweet.extended_entities.media[0].media_url_https` |

+ | **v2** | `includes.media[0].url` (request `expansions=attachments.media_keys&media.fields=url`) |

+ | **Syndication shape** | `tweet.photos[0].url` or `tweet.mediaDetails[0].media_url_https` |

+

+ Pass to the API as **`tweetImageUrl`** or the full **`tweet`** object.

+

+ ### Step B — always pass tweet id / URL

+

+ Every launch tweet has an id. Pass **`tweetId`** (numeric string) or **`tweetUrl`**:

+

+ ```json

+ {

+ "wallet": "0x…",

+ "name": "dontfukinbuy",

+ "symbol": "TEST",

+ "agentChannel": "x",

+ "tweetId": "1990000000000000000",

+ "tweetUrl": "https://x.com/Rayblancoeth/status/1990000000000000000",

+ "tweetImageUrl": "https://pbs.twimg.com/media/….jpg",

+ "tweet": { "extended_entities": { "media": [{ "type": "photo", "media_url_https": "https://pbs.twimg.com/…" }] } }

+ }

+ ```

+

+ API resolves via **syndication** (`cdn.syndication.twimg.com`) when only `tweetId` / `tweetUrl` is passed — no Selenium needed.

+

+ ### Step C — call API before saying "no image"

+

+ 1. `POST /api/agent/resolve-deploy-image` with fields above

+ 2. If `ok: true` → use `imageUrl` in `prepare-deploy`

+ 3. **Only** ask the user for a logo if API returns `imageRequired: true` **after** `tweetId` + `tweetImageUrl` / `tweet` were sent

+

+ **Never** tell the user "no attached image" without passing `tweetId` and `tweetImageUrl` (from `media_url_https`) to the API first.

+

+ ---

+

+ | launch / deploy token | `GET preflight-deploy` → if ok, `POST prepare-deploy` with `agentChannel: "x"` on X, else haiku flow |

+ ### X daily limit (1 launch / day on @bankrbot)

+

+ Each Bankr wallet gets **1 subsidized launch per Eastern calendar day** on X (`agentChannel: "x"`). A second attempt the same day returns **409** with:

+

+ - `replyHint` — short copy for the tweet reply (use as-is)

+ - `xDailyLimit.todayToken` — name, symbol, address, `tokenPageUrl` of today's launch

+ - `xDailyLimit.resetsAtEastern` — when the X limit resets (midnight Eastern)

+

+ **Do not retry deploy on X after 409.** Tell the user they already launched today, link `todayToken.tokenPageUrl`, and send them to **https://hood.markets** to launch more (sign in + wallet pays gas).

+

+ ### On X / Twitter (`agentChannel: "x"`)

+

+ 1. Pass **`tweetUrl`** (full status URL of the launch tweet) — API pulls the attached photo via oEmbed even when Bankr cannot see media in context.

+ 2. Pass **`xUsername`** (the X @handle of the user who asked to launch — without `@`) so the token page shows who requested it and their launch count. If omitted, API infers from `tweetUrl`.

+ 3. Optionally also pass `tweetImageUrl`, `tweet`, `tweetMedia`, or `imageUrl` if available in Bankr's payload.

+ 4. Call `POST /api/agent/prepare-deploy` with `agentChannel: "x"`, wallet, name, symbol, and fields above.

+ 5. Wait for user **yes/confirm**, then deploy — **no haiku**. Use the **`steps[].body`** from `prepare-deploy` as-is (includes **`xUsername`**, **`tweetUrl`** / **`sourceUrl`** so the token page shows the requester and launch tweet):

+

+ ```http

+ POST https://api.hood.markets/api/deploy

+ x-wallet-address: 0x…

+ x-agent-channel: x

+ Content-Type: application/json

+

+ {

+ "name": "My Token",

+ "symbol": "MTK",

+ "feeTarget": "agent_wallet",

+ "clientKind": "agent",

+ "agentProvider": "bankr",

+ "agentChannel": "x",

+ "launchMode": "simple",

+ "imageUrl": "https://…",

+ "xUsername": "user",

+ "tweetUrl": "https://x.com/user/status/…",

+ "sourceUrl": "https://x.com/user/status/…",

+ "wallet": "0x…"

+ }

+ ```

+

+ ### Non-X agents (API, cron, cloud — automatable)

+

+ Use **haiku JWT** — no in-thread confirm step:

+

+ - **409** + `blocks[]` → do not deploy; reply with `blocks[0].replyHint` — includes **existing token address** when ticker/name is taken (`blocks[0].existingToken`)

+ - **200** + `canDeploy: true` + `warnings[]` → **deploy is allowed**. If `rate_limit_would_force_platform_fee`: user already launched in the last 24h — fees on **this** token go to the hood.markets platform (same as the website). Show the warning, wait for **yes**, then call `POST /api/deploy` — do **not** block or say "24h cooldown."

+ - After deploy: post **`deployReplyHint`** from `/api/deploy` — no DexScreener/simple-mode footer

+ Two paths — pick based on who is asking:

+

+ ### A) Help someone else / claim for a token (any X user)

+

+ When the user gives a **token contract** and wants fees sent to the **catalog fee recipient** (e.g. "claim fees for EA's $HR"), use:

+

+ POST https://api.hood.markets/api/agent/claim-for-recipient

+ Content-Type: application/json

+

+ { "tokenAddress": "0x78594eD700e343846B4d0Bbba79Ee0cb50Deaa8D" }

+ ```

+

+ **No JWT. No Bankr `/wallet/submit`.** hood.markets server broadcasts and pays gas.

+

+ Response: `ok`, `replyHint` (**post this** — same text as `claimReplyHint`), `completed`, `bankrWalletSubmitRequired: false`, `transactionHash`, `feeRecipientAddress`, `tokenName`, `tokenSymbol`, `tokenPageUrl`.

+

+ If `ok: true`, the claim succeeded — post `replyHint`. Do not check Bankr wallet submit.

+

+ ### B) Fee recipient claims their own tokens

+

+ ```

+ X-Agent-Captcha-JWT: <jwt> (or X channel + x-wallet-address = fee recipient)

+ **Default launches are Simple (V3).** Same endpoint auto-routes V3 `claimRewards` vs V4 locker.

+ | Launch | On-chain |

+ |--------|----------|

+ | **Simple (V3)** | `HoodMarketsV3.claimRewards(token)` → 95% fee wallet |

+ | **Pro (V4)** | Collect pool → claim WETH from locker |

+

+ Response includes `feeRecipientAddress`, `txHash`, `explorerUrl`, `feeModel` / `launchType`.

+

+ → prepare-deploy (`agentChannel: "x"` on X: confirm first, no haiku; else haiku) → deploy → reply with `https://hood.markets/?token=0x…`

+ > claim fees for 0x7859… / help EA claim $HR hood fees

+

+ → POST /api/agent/claim-for-recipient `{ "tokenAddress": "0x…" }` — if `ok: true`, reply with **`replyHint`** only

+

+ → captcha JWT or X wallet → POST /api/agent/claim — if `ok: true`, reply with **`replyHint`**

+ | `references/CLAIM-BANKR.md` | Claim success without Bankr wallet submit |