TRON · 19 Confirmations

USDT TRC20 Payment Solution

USDT TRC20 API by GammaPay lets you accept Tether on TRON. Use coin_symbol USDTTRC20 — never USDTERC20. Addresses start with T. Network fees are paid in TRX.

Network: TRON19 Confirmations6 DecimalsPremium PlanCredits in ~57sMin Invoice: 10 USDTTRC20

Production Base URL

https://api.gammapay.io

SDK & Libraries

Official wrappers for Node.js, Python, and PHP coming soon.

Quick Start

Create a payment invoice in under 2 minutes. You'll need an active API Key and Secret from your wallet settings.

Create a Wallet & Get Credentials

To use the GammaPay API, you must first create a wallet and generate API keys in your dashboard.

Log in to dashboard.gammapay.io.
Navigate to Wallets → New Wallet in the sidebar.
Select the network and coin. For TRON use USDTTRC20 or TRX (Nile: USDTTRC20_NIL / TRX_NILE) and click Create.
Click on your new wallet, then go to the API Keys tab.
Here you will find your X-API-Key and your api_secret.

CRITICAL: Your api_secret is only shown once. Copy it and store it securely.

Generate HMAC Signature

Sign the exact request bytes: timestamp + "." + rawBody. If you send X-Idempotency-Key (required for withdrawals), append + "." + idempotencyKey. GET requests use an empty body, so the payload is timestamp + ".".

Selected coin for examples: USDTTRC20 on TRON. Pick a coin in the right sidebar to rewrite every sample body.

Python — create invoice (HMAC)

import hmac, hashlib, time, json
api_key    = "wk_live_xyz1234342342342343"
api_secret = "sec_dummy_xyz1234342342342343"

url        = "https://api.gammapay.io/v1/invoices"
body_data  = {
  "coin": "USDTTRC20",
  "amount": "10",
  "expire_time": 60,
  "title": "USDT TRC20 Invoice",
  "notify_url": "https://api.yourdomain.com/webhook",
  "custom_data": {
    "orderId": "ord_1001",
    "userId": 1
  }
}

timestamp  = str(int(time.time()))
# Sign the EXACT bytes you send. Compact separators must match the request body.
body_json  = json.dumps(body_data, separators=(',', ':'))

payload = f"{timestamp}.{body_json}"
signature  = hmac.new(
    api_secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

print(f"X-API-Key: {api_key}")
print(f"X-Signature: sha256={signature}")
print(f"X-Timestamp: {timestamp}")

Python — GET (empty body)

import hmac, hashlib, time

api_secret = "sec_dummy_xyz1234342342342343"
timestamp  = str(int(time.time()))
# GET / DELETE: the signed body is an empty string
payload = f"{timestamp}."
signature = hmac.new(
    api_secret.encode(),
    payload.encode(),
    hashlib.sha256
).hexdigest()

Postman Pre-request Script

var timestamp = Math.floor(Date.now() / 1000).toString();
pm.environment.set("timestamp", timestamp);

var apiSecret = pm.environment.get("api_secret");
var rawBody = (pm.request.body && pm.request.body.raw) ? pm.request.body.raw : "";

// payload = timestamp + "." + rawBody [+ "." + idempotencyKey]
var payload = timestamp + "." + rawBody;
var idemHeader = pm.request.headers.get("X-Idempotency-Key");
if (idemHeader) {
  var idempotencyKey = pm.variables.replaceIn(idemHeader);
  pm.environment.set("resolved_idempotency_key", idempotencyKey);
  payload += "." + idempotencyKey;
}

var signature = CryptoJS.HmacSHA256(payload, apiSecret).toString(CryptoJS.enc.Hex);
pm.environment.set("hmac_signature", "sha256=" + signature);

Make Your First Request

Create an invoice. The HMAC API key is already bound to one wallet, so wallet_id is not needed. The coin body field must match that wallet's coin — currently USDTTRC20. amount in the sample is 10 USDTTRC20 (native units; no currency field).

Terminal / Shell

curl -X POST 'https://api.gammapay.io/v1/invoices' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"coin":"USDTTRC20","amount":"10","expire_time":60,"title":"USDT TRC20 Invoice","notify_url":"https://api.yourdomain.com/webhook","custom_data":{"orderId":"ord_1001","userId":1}}'

Listen to Webhook

When payment is detected, GammaPay sends a POST to your webhook URL.

Express.js

app.post('/webhook/gammapay', express.raw({ type: 'application/json' }), (req, res) => {
  const sig    = req.headers['x-neonpay-signature'];
  const ts     = req.headers['x-neonpay-timestamp'];
  const secret = process.env.WEBHOOK_SECRET;

  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}.${req.body}`).digest('hex');

  if (sig !== `sha256=${expected}`) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  if (event.event === 'transaction.confirmed') {
    // Fulfill order
  }
  res.sendStatus(200);
});

Response Format Notice (v1.0)

Every HMAC response uses { flag, msg, data }. Unknown JSON fields are rejected (deny_unknown_fields). Amounts are decimal strings, never floats.

flag === 1 is success. flag === 0 is an error; also check the HTTP status (400 / 401 / 403 / 404 / 429 / 500).

Authentication & Headers

GammaPay uses HMAC signature verification for all API endpoints.

Where to get your keys: Dashboard → Wallets → select wallet → API Keys tab.
What to send: Every API request must include the three HTTP headers below.

Important: Getting Your First API Key
Because API credentials are tied to individual wallets, you cannot use the API to create your very first wallet. You must log into the GammaPay Dashboard UI and create your first wallet manually. Once created, you can reveal its API Key and Secret in the Dashboard, and use those credentials to authenticate HMAC requests (including creating additional wallets programmatically).

Header	Required	Description
X-API-Key	Yes	Your public API key. Starts with `wk_live_` (mainnet) or `wk_test_` (testnet). Never `npk_`.
X-Timestamp	Yes	Unix timestamp in seconds. Rejected if skew > 300s.
X-Signature	Yes	HMAC-SHA256 signature prefixed with `sha256=`.
X-Idempotency-Key	Conditional	Required for withdrawals. UUID to prevent duplicate operations (24h TTL).

Rate Limits

Rate limits are applied per API key.

Plan	Requests/min	Burst (10s)
Free	300	50
Premium	1000	170

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1745223660
Retry-After: 13 // Only present on 429 Error

Error Codes

Code	HTTP	Retriable	Description
VALIDATION_ERROR	400	No	Missing or invalid fields.
INVALID_CREDENTIALS	401	No	API key missing, invalid, or inactive.
INVALID_SIGNATURE	401	No	HMAC signature mismatch.
NONCE_EXPIRED	401	No	Timestamp older than 5 minutes.
FORBIDDEN	403	No	API key lacks required scope.
NOT_FOUND	404	No	Resource not found.
IDEMPOTENCY_CONFLICT	409	No	Same key with different payload.
INSUFFICIENT_AMOUNT	400	No	Amount below minimum.
INVOICE_EXPIRED	410	No	Invoice past expiry.
WALLET_LOCKED	423	Yes	Wallet temporarily locked.
RATE_LIMIT_EXCEEDED	429	Yes	Retry with backoff.
SERVER_ERROR	500	Yes	Internal server error.

API Coin Symbols

Every HMAC call that mentions a coin must use the exact symbol from this table. Do not send display names like "USDT TRON" or "Tron TRX". Select a live coin on the right to rewrite the sample bodies below.

Current example coin: USDTTRC20 — USDT TRC20 on TRON (mainnet). Create-wallet body field: coin_symbol: "USDTTRC20"

Public list (no HMAC): GET https://api.gammapay.io/v1/supported-currencies

Display	Write this in the API	Network	Deposit Confirms	Withdraw Confirms	Decimals	Min Invoice	Min Withdrawal	Status
Bitcoin	BTC	Bitcoin	3(~30 min)	3(~30 min)	8	1.00	—	LIVE
Bitcoin Signet	BTC_SIGNET	Bitcoin Signet · testnet	3(~30 min)	3(~30 min)	8	1.00	—	TESTNET
Ethereum	ETH	Ethereum	12(~2.4m)	12(~2.4m)	18	1.00	—	LIVE
USDT TRC20	USDTTRC20	TRON	19(~57s)	19(~57s)	6	10	—	LIVE
Tron	TRX	TRON	19(~57s)	19(~57s)	6	10	—	LIVE
Tron Nile	TRX_NILE	TRON Nile · testnet	19(~57s)	19(~57s)	6	1	—	TESTNET
USDT TRC20 Nile	USDTTRC20_NIL	TRON Nile · testnet	19(~57s)	19(~57s)	6	1	—	TESTNET
USDT ERC20	USDTERC20	Ethereum	12(~2.4m)	12(~2.4m)	6	1.00	—	LIVE
USDC ERC20	USDCERC20	Ethereum	12(~2.4m)	12(~2.4m)	6	1.00	—	LIVE

Coming soon (not accepted by HMAC): LTC, DOGE, DASH, BCH, ZANO, BNB.

Where to Put the Coin

The API key is bound to one wallet / one coin. Path {coin} and body coin / coin_symbol must match that wallet. For the selected coin, write USDTTRC20.

Operation	Method / path	Where the coin goes	Required body
Create wallet	POST /v1/wallets	Body `coin_symbol`	coin_symbol, name, withdrawal_type
List wallets	GET /v1/wallets	Optional query `coin_symbol`	Empty body
Create address	POST /v1/USDTTRC20/addresses	Path	label
Validate address	POST /v1/USDTTRC20/addresses/validate	Path	address
Create invoice	POST /v1/invoices	Body `coin`	coin, amount (coin units unless currency is fiat)
Get / list invoices	GET /v1/USDTTRC20/invoices	Path	Empty body
Create / estimate withdrawal	POST /v1/withdrawals	Implicit — wallet of the API key (do not send coin)	destination_address, amount
Whitelist payout address	POST /v1/wallets/{wallet_id}/whitelist	Implicit — wallet of the API key	address, label, totp_code

Create wallet body for this coin

{
  "coin_symbol": "USDTTRC20",
  "name": "USDT TRC20 HMAC Wallet",
  "withdrawal_type": "automatic",
  "is_testnet": false,
  "webhook_url": "https://api.yourdomain.com/webhooks",
  "webhook_confirmation": 19,
  "api_withdraw_enabled": true,
  "transaction_speed": "medium"
}

TRON (TRX & USDT TRC20)

TRON is live on HMAC. Treat native TRX and USDT TRC20 as two different assets — two wallets, two API keys, two invoice coins.

Asset	coin_symbol / coin	Network	Notes
USDT on TRON	USDTTRC20	TRON mainnet	TRC-20 token. Contract `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`
Native TRON	TRX	TRON mainnet	6 decimals (sun). Not a token.
USDT Nile	USDTTRC20_NIL	TRON Nile testnet	Testnet contract `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`
TRX Nile	TRX_NILE	TRON Nile testnet	Sandbox native TRX.

Addresses are Base58 and start with T. Never send to an 0x Ethereum address.
USDTTRC20 ≠ USDTERC20. Wrong network = permanent loss.
TRX ≠ USDTTRC20. A TRX invoice will not detect USDT deposits (and vice versa).
Default confirmations for TRON mainnet: 19 (~57s), Nile testnet: 19 (~57s). BIP44 coin type 195.
TRC-20 transfers burn energy/bandwidth paid in TRX. GammaPay covers network resources on withdrawals; you still withdraw USDT from a USDTTRC20 wallet, not from a TRX wallet.
Invoice payment URI for TRON is the plain T-address(no tron: scheme).
Nile faucet: nileex.io

USDT TRC20 — create wallet

{
  "coin_symbol": "USDTTRC20",
  "name": "USDT TRC20 HMAC Wallet",
  "withdrawal_type": "automatic",
  "is_testnet": false,
  "webhook_confirmation": 19,
  "api_withdraw_enabled": true
}

Native TRX — create wallet

{
  "coin_symbol": "TRX",
  "name": "TRX HMAC Wallet",
  "withdrawal_type": "automatic",
  "is_testnet": false,
  "webhook_confirmation": 19,
  "api_withdraw_enabled": true
}

USDT Nile — create wallet

{
  "coin_symbol": "USDTTRC20_NIL",
  "name": "USDT TRC20 Nile HMAC Wallet",
  "withdrawal_type": "automatic",
  "is_testnet": true,
  "webhook_confirmation": 19,
  "api_withdraw_enabled": true
}

TRX Nile — create wallet

{
  "coin_symbol": "TRX_NILE",
  "name": "TRX Nile HMAC Wallet",
  "withdrawal_type": "automatic",
  "is_testnet": true,
  "webhook_confirmation": 19,
  "api_withdraw_enabled": true
}

⚠️ CRITICAL: is_testnet must match the symbol. USDTTRC20 + is_testnet: true is rejected. Use USDTTRC20_NIL / TRX_NILE with is_testnet: true for Nile.

Wallets

A wallet is the fundamental unit in GammaPay. Each wallet is associated with a single coin/network and provides isolated API credentials, deposit addresses, webhook configuration, whitelist rules, and transaction history.

API Credentials

Each wallet has its own API key + secret pair, isolated from other wallets.

HD Addresses

One deposit address per invoice, never reused.

Whitelist

Withdrawals only go to verified, email-confirmed addresses.

Wallet Tabs (Dashboard)

When you open a wallet, the detail page shows the wallet name, total balance, coin symbol, and 8 tabs for managing every aspect of that wallet:

Tab	Purpose
Transaction	View all incoming deposits and outgoing withdrawals with search, status/direction filters, list/grid views, and detail side-panel.
Addresses	Generate new HD-derived deposit addresses with a mandatory label (3–50 chars, must include a letter or number). QR codes auto-generated. Copy address, view HD index, list/grid toggle.
Whitelist	Manage withdrawal address whitelist. Add (requires 2FA + email verification), remove, verify pending addresses, copy, view status.
Credential	Reveal API key + secret (password + 2FA required), rotate keys, toggle API withdraw permission, update wallet password.
Webhook	Set/update webhook URL, test connection, reveal/rotate webhook secret, remove webhook, view full delivery log with retry status.
Deposit / Withdraw	Quick deposit (QR code + address copy), withdraw to whitelisted addresses (requires 2FA), fee estimation, speed selection, recent withdrawal history.
API Logs	Full audit trail of every API call: HTTP status, method + endpoint, source IP, response duration (ms), timestamp.
Chart	Visual analytics with balance over time (area chart), daily inbound/outbound volume (bar chart), 7d/30d/90d range selector.

Creating a Wallet

The wallet creation wizard walks you through a 3-step process:

1 Wallet Basics

Select Currency: Use the exact API symbol. For this page: USDTTRC20 (USDT TRC20). TRON: USDTTRC20 or TRX (Nile: USDTTRC20_NIL / TRX_NILE).
Wallet Name: A human-readable label
Password: Used to encrypt wallet keys. You'll need this to reveal API credentials later.
Invoice Branding (Optional): Upload a brand image (PNG or JPG, max 2MB) for your invoices.

2 Advanced Settings

Webhooks: Set your Endpoint URL for real-time notifications and choose the number of network confirmations required.
IP Whitelist: Restrict API access to specific IPs or domains. Leave blank to allow all traffic (not recommended).

3 Review

Summary: Final review of all configurations, including wallet identity, security, API configuration, platform fee, and estimated network gas before confirming creation.

Create via HMAC API

Authenticate with an existing wallet API key. The first wallet must be created in the dashboard. coin_symbol is required and must be the exact symbol — for the selected coin write USDTTRC20. is_testnet must match that symbol (false for USDTTRC20). HMAC create does not take a password or recaptcha_token.

GET/v1/wallets

List wallets for the authenticated user. Filter with coin_symbol.

Query Parameter	Type	Description
coin_symbol	string	Filter, e.g. USDTTRC20
is_testnet	boolean	Filter mainnet vs testnet wallets
search	string	Name search
page	number	Default 1
per_page	number	Default 20, max 100

Example Request

curl -X GET 'https://api.gammapay.io/v1/wallets?coin_symbol=USDTTRC20&page=1&per_page=20' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

POST/v1/wallets

Create a USDT TRC20 wallet. coin_symbol must be "USDTTRC20".

Body Field	Type	Description
coin_symbol *	string	Exact API symbol. For the selected coin write "USDTTRC20". Live TRON: TRX, USDTTRC20. Nile: TRX_NILE, USDTTRC20_NIL.
name *	string	Human-readable label (max 100 chars)
withdrawal_type *	string	Must be 'automatic' or 'manual'
is_testnet	boolean	Must match the symbol. Use false for USDTTRC20.
webhook_url	string	HTTPS URL for payment notifications
webhook_confirmation	number	Confirmations before webhook. Default for USDTTRC20: 19
ip_whitelist	string[]	Allowed IPv4/IPv6 addresses (max 25). Empty = allow all.
api_withdraw_enabled	boolean	Allow POST /v1/withdrawals. Default false.
daily_withdrawal_limit	string	Max 24h withdrawal in coin units (decimal string)
transaction_speed	string	'low', 'medium', or 'high'. Default 'low'.
logo_url	string	HTTPS URL of a logo shown on hosted invoices

Example Request

curl -X POST 'https://api.gammapay.io/v1/wallets' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"coin_symbol":"USDTTRC20","name":"USDT TRC20 HMAC Wallet","withdrawal_type":"automatic","is_testnet":false,"webhook_url":"https://api.yourdomain.com/webhooks","webhook_confirmation":19,"api_withdraw_enabled":true,"transaction_speed":"medium"}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "balance": {
      "available": "0",
      "pending": "0",
      "locked": "0",
      "total": "0"
    },
    "credentials": {
      "api_key": "wk_live_xyz1234342342342343",
      "api_secret": "sec_dummy_xyz1234342342342343",
      "key_version": 1,
      "shown_once": true
    },
    "wallet": {
      "api_withdraw_enabled": true,
      "coin_symbol": "USDTTRC20",
      "confirmation_threshold": 19,
      "created_at": "2026-09-16T12:20:34.564839Z",
      "daily_withdrawal_limit": null,
      "id": "7a2bc6e6-1a37-4f72-b6bd-272629ea49bc",
      "ip_whitelist": [],
      "is_active": true,
      "is_testnet": false,
      "logo_url": null,
      "name": "USDT TRC20 HMAC Wallet",
      "transaction_speed": "medium",
      "withdrawal_type": "automatic"
    }
  }
}

Get Wallet Detail

Retrieve the details of an existing wallet, including its configuration, balance, and API key metadata.

GET/v1/wallets/{wallet_id}

Get wallet details. coin_symbol in the response is "USDTTRC20" for this example.

Example Request

curl -X GET 'https://api.gammapay.io/v1/wallets/{wallet_id}' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "api_key_meta": {
      "created_at": "2026-09-16T12:20:34.564839Z",
      "is_revealed": false,
      "key_prefix": "wk_live_xyz1",
      "key_version": 1,
      "label": "default",
      "last_used_at": null,
      "last_used_ip": null,
      "request_count": 0,
      "reveal_supported": true,
      "revealed_at": null,
      "scopes": [
        "*"
      ]
    },
    "pending_ops_count": 0,
    "wallet": {
      "api_key": null,
      "api_secret": null,
      "api_withdraw_enabled": true,
      "balance": {
        "available": "0",
        "pending": "0",
        "locked": "0",
        "total": "0"
      },
      "coin_symbol": "USDTTRC20",
      "confirmation_threshold": 19,
      "created_at": "2026-09-16T12:20:34.564839Z",
      "daily_withdrawal_limit": null,
      "id": "7a2bc6e6-1a37-4f72-b6bd-272629ea49bc",
      "ip_whitelist": [],
      "is_active": true,
      "is_testnet": false,
      "key_version": null,
      "logo_url": null,
      "name": "USDT TRC20 HMAC Wallet",
      "shown_once": null,
      "transaction_speed": "medium",
      "withdrawal_type": "automatic"
    },
    "webhook": null
  }
}

Update Wallet

Update the configuration of an existing wallet. All body parameters are optional; only the provided fields will be modified.

PATCH/v1/wallets/{wallet_id}

Update wallet settings like webhook configuration, limits, and transaction speed.

Body Field	Type	Description
name	string	A human-readable label for the wallet
webhook_url	string \| null	URL to receive payment notifications. Set to null to remove.
webhook_secret	string	Secret used to sign webhook payloads.
webhook_confirmation	number	Number of network confirmations required before webhook triggers.
ip_whitelist	string[]	Array of allowed IP addresses for API access. Empty array clears the whitelist.
logo_url	string \| null	URL of the wallet logo image. Set to null to remove.
api_withdraw_enabled	boolean	Enable or disable programmatic withdrawals.
daily_withdrawal_limit	string \| null	Maximum daily withdrawal amount in native coin units. Set to null for unlimited.
transaction_speed	string	Gas preference: 'low', 'medium', or 'high'.

Example Request

curl -X PATCH 'https://api.gammapay.io/v1/wallets/{wallet_id}' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"name":"Updated USDT TRC20 Wallet","transaction_speed":"high","api_withdraw_enabled":true}'

Sample Response

{
  "flag": 1,
  "msg": "Wallet updated successfully",
  "data": {
    "api_withdraw_enabled": true,
    "coin_symbol": "USDTTRC20",
    "confirmation_threshold": 19,
    "created_at": "2026-09-16T12:20:34.564839Z",
    "daily_withdrawal_limit": null,
    "id": "7a2bc6e6-1a37-4f72-b6bd-272629ea49bc",
    "ip_whitelist": [],
    "is_active": true,
    "is_testnet": false,
    "logo_url": null,
    "name": "Updated USDT TRC20 Wallet",
    "transaction_speed": "high",
    "withdrawal_type": "automatic"
  }
}

API Credentials (Per-Wallet)

Every wallet has its own isolated API key pair. These credentials are used to authenticate API requests for that specific wallet.

Reveal Keys

Requires your dashboard password (+ 2FA code if enabled). The API secret is shown only once. After revealing, you cannot reveal again — only rotate.

Rotate Keys

Generates a new API key + secret pair. The previous keys are immediately invalidated. All active integrations must be updated. Requires password verification.

Enable API Withdraw

A toggle to allow or disallow withdrawals via API. When disabled, withdrawals can only be initiated from the dashboard UI. Acts as an additional safety layer.

POST/v1/wallets/{wallet_id}/api-keys

Generate a new API key and secret pair for the specified wallet. The secret will only be shown once in the response. Store it securely.

Body Field	Type	Description
label	string	A human-readable label for the API key (defaults to 'API Key {version}')
scopes	string[]	Array of permissions. Exact values: read, invoice.create, address.create, withdrawal.create, or * (all). 'write' is not a valid create-invoice/address/withdraw scope.
expires_at	string	ISO8601 timestamp for when this key should expire. If omitted, the key never expires.

Example Request

curl -X POST 'https://api.gammapay.io/v1/wallets/{wallet_id}/api-keys' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{
    "label": "New API Key",
    "scopes": ["read", "invoice.create", "address.create", "withdrawal.create"]
  }'

Sample Response

{
  "data": {
    "api_key": "wk_live_xyz1234342342342343",
    "api_secret": "sec_dummy_xyz1234342342342343",
    "expires_at": null,
    "key_prefix": "wk_live_xyz1",
    "key_version": 2,
    "label": "New API Key",
    "scopes": [
      "read",
      "invoice.create",
      "address.create",
      "withdrawal.create"
    ],
    "shown_once": true
  },
  "flag": 1,
  "msg": "success"
}

POST/v1/wallets/{wallet_id}/api-keys/rotate

Rotate the API key for a wallet. This endpoint requires step-up authentication (dashboard password) in the JSON body, even when called programmatically via HMAC.

Body Field	Type	Description
current_password *	string	Your dashboard account password
totp_code	string	Your 6-digit 2FA code, if two-factor authentication is enabled

Example Request

curl -X POST 'https://api.gammapay.io/v1/wallets/{wallet_id}/api-keys/rotate' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{
    "current_password": "your_dashboard_password_here"
  }'

Sample Response

{
  "data": {
    "api_key": "wk_live_xyz9876543210987654",
    "api_secret": "sec_dummy_xyz9876543210987654",
    "key_version": 3,
    "previous_key_expires_at": "2026-08-01T14:14:33.389313171Z",
    "shown_once": true
  },
  "flag": 1,
  "msg": "success"
}

Deposit Addresses

GammaPay uses BIP44 HD derivation (m/44'/coin_type'/0'/0/index) to generate unique deposit addresses for each wallet.

Coin goes in the path and must match the API key's wallet. For the selected coin that path is /v1/USDTTRC20/addresses. Expected format: Base58 (T...). Example: TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd — TRON Base58, starts with T. Never an 0x Ethereum address.

One address per invoice — addresses are never reused across invoices to maintain privacy and simplify tracking.
Labels (required): A label is mandatory when generating an address via API or dashboard (e.g., "Customer #1234"). Rules: 3–50 characters after trim, not whitespace-only, and must contain at least one letter or number. Missing or invalid label returns 400 with a clear error message.
QR Codes: Each address comes with an auto-generated QR code for easy display.
Monitoring: All generated addresses are automatically monitored by the blockchain scanner.

POST/v1/USDTTRC20/addresses

Generate a new HD deposit address for USDTTRC20 on TRON. label is mandatory. Scope: address.create.

Body Field	Type	Description
label *	string	Required. 3–50 chars after trim, not whitespace-only, must include a letter or number

Example Request

curl -X POST 'https://api.gammapay.io/v1/USDTTRC20/addresses' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"label":"Customer 1234"}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "coin": "USDTTRC20",
    "created_at": "2026-09-16T12:36:15.594508Z",
    "hd_index": 5,
    "label": "Customer 1234",
    "network": "TRON",
    "qr_code_url": "https://pay.gammapay.io/qr/TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd?coin=USDTTRC20"
  }
}

POST/v1/USDTTRC20/addresses/validate

Validate a TRON address before you whitelist or withdraw. Scope: read.

Body Field	Type	Description
address *	string	Address in Base58 (T...) format

Example Request

curl -X POST 'https://api.gammapay.io/v1/USDTTRC20/addresses/validate' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"address":"TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd"}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "coin": "USDTTRC20",
    "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "is_valid": true
  }
}

⚠️ CRITICAL: Cross-chain payments result in permanent fund loss. USDTTRC20 lives on TRON (Base58 (T...)). USDT on TRON is USDTTRC20, not USDTERC20. TRX and USDTTRC20 use different wallets even though both addresses start with T.

Wallet Settings & Controls

Setting	Type	Description
Wallet Name	string	Human-readable identifier or label for the wallet.
Daily Withdrawal Limit	string	Max amount withdrawable in 24h. Blank = no limit.
Webhook URL	string	Endpoint for receiving real-time payment notifications.
Webhook Secret	string	Cryptographic secret used to sign webhook payloads.
Confirmation Threshold	1–300	Block confirmations required before triggering webhook/status update.
Transaction Speed	low\|medium\|high	Affects network fee multiplier. High = faster confirmation, higher fee.
IP Whitelist	string[]	Restrict API access to specific IPs/domains. Blank = allow all.
API Withdraw Enabled	boolean	Toggle whether withdrawals can be initiated via API.
Logo URL	string	URL of the image used for custom invoice branding.

Invoices API Reference

Create uses body field coin (not coin_symbol). Get/list put the coin in the path. The HMAC key's wallet must already be USDTTRC20. Do not send wallet_id — it is ignored on HMAC. Min invoice for USDTTRC20: 10 USDTTRC20 (6 decimals). Omit currency (or set it to USDTTRC20) so amount is in coin units. If currency is USD / EUR / GBP / JPY, amount is fiat and GammaPay converts at the locked FX rate.

POST/v1/invoices

Create a USDT TRC20 payment request. coin must be "USDTTRC20". Scope: invoice.create.

Body Field	Type	Description
coin *	string	Exact symbol. For this coin write "USDTTRC20".
amount *	string	Decimal string. Default examples are 10 USDTTRC20 (native). If currency is USD/EUR/GBP/JPY, amount is fiat instead.
title	string	Defaults to 'Invoice'. Max 25 words / 255 chars.
currency	string	USD, EUR, GBP, or JPY (locks FX at creation). Omit or set to "USDTTRC20" for a native-coin amount.
expire_time	integer	Minutes until expiry (1–10080, default 60)
notify_url	string	HTTPS webhook callback URL
description	string	Detailed description (max 2000 chars)
customer_email	string	Customer email
customer_name	string	Customer name
custom_data	object	Arbitrary JSON returned on get/webhooks
success_url	string	Redirect URL on successful payment
cancel_url	string	Redirect URL on cancellation
send_email	boolean	Email the customer the invoice link
subtitle	string	Subtitle (max 40 words / 255 chars)

Example Request

curl -X POST 'https://api.gammapay.io/v1/invoices' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"coin":"USDTTRC20","amount":"10","expire_time":60,"title":"USDT TRC20 Invoice","notify_url":"https://api.yourdomain.com/webhook","custom_data":{"orderId":"ord_1001","userId":1}}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "amount": {
      "coin": "10",
      "fiat": null,
      "fiat_currency": "USDTTRC20"
    },
    "created_at": "2026-09-16T11:44:32.469809Z",
    "expires_at": "2026-09-16T12:44:32.469348Z",
    "id": "33fbc2e3-8441-4e45-ac16-61d3a0b075dc",
    "invoice_id": "inv_2503a52d02ba",
    "status": "pending",
    "url": "https://pay.gammapay.io/inv_2503a52d02ba"
  }
}

Fiat-denominated invoice (amount is 25.00 USD, converted to USDTTRC20 at the locked rate). Do not mix this with a native-coin amount.

Create invoice body — USD amount

{
  "coin": "USDTTRC20",
  "amount": "25.00",
  "currency": "USD",
  "expire_time": 60,
  "title": "USDT TRC20 Invoice (USD)",
  "notify_url": "https://api.yourdomain.com/webhook"
}

GET/v1/USDTTRC20/invoices/{invoice_id}

Fetch one invoice. invoice_id may be the UUID or the inv_… number. Path coin must be USDTTRC20. Scope: read. GET body is empty.

Example Request

curl -X GET 'https://api.gammapay.io/v1/USDTTRC20/invoices/inv_2503a52d02ba' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "amount": {
      "coin": "10.000000",
      "fiat": null,
      "fiat_currency": "USDTTRC20"
    },
    "coin_name": "USDT TRC20",
    "coin_symbol": "USDTTRC20",
    "created_at": "2026-09-16T11:44:32.469809Z",
    "custom_data": {
      "orderId": "ord_1001",
      "userId": 1
    },
    "customer_email": null,
    "customer_name": null,
    "description": null,
    "exchange_rate": "1.00000000",
    "expire_at": "2026-09-16T12:44:32.469348Z",
    "id": "33fbc2e3-8441-4e45-ac16-61d3a0b075dc",
    "invoice_id": "inv_2503a52d02ba",
    "network": "TRON",
    "paid_amount": "0",
    "paid_at": null,
    "payment_uri": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "status": "pending",
    "subtitle": null,
    "title": "USDT TRC20 Invoice",
    "url": "https://pay.gammapay.io/inv_2503a52d02ba"
  }
}

GET/v1/USDTTRC20/invoices

List invoices for the authenticated USDTTRC20 wallet.

Query Parameter	Type	Description
status	string	Filter by status: pending, confirming, partially_paid, paid, overpaid, expired, underpaid
page	number	Page number for pagination (default: 1)
per_page	number	Number of records per page (default: 20, max 100)
date_from	string	ISO-8601 lower bound on created_at
date_to	string	ISO-8601 upper bound on created_at

Example Request

curl -X GET 'https://api.gammapay.io/v1/USDTTRC20/invoices?page=1&per_page=20' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "invoices": [
      {
        "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
        "amount": {
          "coin": "10.000000",
          "fiat": null,
          "fiat_currency": "USDTTRC20"
        },
        "coin_name": "USDT TRC20",
        "coin_symbol": "USDTTRC20",
        "created_at": "2026-09-16T12:29:09.179077Z",
        "custom_data": {
          "orderId": "ord_1001",
          "userId": 1
        },
        "customer_email": null,
        "customer_name": null,
        "description": null,
        "exchange_rate": "1.00000000",
        "expire_at": "2026-09-16T13:29:09.178650Z",
        "id": "40497706-718c-4c72-a78a-80ce240e66c3",
        "invoice_id": "inv_a7b306da8d45",
        "network": "TRON",
        "paid_amount": "0",
        "paid_at": null,
        "payment_uri": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
        "status": "pending",
        "subtitle": null,
        "title": "USDT TRC20 Invoice",
        "url": "https://pay.gammapay.io/inv_a7b306da8d45"
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Invoice Status Flow

The status field in the API response strictly follows this lifecycle:

pending (awaiting payment) → confirming (transaction detected, accumulating confirmations) → paid (full amount confirmed on-chain)

Alternate flows:
→ partially_paid (partial payment confirmed, awaiting more funds)
→ expired (time window elapsed with zero payments)
→ underpaid (expired while in partially_paid state)
→ overpaid (total confirmed funds exceed required amount)

Edge Cases & Transactions

Transaction Confirmation Flow: When a payment is detected, the invoice status changes to confirming. Once the transaction reaches the required confirmations, the status updates to paid (if full amount) or partially_paid (if partial amount). Check the invoice's associated transactions endpoint to track confirmation progress.
Partial Payments: If the confirmed amount is less than the invoice total, status becomes partially_paid. The invoice remains open for additional payments until expiry or the full amount is received.
Underpayment: Status becomes underpaid after expiry if the invoice was in partially_paid state.
Overpayment: Marked overpaid. Excess funds are credited to your wallet balance.
Wrong Network/Token: Funds sent on the wrong network or as the wrong token are lost permanently. USDTTRC20 invoices only detect USDTTRC20 on TRON. TRX ≠ USDTTRC20 ≠ USDTERC20.

Withdrawals

Withdrawals send USDTTRC20 from the wallet bound to your API key to an external TRON address. Do not send a coin field — the coin is implied by the key. Destination example for USDTTRC20: TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd

API key scope withdrawal.create (or *) and wallet api_withdraw_enabled = true.
Whitelist is optional for HMAC unless the wallet has api_requires_whitelist = true. Dashboard withdrawals always require a confirmed whitelist entry. When enforced, POST /v1/wallets/{wallet_id}/whitelist with address, label, and totp_code, then complete the email confirmation.
X-Idempotency-Key is required and is part of the HMAC payload: timestamp.body.idempotencyKey.
TOTP is not required on HMAC withdrawals (dashboard withdrawals still require 2FA).
Fee model is additive: you enter the amount the recipient should receive; you pay amount + platform fee (the fee configured in platform settings) from available balance.
TRC-20 withdrawals still settle on TRON. Energy/bandwidth is handled by GammaPay; you withdraw from the USDTTRC20 wallet, not a TRX wallet.

Withdrawal Signature (includes Idempotency Key)

Signature Formula

payload = timestamp + "." + rawBody + "." + idempotencyKey
signature = HMAC-SHA256(api_secret, payload)

POST/v1/withdrawals

Withdraw USDTTRC20 to a TRON address. Scope: withdrawal.create. Coin is implied by the API key — do not send coin.

Body Field	Type	Description
destination_address *	string	Base58 (T...). Example: TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd
amount *	string	Amount of USDTTRC20 the destination receives (decimal string)
note	string	Optional note (max 500 chars)

Example Request

curl -X POST 'https://api.gammapay.io/v1/withdrawals' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -H "X-Idempotency-Key: 9eb581a2-ca56-447f-908f-26959444b9a1" \
  -d '{"destination_address":"TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd","amount":"10","note":"API payout"}'

Sample Response

{
  "flag": 1,
  "msg": "Withdrawal request submitted and queued for broadcasting.",
  "data": {
    "id": "68a0cf9f-94eb-4f73-9c3b-e5f419beee99",
    "wallet_id": "7a2bc6e6-1a37-4f72-b6bd-272629ea49bc",
    "coin_symbol": "USDTTRC20",
    "amount": "10",
    "gross_amount": "10",
    "fee_bps": 0,
    "fee_amount": "0",
    "net_amount": "10",
    "destination_address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "status": "approved",
    "note": "API payout",
    "created_at": "2026-09-16T03:35:09Z",
    "remaining_withdraw_limit_24h": null,
    "source": "api"
  }
}

POST/v1/wallets/{wallet_id}/whitelist

Add a TRON payout address. TOTP is required. Email confirmation is still required before the address can be used if whitelist enforcement is on.

Body Field	Type	Description
address *	string	Base58 (T...). Example: TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd
label *	string	Label, max 50 characters
totp_code *	string	6-digit authenticator code from the merchant dashboard 2FA

Example Request

curl -X POST 'https://api.gammapay.io/v1/wallets/{wallet_id}/whitelist' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"address":"TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd","label":"HMAC payout dest","totp_code":"123456"}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "label": "HMAC payout dest",
    "email_confirmed": false,
    "is_active": true
  }
}

GET/v1/withdrawals/{id}

Retrieve a USDTTRC20 withdrawal. Scope: read. Empty body.

Example Request

curl -X GET 'https://api.gammapay.io/v1/withdrawals/68a0cf9f-94eb-4f73-9c3b-e5f419beee99' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "id": "68a0cf9f-94eb-4f73-9c3b-e5f419beee99",
    "wallet_id": "7a2bc6e6-1a37-4f72-b6bd-272629ea49bc",
    "coin_symbol": "USDTTRC20",
    "amount": "10",
    "destination_address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
    "status": "completed",
    "tx_hash": "a1b2c3d4e5f67890...",
    "note": "API payout",
    "confirmations": 19,
    "required_confirmations": 19,
    "reviewed_at": "2026-09-16T04:12:02Z",
    "confirmed_at": "2026-09-16T04:25:00Z",
    "created_at": "2026-09-16T03:35:09Z"
  }
}

GET/v1/withdrawals

List withdrawals for the authenticated wallet.

Query Parameter	Type	Description
page	int	Page number (default 1)
per_page	int	Items per page
status	string	Optional status filter

Example Request

curl -X GET 'https://api.gammapay.io/v1/withdrawals?page=1&per_page=20' \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..."

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "withdrawals": [
      {
        "id": "68a0cf9f-94eb-4f73-9c3b-e5f419beee99",
        "coin_symbol": "USDTTRC20",
        "amount": "10",
        "destination_address": "TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd",
        "status": "completed"
      }
    ]
  }
}

POST/v1/withdrawals/estimate

Estimate fee for a USDTTRC20 withdrawal without creating it.

Body Field	Type	Description
destination_address *	string	Whitelisted TRON address
amount *	string	Amount in USDTTRC20

Example Request

curl -X POST 'https://api.gammapay.io/v1/withdrawals/estimate' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xyz1234342342342343" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: sha256=..." \
  -d '{"destination_address":"TKs4P6BuXxDDg7b3LuMVKaRw7U7YTXqHUd","amount":"10"}'

Sample Response

{
  "flag": 1,
  "msg": "success",
  "data": {
    "amount": "10",
    "fee_amount": "0",
    "net_amount": "10",
    "gross_amount": "10",
    "total_to_send": "10",
    "withdrawal_speed": "standard",
    "remaining_withdraw_limit_24h": null
  }
}

Webhooks (IPN)

Webhooks provide real-time notifications when transaction states change. Configure a webhook URL per wallet in the dashboard.

Dashboard Webhook Management

Set URL: Enter an HTTPS endpoint and run a connection test before saving.
Test: Sends a test payload to verify your endpoint responds with 200 OK.
Webhook Secret: Each wallet has a unique HMAC secret for verifying webhook authenticity. Reveal it with password + 2FA.
Rotate Secret: Invalidates the current secret and generates a new one.
Remove: Deletes the webhook configuration entirely.
Delivery Logs: View all webhook delivery attempts with status, response code, timestamps, and retry count.

Event Types

Event	Trigger
transaction.confirmed	Payment fully confirmed on-chain
transaction.detected	Payment detected in mempool (unconfirmed)
payment.underpaid	Invoice expired with partial payment
withdrawal.created	New withdrawal request submitted
withdrawal.completed	Withdrawal broadcast and confirmed on-chain
withdrawal.failed	Withdrawal rejected or broadcast failed

Sample Payloads

transaction.confirmed

{
  "event": "transaction.confirmed",
  "amount": "10",
  "coin": "USDTTRC20",
  "confirmed_at": "2026-09-16T03:10:35Z",
  "net_amount": "10",
  "platform_fee": "0",
  "transaction_id": "ec0334e-3eb6-43cf-aa95-c7be9bec950b",
  "tx_hash": "a1b2c3d4e5f67890...",
  "wallet_id": "5e9c5b14-0bae-415d-aca2-725962c68ab8"
}

Webhook Signature Verification

Extract X-NeonPay-Timestamp and X-NeonPay-Signature headers. Also present: X-NeonPay-Event, X-NeonPay-Delivery-Id, X-NeonPay-Idempotency-Key.
Check |now - timestamp| < 300 seconds.
Compute: HMAC-SHA256(webhook_secret, timestamp + "." + rawBody)
Compare using timingSafeEqual.

Retry Schedule

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours

After 6 failed attempts, the event is moved to a dead letter queue and the merchant is alerted via email.

Security Features

GammaPay implements multiple layers of security to protect your funds and account. These features are available in the Security section of your dashboard.

Two-Factor Authentication

TOTP-based 2FA with anti-phishing image protection and backup recovery codes.

IP Whitelisting

Restrict API access to approved IP addresses only.

Login Shield

Blocks login from unrecognized devices until email confirmation.

Session Management

View and terminate active sessions. Configurable session timeout.

Two-Factor Authentication (2FA)

TOTP (Time-based One-Time Password) adds a second layer of security. It is required for dashboard withdrawals, security settings changes, and API key operations.

Setup Flow

Verify Password: Enter your current account password to initiate setup.
Scan QR Code: Scan the displayed QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.). Or manually enter the secret key.
Select Anti-Phishing Image: Choose a personalized image from categories (Animals, Vehicles, Objects). This image appears in all security emails from GammaPay.
Verify Code: Enter the 6-digit code from your authenticator app to confirm setup.
Save Recovery Codes: Download and securely store your one-time backup recovery codes. These are the only way to regain access if you lose your authenticator device.

⚠️ IMPORTANT: Recovery codes are shown only once during setup. Store them in a password manager or physical safe. If lost, account recovery requires manual identity verification.

Anti-Phishing Image Protection

During 2FA setup, you select a personalized security image. This image is embedded in all official GammaPay emails (whitelist verification, login alerts, etc.).

How it protects you:

Every security-sensitive email from GammaPay includes YOUR chosen image.
If you receive an email claiming to be from GammaPay but the image is wrong or missing — it's a phishing attempt.
You can change your anti-phishing image at any time from Security settings.
Images are categorized into Animals, Vehicles, and Objects for easy selection.

IP Whitelisting (Account-Level)

When enabled, API requests are only accepted from IP addresses you specify. This is a global toggle that applies to all wallets on your account.

Toggle on/off from Security → IP Whitelisting
Configure IPs per-wallet in the wallet settings (Deposit & Withdraw tab → Security Whitelist section)
Supports IPv4 and IPv6 addresses only (domains are not supported)
Requests from non-whitelisted IPs receive a 403 Forbidden response

Login Shield

When enabled, login from a new device/location triggers an email confirmation.
The account remains locked until the email link is clicked.
Prevents unauthorized access even if password is compromised (without 2FA).
Toggle on/off from Security settings.

Session Management

Active Sessions: View all currently active sessions (device, IP, browser, last active time).
Terminate Sessions: Remotely log out any active session from the Active Sessions page.
Session Timeout: Configure auto-logout after inactivity (configurable from Notifications settings).
Login History: Full audit log of all login attempts (successful and failed) with IP, timestamp, and device info.

API Logs

Every API request made against your wallet is logged and available for inspection in the API Logs tab of each wallet. This provides a complete audit trail for debugging and security monitoring.

Log Entry Fields

Field	Description
Status Code	HTTP response code (200, 400, 401, 403, 429, 500, etc.)
Method & Endpoint	HTTP method (GET/POST/PATCH/DELETE) and the full endpoint path
IP Address	Source IP of the request
Duration	Request processing time in milliseconds
Date	Full timestamp of when the request was received
Description	Error description (shown for failed requests)

Debugging Tips

401 errors: Check your HMAC signature calculation. Ensure timestamp skew is within 300 seconds.
403 errors: Your IP may not be whitelisted, or the API key lacks required permissions.
429 errors: You're hitting rate limits. Implement exponential backoff.
High latency: If duration exceeds 5000ms, check if your request payload is unusually large.
Unexpected IPs: If you see requests from unknown IPs, rotate your API keys immediately and enable IP whitelisting.

Notifications

Configure how and when GammaPay notifies you about account activity. Navigate to Settings → Notifications in your dashboard.

Notification Types

Category	Email	Push	Description
Security	✓	✓	Login alerts, 2FA changes, password updates
Transactions	✓	✓	Incoming deposits, withdrawal confirmations
Invoices	✓	✓	Invoice paid, expired, underpaid
System	✓	✓	Maintenance, feature updates, plan changes
Weekly Summary	✓	—	Weekly digest of transaction volume and revenue

Configuration Options

Email on Login: Receive an email every time your account is accessed.
Transaction Alerts: Get notified for every incoming/outgoing transaction.
Language: Set preferred language for notifications.
Currency: Default fiat currency (USD, EUR, GBP, JPY) for live dashboard equivalents. Existing invoices keep the fiat they were created with.
Timezone: Affects all timestamp formatting in notifications.
Session Timeout: Auto-logout after configurable inactivity period (in minutes).

Developer Guides

Accept a Payment (Full Flow)

Create a wallet for the desired coin in the dashboard.
Get your API credentials from the wallet's API Keys tab.
Call POST /v1/invoices with { "coin": "USDTTRC20", "amount": "10" }.
Redirect the customer to the returned url or display the address with amount.
Listen for the transaction.confirmed webhook event.
Verify the webhook signature using your wallet's webhook secret.
Fulfill the order once payment is confirmed.

Best Practice

X-Idempotency-Key is required on withdrawals (and is part of the HMAC payload). It is optional on invoice create; if you send it, include it in the signature.

Crypto vs Fiat Payments

Fiat Mode

Set currency: "USD" | "EUR" | "GBP" | "JPY". GammaPay locks the exchange rate at invoice creation and calculates the required crypto amount. Changing your dashboard display currency later does not rewrite this invoice.

Native Coin Mode

Set currency: "USDTTRC20" or omit currency. No conversion. Customer pays the exact USDTTRC20 amount specified.

Handling Underpayments

Monitor for the payment.underpaid webhook event.
The webhook payload includes amount_received_coin and shortfall_coin.
You can manually mark the invoice as paid in the dashboard if the shortfall is negligible.
Otherwise, the invoice remains underpaid until the remaining balance is sent to the same address.

Test Your Integration

Use testnet coins: Create wallets with TRX_NILE, USDTTRC20_NIL, or Sepolia symbols (ETH_SEPOLIA, USDTERC20_SEP). Set is_testnet: true only with those symbols.
Faucets: Get free testnet tokens from Sepolia faucets for ETH/ERC20 or Nile faucet for TRC20.
Webhook testing: Use the built-in "Test Webhook" button in the dashboard or tools like webhook.site.
API Logs: Monitor all requests in real-time from the API Logs tab.

Security Best Practices

Never share your api_secret — store it only on your backend server, never in frontend code or version control.
Enable 2FA immediately — it's required for withdrawals and provides critical protection.
Verify webhook signatures — always validate the HMAC signature before processing webhook events.
Use IP whitelisting — restrict API access to your known server IPs.
Set daily withdrawal limits — cap exposure in case of credential compromise.
Rotate keys periodically — rotate API keys and webhook secrets on a regular schedule.
Monitor API logs — watch for unexpected IPs or unusual request patterns.
Use idempotency keys — prevent duplicate charges from retry logic.

Glossary

HMAC

Hash-based Message Authentication Code. Used to sign API requests.

Nonce / Timestamp

A value used once to prevent replay attacks. GammaPay uses Unix timestamps.

Webhook

An HTTP callback that notifies your server of events automatically.

Mempool

The waiting area for transactions before they are added to a block.

Confirmations

The number of blocks added after yours. More = more secure.

Testnet

An alternative blockchain used for testing without using real value.

BIP44

HD wallet derivation standard used to generate unique addresses.

TOTP

Time-based One-Time Password. The standard behind 2FA authenticator apps.

Idempotency Key

A UUID ensuring the same operation isn't executed twice on retry.

Whitelist

A pre-approved list of addresses that can receive withdrawals.

coin_symbol

Exact API identifier for create-wallet (e.g. USDTTRC20, TRX, TRX_NILE). Not a display name.

coin

Exact API identifier in invoice bodies and in paths like /v1/{coin}/addresses.

TRC20

TRON token standard. USDTTRC20 is Tether on TRON; it is not USDTERC20.

wk_live_ / wk_test_

Wallet HMAC API key prefixes for mainnet and testnet.