TgPay Merchant API

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Accept crypto payments via the TgPay Merchant API — invoices, subscriptions, webhooks.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "TgPay Merchant API": {
      "url": "https://app.tgpaycrypto.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (20)

• get_docs read-only

  Read a TgPay Merchant API integration doc. START HERE before integrating: topics quickstart, invoices, subscriptions, transfers-checks, webhooks, errors.

  Parameters:

  • topic (required) — string — quickstart | invoices | subscriptions | transfers-checks | webhooks | errors

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• connect

  Start token issuance WITHOUT the Mini App UI: creates a merchant-app request and returns a t.me approve link plus a poll_secret. Show the link to the human — they approve with one button in the @tgpaycryptobot bot — then call connect_status with the poll_secret. Use only when no API token is configured yet.

  Parameters:

  • app_name (required) — string — Merchant app name shown to the approving human, 1-64 chars (e.g. the project/bot name).

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• connect_status

  Poll a connect request. Returns pending | denied | expired, or — once approved — the app id and the API TOKEN (returned exactly once: save it to the project's .env immediately, never print it in logs). The token is SCOPED (read, invoices, subscriptions, webhooks) — it cannot move money out of the app; transfers/refunds/checks need the primary token the human holds in the Mini App. Poll every 3-5 seconds while pending.

  Parameters:

  • poll_secret (required) — string — The poll_secret from the connect tool.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• getMe read-only

  Verify the token: app id, name, webhook config, token scopes.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getBalance read-only

  Merchant app balance per asset (available + onhold).

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getCurrencies read-only

  Supported crypto assets (code/name/decimals) and fiats.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getExchangeRates read-only

  Current asset↔fiat display rates.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getStats read-only

  App volume/count stats for a period.

  Parameters:

  • end_at — string — ISO 8601 period end.
  • start_at — string — ISO 8601 period start.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getInvoices read-only

  List invoices (newest first).

  Parameters:

  • fiat — string — Filter by fiat code.
  • asset — string — Filter by asset code.
  • count — integer — Page size (default 100).
  • offset — integer — Skip this many.
  • status — string — active | paid | expired.
  • invoice_ids — string — Comma-separated ids.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getChecks read-only

  List checks.

  Parameters:

  • asset — string — Filter by asset code.
  • count — integer — Page size (default 100).
  • offset — integer — Skip this many.
  • status — string — active | activated.
  • check_ids — string — Comma-separated ids.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getTransfers read-only

  List app→user transfers.

  Parameters:

  • asset — string — Filter by asset code.
  • count — integer — Page size (default 100).
  • offset — integer — Skip this many.
  • spend_id — string — Filter by idempotency key.
  • transfer_ids — string — Comma-separated ids.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getSubscriptionPlans read-only

  List subscription plans.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• getSubscriptions read-only

  List subscriptions (subscribers).

  Parameters:

  • status — string — active | grace | cancelled | expired.
  • plan_id — integer — Filter by plan.
  • user_id — integer — Filter by Telegram user id.

  Hints: read-only yes · destructive no · idempotent not declared · open-world not declared

• createInvoice

  Create a one-off payment invoice; the payer opens result.mini_app_invoice_url. See the invoices doc.

  Parameters:

  • fiat — string — Fiat code (fiat mode).
  • asset — string — Asset code (crypto mode).
  • amount — string — Decimal string in MAJOR units, e.g. "5" = 5 USDT. Never a float. Omit for an open-amount invoice.
  • payload — string — Opaque data echoed back in the webhook (≤4096).
  • swap_to — string — Auto-convert the received amount to this asset.
  • expires_in — integer — Invoice TTL in seconds.
  • description — string — Shown to the payer (≤1024).
  • paid_btn_url — string — URL for the paid button.
  • currency_type — string — crypto (default) | fiat.
  • paid_btn_name — string — viewItem | openChannel | openBot | callback.
  • allow_comments — boolean — Default true.
  • hidden_message — string — Revealed to the payer ONLY after payment (≤2048).
  • accepted_assets — string — Fiat mode: comma-separated assets the payer may pay in.
  • allow_anonymous — boolean — Default true.
  • rate_lock_seconds — integer — Fiat mode: freeze crypto quotes for this long.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• deleteInvoice destructive

  Delete an unpaid invoice.

  Parameters:

  • invoice_id (required) — integer — The invoice to delete.

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• deleteCheck destructive

  Delete an unclaimed check (refunds the hold).

  Parameters:

  • check_id (required) — integer — The check to delete.

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• createSubscriptionPlan

  Create an IMMUTABLE recurring-billing plan; send payers to result.mini_app_subscribe_url. See the subscriptions doc.

  Parameters:

  • name (required) — string — Plan name shown to payers (≤64).
  • asset (required) — string — Asset code, e.g. USDT.
  • amount (required) — string — Decimal string in MAJOR units, e.g. "5" = 5 USDT. Never a float. Charged per period.
  • period_days (required) — integer — Billing period in days.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• archiveSubscriptionPlan

  Stop new signups for a plan (live subscriptions keep renewing).

  Parameters:

  • plan_id (required) — integer — The plan to archive.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

• cancelSubscription destructive

  Stop future charges for one subscription (paid time runs out).

  Parameters:

  • subscription_id (required) — integer — The subscription.

  Hints: read-only no · destructive yes · idempotent not declared · open-world not declared

• updateApp

  Update app name / webhook_url (https) / webhook_events opt-in list. Needs the 'webhooks' scope (the connect-issued token has it) or the primary token. See the webhooks doc for the event types and signature verification.

  Parameters:

  • name — string — New app name (1-64).
  • webhook_url — string — https URL for webhook delivery; "" clears it.
  • webhook_events — array — Extended event types to opt into (invoice_paid is always delivered); [] = invoice_paid-only.

  Hints: read-only no · destructive no · idempotent not declared · open-world not declared

Publisher website

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.