Skip to content

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. requestPayment sends 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. pay on an inline keyboard opens Send prefilled. Good for tips and fixed prices.
TypeScript
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' }),
);
Python
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
mintThe token's mint address. For the network's own coin, use NATIVE_MINT in TypeScript or "native" in either SDK.
chainsolana, cookie, fogo, x1, sonicsvm or solayer.
amountA decimal string, like "0.02".
decimalsThe token's decimals: 9 for SOL, 6 for USDC.
symbolShown on the card.
textWhat 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.

TypeScript
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.'));
Python
@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:

TypeScript
const bot = new Bot(token, { rpc: { solana: 'https://your-rpc.example.com' } });
Python
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.

Try one of these