REST API

Base URL

https://api.tonramp.io

Authentication

To use the partner REST API you need an API key in the format tonr_<prefix>_<secret>, created in the partner console.

Console access is via magic link:

1. Send POST /v1/partner/auth/request-link with the registered e-mail.
2. You receive a link by e-mail; opening it makes the session issue a JWT token.
3. With the owner session, create an API key via POST /v1/partner/api-keys. The raw key is shown only once — store it securely. It can be revoked at any time.

Send the API key in authenticated calls in the header:

Authorization: Bearer tonr_<prefix>_<secret>

Caution

The POST /v1/wallet/trp/generate endpoint forces the payload wallet to be the partner’s registered wallet (anti-spoof protection): you cannot generate a payload for a third-party wallet.

Endpoints under /v1/partner/... (such as GET /v1/partner/transactions) use the partner’s session JWT token, also sent as Authorization: Bearer ....

Endpoints

POST /v1/wallet/trp/generate

Generates a TRP payload and returns the links.

Caution

This endpoint requires partner API key authentication in the Authorization: Bearer tonr_... header. See Authentication. The payload wallet is forced to the partner’s registered wallet (anti-spoof protection): you cannot generate a payload for a third-party wallet.

Request:

curl -X POST https://api.tonramp.io/v1/wallet/trp/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tonr_YOUR_API_KEY" \
  -d '{
    "wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
    "merchant": "store123",
    "amount": 100.00,
    "currency": "USDT",
    "tx_id": "tx123456"
  }'

Response (200):

{
  "success": true,
  "payload": "trp010148UQBJ6gU8...",
  "deep_link": "https://trp.tonramp.io/trp/trp01...",
  "telegram_link": "https://t.me/TonRmpBot/tonramp?startapp=trp01...",
}

Parameters:

Field	Type	Required	Description
wallet	string	Yes	Destination TON address (10-48 chars)
merchant	string	Yes	Merchant ID (max 32 chars)
amount	string	Yes	Amount in USDT (e.g., “100.00” = 100.00 USDT)
currency	string	No	Fixed currency: USDT (default). Other values are rejected.
tx_id	string	Yes	Transaction ID (max 64 chars)

---

POST /v1/wallet/trp/parse

Decodes a TRP payload and returns its fields.

Request:

curl -X POST https://api.tonramp.io/v1/wallet/trp/parse \
  -H "Content-Type: application/json" \
  -d '{"payload": "trp010148UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ0208store1230305100000404USDT0508tx12345699045D57"}'

Response (200):

{
  "success": true,
  "data": {
    "wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
    "merchant": "store123",
    "amount": 10000,
    "currency": "USDT",
    "tx_id": "tx123456",
    "crc_valid": true
  }
}

---

POST /v1/wallet/trp/validate

Validates the CRC of a TRP payload.

curl -X POST https://api.tonramp.io/v1/wallet/trp/validate \
  -H "Content-Type: application/json" \
  -d '{"payload": "trp010148UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ0208store1230305100000404USDT0508tx12345699045D57"}'

Response: {"valid": true} or {"valid": false}

---

GET /v1/trp/status/{tx_id}

Checks the status of a TRP transaction.

Caution

This endpoint requires an authentication token in the token query parameter. The token is generated on the checkout page and prevents unauthorized lookups.

Request:

curl "https://api.tonramp.io/v1/trp/status/tx123456?token=abc123def456"

Response (200):

{
  "status": "pending",
  "amount": "10000",
  "currency": "USDT",
  "updated_at": "2025-03-05T12:00:00Z"
}

Response (403): Invalid or missing token.

Response (404):

{
  "detail": "Transaction not found"
}

Possible Statuses:

Status	Description
pending	Awaiting payment
error	Processing failure
paid	Payment received, processing delivery
completed	USDT delivered, transaction completed
expired	Expired without payment

---

POST /v1/trp/preference

Saves the user’s platform preference in a cookie.

Request:

curl -X POST https://api.tonramp.io/v1/trp/preference \
  -H "Content-Type: application/json" \
  -d '{"platform": "telegram"}'

Response (200):

{
  "success": true,
  "platform": "telegram"
}

Accepted platforms: telegram, google (web)

The tonramp_platform cookie is set with SameSite=None to work cross-origin.

---

GET /v1/partner/transactions

Paginated list of the partner’s TRP transactions. Use it for reconciliation.

Caution

Authenticated with the partner’s session JWT token: Authorization: Bearer <token>. See Authentication.

Query params:

Parameter	Description
status	Filter by status (optional)
search	Text search (optional)
limit	Items per page, 1 to 200 (default per server)
offset	Pagination offset

Request:

curl "https://api.tonramp.io/v1/partner/transactions?status=completed&limit=50&offset=0" \
  -H "Authorization: Bearer <token>"

Response (200):

{
  "items": [
    {
      "id": 123,
      "parent_tx_id": "tx123456",
      "partner_id": 7,
      "partner_name": "store123",
      "amount_brl": null,
      "amount_usdt": 100.00,
      "status": "completed",
      "status_label": "completed",
      "paid": true,
      "completed": true,
      "payer_wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
      "unit_price": 1.0,
      "service_fee": 1.0,
      "created_at": "2026-03-26T12:00:00Z",
      "expiration_time": "2026-03-26T12:30:00Z",
      "close_time": "2026-03-26T12:05:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Each item contains the fields: id, parent_tx_id, partner_id, partner_name, amount_brl, amount_usdt, status, status_label, paid, completed, payer_wallet, unit_price, service_fee, created_at, expiration_time, close_time.

Rate Limiting

Endpoint	Limit
POST /v1/wallet/trp/generate	30/minute
POST /v1/wallet/trp/parse	30/minute
POST /v1/wallet/trp/validate	30/minute
GET /v1/trp/status/\{tx_id\}	60/minute
POST /v1/trp/preference	10/minute

Responses exceeding the rate limit return HTTP 429 Too Many Requests.