1. Connect your xPub
Start here: open @portmanto, tap "Open iCryptex" and send /register. iCryptex is non-custodial. Invoice addresses are derived from your wallet's account xPub, so customer payments land on addresses only you can spend from. Your private keys stay in iCryptex Keyring on your computer.
Generate your xPub with the offline generator the iCryptex bot sends after /register (open it from @portmanto). Later, import the same recovery phrase into iCryptex Keyring to sign sweeps. Your private keys never leave your computer.
Without an xPub, creating an invoice returns 409. The dashboard checklist shows "xPub connected" when it is attached.
2. Get your API key
In the iCryptex bot, send /api_key after your xPub is connected. The key is shown once, then only its last characters. You can reissue it there with a confirmation. During early access, if /api_key is not available yet, an admin issues the key.
Sandbox keys start with pk_test_ (Nile); live keys start with pk_live_ (mainnet, on request).
Copy it now, it is shown only once. We store only a sha256 hash of the key and cannot show it again. If you lose it, reissue it in the iCryptex bot (open it from @portmanto) with a confirmation. A test key sent to the mainnet API (or a live key to the sandbox) is rejected with 401.
Send the key on every request as Authorization: Bearer <api_key> or X-API-Key: <api_key>. The same key logs you in to the dashboard. Keep it on your server only.
Sandbox (Nile) base URL: https://api.icryptex.com/v1. The mainnet host is provided together with your live key. Every route lives under /v1. Connectivity check: GET /v1/merchant/settings returns 401 without a key and your settings with one.
curl -i https://api.icryptex.com/v1/merchant/settings # 401 without a key
curl -H "Authorization: Bearer pk_test_..." https://api.icryptex.com/v1/merchant/settings3. Create an invoice
POST /v1/invoices creates an invoice and returns 201 with a unique TRC-20 address. Send an Idempotency-Key to make retries safe: the same key and body returns the stored response with Idempotent-Replayed: true.
curl https://api.icryptex.com/v1/invoices \
-H "Authorization: Bearer pk_test_..." \
-H "Idempotency-Key: order-1042" \
-H "Content-Type: application/json" \
-d '{"amount": 50, "description": "Order #1042", "metadata": {"order_id": "1042"}, "timeout_seconds": 1800}'| Field | Type | Notes |
|---|---|---|
amount | number | Fixed invoice amount in USDT, above 0 and up to 1,000,000. Omit it for an open invoice. |
type | "fixed" or "open" | Optional. An invoice with an amount is fixed. |
min_amount | number | Open invoices only. Default: your merchant default_min_amount, else 10. |
description | string | Up to 500 characters. |
account | integer | xPub account to derive the address from. Default: the primary one. |
customer_ref (alias buyer_id) | string | Up to 128 characters. Reuses one stable address per customer. |
timeout_seconds | integer | 60 to 86400, default 3600. |
expiry | integer | Alias of timeout_seconds; both given and different is 422. |
metadata | object | Echoed in reads and webhooks, up to 4096 bytes and 50 keys. |
callback_url | string | https only, up to 2048 characters; loopback, link-local, metadata and reserved targets are refused. Overrides your webhook URL for this invoice. 409 if you have no webhook secret yet. |
refund_address | string | The payer's TRON address for refunds (base58 with a valid checksum). |
amount_fiat | number | A price in currency (at most 2 decimals), sent instead of amount. Fixed invoices only; the rate is locked until the invoice expires (at most 20 minutes). |
currency | string | "USDT" or the 3-letter ISO code of amount_fiat. |
success_url | string | Where the checkout page sends the customer once the invoice is paid. |
cancel_url | string | The "back to the shop" link on the checkout page. |
locale | string | Checkout page language: en, es or pt-BR. Anything else falls back to English. |
Response (shortened):
{
"invoice_id": 1042,
"type": "fixed",
"status": "pending",
"amount": 50.0,
"address": "TRRPU387srsJJKiv8DfEsPnLBiWBcRMfCu",
"payment_uri": "tron:TRRPU387srsJJKiv8DfEsPnLBiWBcRMfCu?amount=50.0&token=TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
"expires_at": "2026-10-04T10:25:00.412907+00:00",
"checkout_url": "<checkout_url>",
"livemode": false,
"network": "nile"
}network is "mainnet" or "nile". checkout_url is the hosted payment page: redirect the customer to checkout_url exactly as returned by the API, or show the address and amount yourself. On Nile the token in payment_uri is the Nile USDT contract. Timestamps in API responses are ISO 8601 in UTC; webhook payloads use the Z form. Parse both with an ISO 8601 parser.
Read it back with GET /v1/invoices/{id}; list with GET /v1/invoices. Cancel a pending invoice with DELETE /v1/invoices/{id}.
4. Pay it on Nile
On the sandbox the customer sends Nile test USDT to the invoice address. Two ways to get it:
- If enabled on the sandbox stand, the payment page shows a "Pay for me (test USDT)" button (
POST /pay/{token}/simulate) that pays from the sandbox faucet. It never exists on mainnet. - Get Nile test USDT and TRX from the Nile faucet and send the USDT from any TRON wallet.
A transfer is counted once its block is 19 blocks deep (about one minute). Until then the invoice is detected; then it becomes paid. A short payment within the tolerance (default the larger of 0.5 USDT and 1%) still counts as paid.
5. Verify webhooks
iCryptex POSTs events to your webhook URL. Set it in the dashboard (Settings > Webhooks) or with PUT /v1/merchant/webhook {"webhook_url": "https://...", "rotate_secret": false}; the first URL and every rotation return a new signing secret once, in that response only. The body is canonical JSON (sorted keys, no spaces) and the header X-Porto-Signature is the lowercase hex HMAC-SHA256 of the raw body bytes, keyed with your webhook secret. Version 1 has no timestamp header: verify the signature over the raw body before parsing and deduplicate on event_id. Any 2xx response is success.
import hashlib, hmac
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, signature, secret) {
const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
return expected.length === signature.length && timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}Test vector (v1)
| Input | Value |
|---|---|
| secret | whsec_test_vector_0001 |
| raw body | {"event":"invoice.paid","event_id":"3f1c0a9e5b7d4e2a8c6b1d0f9e8a7b6c","livemode":false} |
| X-Porto-Signature | ad9f5d79979e6edbefe0badaf65ff57e5af78775005bd28d33df9583655f2462 |
printf '%s' '{"event":"invoice.paid","event_id":"3f1c0a9e5b7d4e2a8c6b1d0f9e8a7b6c","livemode":false}' \
| openssl dgst -sha256 -hmac whsec_test_vector_0001Events
| Event | When |
|---|---|
invoice.paid | The invoice reached paid (once). Also per transfer to a customer_ref address with no open invoice. |
invoice.overpaid | Paid with more than the amount, or a later transfer to a paid invoice. |
invoice.underpaid | A confirmed transfer leaves a fixed invoice short. |
invoice.partial | The same as invoice.underpaid, for legacy invoices. |
invoice.below_minimum | An open invoice is below min_amount. |
invoice.late_payment | Funds arrived after expiry or cancellation. |
invoice.expired, invoice.cancelled | The invoice closed without payment. |
invoice.detected | A transfer is in a block but not final; off by default. |
sweep.completed | A sweep signed in iCryptex Keyring closed the invoice. |
invoice.resolved | You or an admin resolved an edge case (credit a late payment, mark paid, mark for refund); top-level resolution holds the logged entry. |
invoice.refund_address_set | A refund address was set (by you, the checkout form or the sandbox faucet). |
invoice.recreated | The customer replaced an expired invoice from the checkout page; top-level recreated holds the new invoice id and checkout URL. |
deposit.received | A confirmed transfer to a customer's permanent deposit address; no invoice, top-level customer instead. |
Payload (shortened):
{
"event": "invoice.paid",
"event_id": "3f1c0a9e5b7d4e2a8c6b1d0f9e8a7b6c",
"timestamp": "2026-10-04T10:01:05Z",
"livemode": false,
"network": "nile",
"invoice": {"invoice_id": 1042, "address": "TRRPU387srsJJKiv8DfEsPnLBiWBcRMfCu", "customer_ref": null, "status": "paid", "amount": 50.0, "amount_received": 50.0, "metadata": {"order_id": "1042"}},
"transaction": {"tx_hash": "e8db4a17...", "from_address": "TSa6Hr3mmPsCkLcQFEjieEtSeW1ASY6UVV", "amount": 50.0, "block_number": 68900005, "confirmed": true, "kind": "payment"}
}Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h and 12 h (6 attempts in total). List deliveries with GET /v1/webhooks/deliveries and resend one, in any state, from the dashboard or with POST /v1/webhooks/deliveries/{id}/resend (same bytes and event_id; up to 10 resends of one delivery per hour). Check livemode so a test event never fulfils a real order.
6. Statuses
| Status | Group | Meaning |
|---|---|---|
pending | open | Awaiting payment. |
activating | open | Internal; treat as pending. |
detected | open | A transfer is in a block, not yet final. |
underpaid / partial | open | Fixed invoice: confirmed total below amount minus tolerance. |
below_minimum | open | Open invoice: confirmed total below min_amount. |
paid | paid | Fully paid (overpayment shows in overpaid_amount). |
expired | closed | Not paid in time. |
cancelled | closed | Cancelled by you. |
late_payment | closed | Funds arrived after expiry or cancellation. |
withdrawn / swept | closed | Funds were swept to your wallet. |
7. Go live
The dashboard checklist ("Before you go live") shows what is missing: xPub connected, webhook URL and secret set, last delivery succeeded and a paid test invoice. Mainnet is available on request through support in the iCryptex bot (open it from @portmanto). Then:
- Get a
pk_live_key with/api_keyon the mainnet deployment (during early access an admin may issue it). The mainnet host is provided together with your live key. - Connect your mainnet account xPub there. Never reuse a test wallet for real money.
- Point your integration at the mainnet host with the live key, and set your webhook URL and secret again there (or a new secret).
- Keep the sandbox key for your staging environment.
Endpoints and payloads stay the same; livemode becomes true.
During early access, plan activation, changes and cancellation go through support in the iCryptex bot. Billed monthly in USDT.