Skip to content

README.en.md

Latest commit

 

History

History
235 lines (177 loc) · 5.39 KB

README.en.md

File metadata and controls

235 lines (177 loc) · 5.39 KB

EPTRC

中文 | English

EPTRC (Easy Payment TRC) is a lightweight TRC20-USDT payment gateway.

Merchant systems can integrate USDT collection through simple HTTP APIs + Webhook callbacks.

Quick Start

bun install
bun run dev

Environment Variables

PORT=3000
API_KEY=it.is.very.secret
WEBHOOK_KEY=it.is.webhook.secret
DB_FILE_NAME=eptrc.sqlite
TRON_NETWORK=nile
  • PORT: service port, default 3000.
  • API_KEY: auth key for business endpoints (X-API-KEY).
  • WEBHOOK_KEY: auth key used for webhook delivery; falls back to API_KEY if unset.
  • DB_FILE_NAME: SQLite database file name, default eptrc.sqlite.
  • TRON_NETWORK: nile for testnet, main for mainnet.

Scripts

  • bun run dev: start local development server (hot reload)
  • bun run lint: run oxlint
  • bun run lint:fix: run oxlint with auto fixes
  • bun run db:generate: generate Drizzle migrations from schema changes
  • bun run db:check: verify schema and migrations are synchronized
  • bun run db:push: push Drizzle schema to the database
  • bun run build:bun: build Bun runtime version to dist/
  • bun run build:linux-x64: build Linux x64 executable
  • bun run build:windows-x64: build Windows x64 executable
  • bun run build:darwin-x64: build macOS Intel x64 executable
  • bun run build:darwin-arm64: build macOS Apple Silicon executable

Authentication

  • GET / does not require authentication.
  • Other endpoints require X-API-KEY in request headers.

Integration Flow

  1. Call POST /paymentSession/create to create a payment session.
  2. Show the returned address and ask the user to transfer funds.
  3. Receive Webhooks (payment.session.paid or payment.session.timeout).
  4. Call POST /paymentSession/detail for reconciliation when needed.
  5. Periodically call POST /wallet/collect to collect paid wallet balances.

Amount Precision

  • All amount fields use integer strings in on-chain minimal units.
  • TRC20-USDT uses decimals = 6.
  • Conversion example: 1000000 = 1.000000 USDT.

API

  • Business succeeded: return HTTP 200.
  • Business failed: return HTTP 4xx or HTTP 5xx.

Health Check

GET /

Response example (HTTP 200):

{
  "version": "1.0.0",
  "tronGridBaseUrl": "https://nile.trongrid.io",
  "contractAddress": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"
}

Create Payment Session

POST /paymentSession/create

Request body:

{
  "metadata": "{\"orderId\":\"order.123\",\"userId\":\"user.456\"}",
  "notifyUrl": "https://api.merchant-system.com/eptrcNotify"
}
  • notifyUrl: required callback URL for payment results.
  • metadata: optional; any string, passed through unchanged in webhook payload.

Response example (HTTP 200):

{
  "paymentSessionId": "019bf34f-9bec-7000-9b43-2ff5f5b0427d",
  "address": "TTU6hE7tn9UX9XxcbQ3fZMZY3SH4GfMYZy",
  "expiresAt": 1577934245000
}

Query Payment Session Detail

POST /paymentSession/detail

Request body:

{
  "paymentSessionId": "019bf34f-9bec-7000-9b43-2ff5f5b0427d"
}

Use this endpoint to query session status, paid amount, blockchain tx id, and collection state.

Response example (HTTP 200):

{
  "id": "019bf34f-9bec-7000-9b43-2ff5f5b0427d",
  "metadata": "{\"orderId\":\"order.123\",\"userId\":\"user.456\"}",
  "amount": "1000000",
  "notifyUrl": "https://api.merchant-system.com/eptrcNotify",
  "address": "TTU6hE7tn9UX9XxcbQ3fZMZY3SH4GfMYZy",
  "status": "paid",
  "collected": 0,
  "blockchainTxId": "2a6a...",
  "paidAt": 1577934200000,
  "expiresAt": 1577934245000
}

Wallet Collect

POST /wallet/collect

Request body:

{
  "toAddress": "TRx...target.address",
  "feePayerPrivateKey": "your.fee.payer.private.key"
}
  • toAddress: destination address for collection.
  • feePayerPrivateKey: private key of the wallet paying TRX network fees.
  • Ensure this key's address has enough TRX.
  • Never expose this key in frontend code, logs, or public channels.

Response example (HTTP 200):

{
  "collectResults": [
    {
      "address": "Txxx...",
      "status": "collected",
      "amount": "1000000",
      "txId": "2a6a..."
    },
    {
      "address": "Tyyy...",
      "status": "no.balance"
    },
    {
      "address": "Tzzz...",
      "status": "error",
      "error": "collect.failed"
    }
  ]
}

Webhook

When session status changes, EPTRC sends a POST request to notifyUrl.

Request headers:

X-API-KEY: <WEBHOOK_KEY>
Content-Type: application/json
User-Agent: EPTRC/<version>

Merchant response requirements:

  • Return HTTP 200 so EPTRC marks delivery as successful.
  • Non-200 responses are treated as failures and retried (max retries: 10).
  • Verify X-API-KEY equals configured WEBHOOK_KEY (or fallback API_KEY if unset).

Event types:

  • payment.session.paid
  • payment.session.timeout

payment.session.paid example:

{
  "event": "payment.session.paid",
  "data": {
    "paymentSessionId": "019bf34f-9bec-7000-9b43-2ff5f5b0427d",
    "metadata": "{\"orderId\":\"order.123\",\"userId\":\"user.456\"}",
    "amount": "1000000"
  }
}

payment.session.timeout example:

{
  "event": "payment.session.timeout",
  "data": {
    "paymentSessionId": "019bf34f-9bec-7000-9b43-2ff5f5b0427d",
    "metadata": "{\"orderId\":\"order.123\",\"userId\":\"user.456\"}"
  }
}

Support

If this project helps you, you can support via this TRON address:

TTU6hE7tn9UX9XxcbQ3fZMZY3SH4GfMYZy