DOCS / API

API quickstart

From API key to a verified webhook on the TRON Nile sandbox.

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.

shell
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/settings

3. 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.

shell
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}'
FieldTypeNotes
amountnumberFixed 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_amountnumberOpen invoices only. Default: your merchant default_min_amount, else 10.
descriptionstringUp to 500 characters.
accountintegerxPub account to derive the address from. Default: the primary one.
customer_ref (alias buyer_id)stringUp to 128 characters. Reuses one stable address per customer.
timeout_secondsinteger60 to 86400, default 3600.
expiryintegerAlias of timeout_seconds; both given and different is 422.
metadataobjectEchoed in reads and webhooks, up to 4096 bytes and 50 keys.
callback_urlstringhttps 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_addressstringThe payer's TRON address for refunds (base58 with a valid checksum).
amount_fiatnumberA 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).
currencystring"USDT" or the 3-letter ISO code of amount_fiat.
success_urlstringWhere the checkout page sends the customer once the invoice is paid.
cancel_urlstringThe "back to the shop" link on the checkout page.
localestringCheckout page language: en, es or pt-BR. Anything else falls back to English.

Response (shortened):

json
{
  "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.

python
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)
javascript
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)

InputValue
secretwhsec_test_vector_0001
raw body{"event":"invoice.paid","event_id":"3f1c0a9e5b7d4e2a8c6b1d0f9e8a7b6c","livemode":false}
X-Porto-Signaturead9f5d79979e6edbefe0badaf65ff57e5af78775005bd28d33df9583655f2462
shell
printf '%s' '{"event":"invoice.paid","event_id":"3f1c0a9e5b7d4e2a8c6b1d0f9e8a7b6c","livemode":false}' \
  | openssl dgst -sha256 -hmac whsec_test_vector_0001

Events

EventWhen
invoice.paidThe invoice reached paid (once). Also per transfer to a customer_ref address with no open invoice.
invoice.overpaidPaid with more than the amount, or a later transfer to a paid invoice.
invoice.underpaidA confirmed transfer leaves a fixed invoice short.
invoice.partialThe same as invoice.underpaid, for legacy invoices.
invoice.below_minimumAn open invoice is below min_amount.
invoice.late_paymentFunds arrived after expiry or cancellation.
invoice.expired, invoice.cancelledThe invoice closed without payment.
invoice.detectedA transfer is in a block but not final; off by default.
sweep.completedA sweep signed in iCryptex Keyring closed the invoice.
invoice.resolvedYou 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_setA refund address was set (by you, the checkout form or the sandbox faucet).
invoice.recreatedThe customer replaced an expired invoice from the checkout page; top-level recreated holds the new invoice id and checkout URL.
deposit.receivedA confirmed transfer to a customer's permanent deposit address; no invoice, top-level customer instead.

Payload (shortened):

json
{
  "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

StatusGroupMeaning
pendingopenAwaiting payment.
activatingopenInternal; treat as pending.
detectedopenA transfer is in a block, not yet final.
underpaid / partialopenFixed invoice: confirmed total below amount minus tolerance.
below_minimumopenOpen invoice: confirmed total below min_amount.
paidpaidFully paid (overpayment shows in overpaid_amount).
expiredclosedNot paid in time.
cancelledclosedCancelled by you.
late_paymentclosedFunds arrived after expiry or cancellation.
withdrawn / sweptclosedFunds 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:

  1. Get a pk_live_ key with /api_key on the mainnet deployment (during early access an admin may issue it). The mainnet host is provided together with your live key.
  2. Connect your mainnet account xPub there. Never reuse a test wallet for real money.
  3. Point your integration at the mainnet host with the live key, and set your webhook URL and secret again there (or a new secret).
  4. 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.

Coming soon

This section is not available yet.