# Buy bot setup

The buy bot posts a message in a Telegram group every time someone buys the token it is configured for. It is configured either entirely inside Telegram or from the dashboard.

## Overview

> **Beta**
>
> The buy bot is currently in beta, served from the dashboard's beta tab.

#### Who may operate it

| Setting | Value |
| --- | --- |
| Allowed | The bot's Memescale owner, or a Memescale platform admin. |
| Telegram group admins | Never included. Admin status in the group grants no access to any buy bot command, button or prompt. |
| A non-owner sends a command | Ignored — no reply. |
| A non-owner taps a button | Alert popup: "Owner / admins only". |
| Someone else messages while a prompt is open | Left alone — it neither answers nor cancels the prompt. |

Every write — a Telegram command, a button, or a dashboard save — goes through the same server-side config sanitizer (`services/buyBot.ts`), so the two surfaces always agree.

> **Setting it up is turning it on**
>
> The config's `enabled` field is set to `true` automatically on any save where the config comes out set up — a contract address and at least one target group both present — and was not set up immediately before that save. Every write from every surface passes through the same check in `sanitizeBuyBotConfig`, so the state saved a moment earlier is what the check compares against: a config that loses its last group and later gains one back is set up again, and turns on again. While the config stays set up, the explicit control (the settings-card switch, `/enablebuybot`, Lock It In, or the dashboard's own toggle state) governs it. Saving with only one of the two pieces present never turns the bot on by itself.

## In Telegram

The shortest path starts in the group the buys are to post in.

#### Group path

1. Add the bot to the group and promote it to admin. If it isn't admin yet, it replies `Promote me to admin first, then send /enablebuybot again.`
2. Send `/enablebuybot` in the group. This silently authorizes the group and adds it to the buy bot's target list (up to 10 groups).
3. If no contract address is set yet, the bot replies `Send the contract address right here and I'll enable it.`
4. Paste the contract address in that same group. Only a message that is an address counts — anything else is left alone and the prompt keeps waiting.
5. If the address is an EVM address DexScreener has no listing for, the bot asks `Which chain is this token on?` with one button per EVM chain.
6. The bot replies `Done ✅ — $SYM buys post here.` followed by `Send /buybotsettings if you'd like to customize the layout, emojis, or media.` The group is now live.

> **Note**
>
> If a contract address is already set, step 2 finishes immediately with `Buy bot enabled ✅ — buys post here.` and steps 3–6 are skipped. If the group is already a target and the bot is already fully on, nothing is written and the bot replies `Buy bot is already enabled for $SYM here — still running, nothing changed.`

> **Limit**
>
> A group can't be added past the 10-group cap: `Limit reached, we're already in 10 groups. Remove a group first and then send the /enablebuybot again to enable the buy bot.`

#### Starting in a DM

1. Send `/enablebuybot` in a DM with no contract address set. The bot replies `Send the token's contract address and I'll set it up.`
2. Paste the address. The bot looks it up on DexScreener and shows a card: `Found $SYM — <name>` (or `I couldn't find that token on DexScreener yet — it may be very new.`), the chain, the address, and `Lock it in?`, with **Confirm ✅** / **Cancel** buttons.
3. Tap **Confirm ✅**. The bot writes the contract address and chain. When DexScreener's listing has a link the layout can use, the socials card opens next (see Commands and the settings card); otherwise each needed link is asked one by one, or the flow finishes straight away.
4. With a token set but no group yet, the bot replies `No group yet — Send /enablebuybot inside any group I'm an admin in and I'll begin sending alerts right away.`
5. Go to the group, promote the bot to admin, and send `/enablebuybot`.

#### Forking a layout first

1. Send `/forkbuybot`. A never-styled bot gets `Gotchu. Paste a buy bot post right here by forwarding it or pasting it in. Also, I can create a premium coin emoji for you, just send /newpack if you need one for the buybot.` A bot that already has a custom layout gets a warning instead: `Bet. Let's fork a new buy bot. This will overwrite the existing styling for $SYM. Forward a message from the bot where it announces a buy, and we'll configure it ASAP.`
2. Paste or forward the other bot's buy post — image, GIF or video included. This writes only the body text, size emoji and media. **The buy bot is not enabled and no groups are added.**
3. The post-fork wizard opens on the same card: links, then media and emoji, then locked in — see Commands and the settings card. The pasted message is deleted once the wizard card is up.
4. The wizard asks for the contract address first, because the DexScreener lookup that names the token is also where the profile links come from.
5. Tapping **Lock It In** turns the bot on only if a group is already wired. Without one, the final card tells the owner to send `/enablebuybot` in the group.

> **Limit**
>
> A private Telegram invite link (`t.me/+…`, `joinchat`, `tg://join`) can never be resolved by a bot — Telegram's `messages.checkChatInvite` answers `BOT_METHOD_INVALID` for bot accounts. To add a group you can't run the command inside directly, send `/getid` in that group and paste the numeric ID instead.

## In the dashboard

The buy bot is only available for Telegram bots — a non-Telegram bot's setup request is refused with `The buy bot is only available for Telegram bots`.

#### Dashboard path

1. Open the Buy Bot tab. As the bot owner: dashboard → beta tab → Buy Bot. As a platform admin: search for the bot.
2. Tap **Set up** — the only control shown before the buy bot has a config. This writes the default config with `enabled` set to `false`.
3. Pick the chain. Until a chain is picked, the editor is replaced by `Which chain is the token on?` with one button per supported chain; **Cancel** closes the tab.
4. In Settings, set **Currently enabled in** to a group. Picking a group Telegram hasn't authorized yet (labelled "unauthorized — picking authorizes it") authorizes it first.
5. Enter the **Contract address**.
6. Optional: Layout settings, Emoji settings, media, buttons, body edits.
7. Tap **Save & push**.

> **Warning**
>
> The dashboard's group picker writes exactly one group — picking a new one replaces whatever was selected before. The config can hold up to 10 targets, but the dashboard never writes more than the single group currently selected. Reaching more than one group requires the Telegram side: `/enablebuybot` in each additional group, or Manage Groups.

There is no separate confirmation step for the auto-enable described in Overview, and no client-side check stopping a save with an empty contract address or no group — the bot stays off until both are present.

* [Commands and the settings card](#buybot-commands)