Payments to bots
Ask people to pay your bot, get a payment event only after the SDK has checked the transaction on chain, and where the money goes.
People pay your bot from their own wallet, in the chat. Your bot never takes money: it asks, and the person reviews and confirms the payment in Send, like any other.
The money lands on your bot's address. That address is a wallet on every network Morsel supports, and the bot's token is its key.
Ask for a payment
There are two ways to ask:
- A payment request.
requestPaymentsends a payment card with a Pay button. The payment is tied to that request, and the SDK checks the token and the amount against it. - A pay button.
payon an inline keyboard opens Send prefilled. Good for tips and fixed prices.
import { Bot, NATIVE_MINT } from '@morsel/bot';
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
bot.command('pro', (ctx) =>
ctx.requestPayment({ mint: USDC, chain: 'solana', amount: '5', decimals: 6, symbol: 'USDC', text: 'Pro alerts, 30 days' }),
);
bot.command('coffee', (ctx) =>
ctx.requestPayment({ mint: NATIVE_MINT, chain: 'solana', amount: '0.02', decimals: 9, symbol: 'SOL', text: 'One coffee' }),
);USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
@bot.command("pro")
async def pro(ctx: Context) -> None:
await ctx.request_payment(mint=USDC, chain="solana", amount="5", decimals=6, symbol="USDC", text="Pro alerts, 30 days")
@bot.command("coffee")
async def coffee(ctx: Context) -> None:
await ctx.request_payment(mint="native", chain="solana", amount="0.02", decimals=9, symbol="SOL", text="One coffee")| Field | |
|---|---|
mint | The token's mint address. For the network's own coin, use NATIVE_MINT in TypeScript or "native" in either SDK. |
chain | solana, cookie, fogo, x1, sonicsvm or solayer. |
amount | A decimal string, like "0.02". |
decimals | The token's decimals: 9 for SOL, 6 for USDC. |
symbol | Shown on the card. |
text | What it's for, shown on the card. |
In a group, the request names the member who wrote the command.
Get paid
When a person's payment arrives in the chat, the SDK checks it on chain first. Only then does your bot get payment. If the check fails, it gets payment_failed.
bot.on('payment', async (ctx) => {
const p = ctx.payment!; // { sig, chain, mint, amount, base, decimals, request?, received, check }
await db.recordPayment(p.sig, ctx.from!, p.mint, p.base); // before you deliver anything
await ctx.reply(p.request ? `Paid ${p.amount} ${p.request.symbol}. Thank you!` : `Thanks for the ${p.amount} tip!`);
});
bot.on('payment_failed', (ctx) => ctx.reply(`I could not confirm that payment (${ctx.payment!.check.reason}).`));
bot.on('decline', (ctx) => ctx.reply('No problem.'));@bot.on("payment")
async def paid(ctx: Context) -> None:
p = ctx.payment # VerifiedPayment: sig, chain, mint, amount (Decimal), amount_base, payer, for_request
assert p is not None
await db.record_payment(p.sig, ctx.from_, p.mint, p.amount_base) # before you deliver anything
await ctx.reply(f"Received {p.amount}. Thank you!")
@bot.on("payment_failed")
async def failed(ctx: Context) -> None:
assert ctx.payment_error is not None
await ctx.reply(f"I could not confirm that payment ({ctx.payment_error.code}).")db stands for your own database.
What the SDK checks
Before payment, the SDK fetches the transaction from the network's RPC and checks that:
- it is finalized and succeeded;
- the person who sent the message signed it;
- your bot's address gained the token;
- when it answers one of your requests, it's that request's token and at least its amount.
The SDK waits for the transaction to finalize, up to 90 seconds by default (paymentTimeoutMs in TypeScript). A signature counts once: in TypeScript the store keeps track of it, and in Python once per process. Record sig in your own database too, and never deliver twice for one signature.
Reasons a check fails include NOT_FOUND (not finalized in time), FAILED, TOO_LITTLE, a wrong token, and RPC (the RPC didn't answer).
RPC endpoints
By default, the SDKs use the public RPCs the app uses, for every network. For anything busy, use your own:
const bot = new Bot(token, { rpc: { solana: 'https://your-rpc.example.com' } });bot = Bot(token, rpc={"solana": "https://your-rpc.example.com"})Where the money goes
Payments land on the bot's address. It's a hot wallet: its key sits on your server.
- Keep its balance low.
- Move funds out regularly with Withdraw, which sends them to the wallet that owns the bot.
- If the token leaks, whoever has it can move what's there. See Bot security.