Getting started as a developer

Create an app in the Mini App, copy its API token once, and start calling the API. The whole setup lives under More → Merchant API.

Steps

1. Open More → Merchant API.
2. Enter an App name (e.g. “My Store”) and, optionally, a Webhook URL.
3. Tap Create app.
4. Copy the API token immediately. It’s shown once and never again — the app stores only a hash of it.
5. Send your first request with the token in the TgCryptoPay-API-Token header.

Your first call

Point your client at the API base https://crypto.tgpaybot.com/pay/api and call getMe to confirm the token works. getBalance returns your app’s balances, getCurrencies the assets you can use.

Read methods are GET. The methods that move money — createInvoice, transfer, createCheck and their delete counterparts — are POST only, on purpose: amounts and idempotency keys don’t belong in access logs. Parameters may be sent as a JSON body, form-urlencoded, or query params.

Managing an app

Each app card in Merchant API shows its app ID and balance, and lets you:

• Set or change the webhook URL and save it.
• Rotate token — issues a new token and instantly invalidates the old one. Use this if a token leaked; the new one is shown once, same as at creation.
• Delete — the app stops authenticating, but its balance and payment history are preserved. Money never disappears with the app row.

Webhooks

If you set a webhook URL, the app POSTs a signed JSON body to it:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

The signature is in the TgCryptoPay-API-Signature header (with Crypto-Pay-API-Signature as a compat alias): HMAC-SHA256 over the raw body, keyed by the SHA-256 of your API token. Verify it before trusting anything in the payload.

Deliveries are retried with a growing backoff for a long window, and update_id stays the same across retries — key your deduplication on it and make your handler idempotent.

⚠️ Guard the token like a private key

It authorises payouts from your app balance. Keep it on your server, never in a mobile app, front-end bundle or committed config. If you’re unsure whether it leaked, rotate it — rotation is instant and costs nothing.