Menu

Quick start

This walk-through creates a deposit address, shows it to a payer, and handles the callbacks. Replace the payout address and callback URL with your own. Use URL encoding for every query value; curl -G --data-urlencode does this for you.

1. Check the ticker and its minimum

Token tickers contain a slash: trc20/usdt. See Tickers and networks for the list.

Shell
curl "https://api.suawave.com/trc20/usdt/info/"
JSON
{
  "status": "success",
  "coin": "USDT",
  "ticker": "trc20/usdt",
  "minimum_transaction_coin": "10.000000"
}

2. Create the deposit address

Generate an unguessable nonce for the order, store it on your server, and put it in the callback URL together with your own order reference. Add pending=1 if you also want a callback when the deposit is first detected.

Shell
curl -G "https://api.suawave.com/trc20/usdt/create/" \
  --data-urlencode "address=TXyzPayoutAddressExample0000000000000" \
  --data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c" \
  --data-urlencode "pending=1"
JSON
{
  "status": "success",
  "address_in": "TDepositAddressExample0000000000",
  "address_out": "TXyzPayoutAddressExample0000000000000",
  "callback_url": "https://shop.example/hook?order=1001&nonce=7f3a9c",
  "minimum_transaction_coin": "10.000000"
}

Note

Calling it again with the same ticker and callback returns the same address_in. Use HTTPS for the callback URL; private and loopback destinations are refused.

3. Show the address to the payer

Display address_in, the asset, the network and minimum_transaction_coin. A deposit below the minimum is not forwarded and not paid out.

To render a QR code, call GET /{ticker}/qrcode/ with the address_in:

Shell
curl -G "https://api.suawave.com/trc20/usdt/qrcode/" \
  --data-urlencode "address=TDepositAddressExample0000000000" \
  --data-urlencode "value=25.5"

The response contains qr_code, a data:image/png;base64, URI you can use as an image source, and the exact payment_uri that is encoded. Wallet support for amounts differs by network; see the API reference.

4. Receive the callbacks

When a deposit is detected your callback URL receives a pending callback (only with pending=1), and after the deposit was forwarded a confirmed callback. By default callbacks are GET requests with the fields in the query string. A confirmed callback looks like this, shown as JSON for readability (price is added when a fresh price is available):

JSON
{
  "uuid": "8c4e2a61-5b3d-47f9-a0e2-1d6c9b7f3e45",
  "address_in": "TDepositAddressExample0000000000",
  "address_out": "TXyzPayoutAddressExample0000000000000",
  "txid_in": "9f2c1a0e5b7d4c3a8e6f1b2d3c4a5e6f7a8b9c0d1e2f30415263748596a7b8c9",
  "coin": "trc20_usdt",
  "pending": "0",
  "txid_out": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
  "confirmations": "21",
  "value_coin": "100.000000",
  "value_forwarded_coin": "98.200000",
  "fee_coin": "1.800000"
}

In your handler:

  1. Verify the x-ca-signature header (Verify callback signatures).
  2. Compare the nonce and order query values with what you stored, and check address_in, coin and value_coin against the order.
  3. Save the uuid before doing anything else. If you have seen it, skip the work but still answer *ok*.
  4. Fulfill the order only on a confirmed callback (pending is "0").
  5. Answer HTTP 200 with the body *ok* within 30 seconds. Any other answer is retried.

5. Poll the logs as a fallback

If a callback did not arrive, read the history of the order:

Shell
curl -G "https://api.suawave.com/trc20/usdt/logs/" \
  --data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c"

Logs list each forwarded deposit with its forwarding transaction, fees and the last delivery attempts. Verified callbacks remain the source of truth for accepting a payment; logs are a polling fallback.

Next