# TgPay Merchant API

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

- name: com.tgpaybot/merchant-api
- version: 1.0.2
- connection class: R0 (autonomous)
- trust: 79/100 flags: no-repository
- quality: 82/100 (good)
- owner: not claimed
- descriptor: https://api.protogrid.dev/v1/servers/com.tgpaybot%2Fmerchant-api
- tools: https://api.protogrid.dev/v1/servers/com.tgpaybot%2Fmerchant-api/tools

**An agent can connect right now, no human step.** Remote endpoint, no authentication, reachable on the last probe.

## Connection (mcpServers)

```json
{
  "mcpServers": {
    "merchant-api": {
      "type": "http",
      "url": "https://app.tgpaycrypto.com/mcp",
      "headers": {
        "TgPayCrypto-API-Token": "${TGPAYCRYPTO_API_TOKEN}"
      }
    }
  }
}
```

Placeholders to fill: `${TGPAYCRYPTO_API_TOKEN}`.

## Trust

- hygiene: 80
- liveness: 99
- freshness: 85
- provenance: 55
- drivers: +dns-namespace +website +reachable +uptime-97% ~updated-43d-ago -no-repository
- Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed.

## Quality 82/100 (good)

### protocol: 75 (weight 25)

- warn `protocol.modern`: newest supported version is 2025-06-18; 2026-07-28 not supported, older versions are deprecated until 2027-07-28
- n/a `protocol.stateless`: only applies to 2026-07-28 servers
- pass `protocol.transport`: streamable HTTP
- n/a `protocol.list_ttl`: only applies to 2026-07-28 servers

### authorization: n/a (weight 15)

- n/a `auth.prm`, `auth.as_metadata`, `auth.cimd`: no remote uses OAuth
- n/a `auth.secret_in_url`: no templated URL

### tool hygiene: 79 (weight 30)

- warn `tools.descriptions`: 1 of 20 tools have a description under 20 characters
- pass `tools.description_length`: descriptions are concise
- pass `tools.schemas`: every tool has an object input schema
- pass `tools.annotations`: 20 of 20 tools declare readOnlyHint or destructiveHint
- fail `tools.directory_hints`: no tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: getInvoices (idempotentHint, openWorldHint); deleteInvoice (idempotentHint, openWorldHint); connect (idempotentHint, openWorldHint); …
- pass `tools.token_cost`: about 1,977 tokens to load every tool
- pass `tools.api_dump`: tools are not a one-to-one API dump

### stability: 100 (weight 15)

- pass `stability.changes`: no tool changes in 30 days
- pass `stability.rug_pull`: no tool changed its meaning under the same name

### dependencies: n/a (weight 15)

- n/a `deps.known_vulns`, `deps.mcp_sdk_version`, `deps.resolvable`: no npm or PyPI package

- tools: 20, about 1,977 tokens to load them all
- tool set hash: edcf9e664ece213436a2a97f9abe3190
- badge: [![protogrid quality](https://protogrid.dev/badge/com.tgpaybot/merchant-api.svg)](https://protogrid.dev/servers/com.tgpaybot/merchant-api)
- Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed.

### Tool changes

_No tool definition changes recorded._

## Remotes

- https://app.tgpaycrypto.com/mcp (streamable-http, auth none, reachable true, uptime30d 0.96581197)

## Packages

_none_

## Tools (20)

- `archiveSubscriptionPlan`: Stop new signups for a plan (live subscriptions keep renewing).
- `cancelSubscription`: Stop future charges for one subscription (paid time runs out).
- `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.
- `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.
- `createInvoice`: Create a one-off payment invoice; the payer opens result.mini_app_invoice_url. See the invoices doc.
- `createSubscriptionPlan`: Create an IMMUTABLE recurring-billing plan; send payers to result.mini_app_subscribe_url. See the subscriptions doc.
- `deleteCheck`: Delete an unclaimed check (refunds the hold).
- `deleteInvoice`: Delete an unpaid invoice.
- `getBalance`: Merchant app balance per asset (available + onhold).
- `getChecks`: List checks.
- `getCurrencies`: Supported crypto assets (code/name/decimals) and fiats.
- `get_docs`: Read a TgPay Merchant API integration doc. START HERE before integrating: topics quickstart, invoices, subscriptions, transfers-checks, webhooks, errors.
- `getExchangeRates`: Current asset↔fiat display rates.
- `getInvoices`: List invoices (newest first).
- `getMe`: Verify the token: app id, name, webhook config, token scopes.
- `getStats`: App volume/count stats for a period.
- `getSubscriptionPlans`: List subscription plans.
- `getSubscriptions`: List subscriptions (subscribers).
- `getTransfers`: List app→user transfers.
- `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.