# 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](tickers.md) for the list.

```bash
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.

```bash
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`:

```bash
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](api-reference.md).

## 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](verify-signature.md)).
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:

```bash
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

- [API reference](api-reference.md) for all parameters and responses.
- [Callbacks](callbacks.md) for the retry schedule and transports (`post=1`, `json=1`).
- [Fees and minimums](fees.md) to know what you will receive.