diff --git a/docs.json b/docs.json index 773688d4..505e6f90 100644 --- a/docs.json +++ b/docs.json @@ -44,6 +44,7 @@ "guides/first-smart-contract", "guides/from-ethereum", "guides/payment", + "guides/usdt", "guides/airdrop", "guides/debug", "guides/telegram", diff --git a/ecosystem/processing/overview.mdx b/ecosystem/processing/overview.mdx new file mode 100644 index 00000000..87045c87 --- /dev/null +++ b/ecosystem/processing/overview.mdx @@ -0,0 +1,7 @@ +--- +title: Processing +--- + +import { Stub } from '/snippets/stub.jsx'; + + diff --git a/guides/usdt.mdx b/guides/usdt.mdx index 666ca0d7..8f044e4d 100644 --- a/guides/usdt.mdx +++ b/guides/usdt.mdx @@ -1,7 +1,146 @@ --- -title: "USDT" +title: "USDT: send and receive" --- -import { Stub } from '/snippets/stub.jsx'; +import { Aside } from '/snippets/aside.jsx'; - +Tether USD (USDT) is a stablecoin that represents US dollars. Each USDT is designed to be worth \$1. On TON blockchain, USDT is represented as [Jetton tokens](/standard/tokens/jettons/overview). + +Like all jettons, USDT has a Jetton Master contract that identifies the token. + + + +You can view the official USDT Jetton Master contract on [TON Viewer](https://tonviewer.com/EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs). + +## How jettons work + +While toncoin is handled natively by TON blockchain, Jetton is built on top of it as a set of contracts. + +- _Jetton master_: The main [account](/foundations/addresses/overview) that contains metadata and tracks total supply. +- _Jetton wallets_: Each user has their own Jetton wallet account that holds their balance. + +When you "have USDT," you actually have a personal USDT Jetton wallet account associated with your regular TON wallet account. + +## How to find your USDT Jetton wallet address + +Your USDT Jetton wallet address is different from your main TON wallet address. To find it: + +### Using TON Viewer + +1. Go to [TON Viewer](https://tonviewer.com/). +1. Enter your TON wallet address. +1. Click on the "Tokens" tab. +1. Find "Tether USD" in the list. Beware of scams! +1. Clicking on USDT will show all operations with USDT on your wallet. +1. On the top of the page, you will see your individual USDT wallet address and the amount of USDT you have. + +![Locating Tether USD in Tokens list](/resources/images/tether.png) + +### Programmatically + +You can call the `get_wallet_address` method on the USDT Jetton Master account: + +```typescript +import { Address, beginCell } from "@ton/core"; +import { TonClient } from "@ton/ton"; + +const myWalletAddress = Address.parse('YOUR_TON_WALLET_ADDRESS'); + +const client = new TonClient({ + endpoint: 'https://toncenter.com/api/v2/jsonRPC', +}); + +const USDT_MASTER = Address.parse('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'); + +// Call get_wallet_address on the master contract +const result = await client.runMethod( + USDT_MASTER, + 'get_wallet_address', + [{ + type: 'slice', + cell: beginCell() + .storeAddress(myWalletAddress) + .endCell(), + }], +); + +const myUsdtWalletAddress = result.stack.readAddress(); +console.log('My USDT wallet:', myUsdtWalletAddress.toString()); +``` + +## How to send USDT + +Sending USDT requires you to interact with your personal USDT Jetton wallet. Here's how: + +### Prerequisites + +Before sending USDT, make sure you have: + +1. Some USDT balance in your wallet. +1. Some toncoin (approximately 0.1 TON) to pay for transaction fees. In practice, commission will be lower than 0.1 TON, excesses will be returned. +1. The recipient's TON wallet address. + +### Using a wallet app + +The easiest way to send USDT is through a [wallet app](/ecosystem/wallet-apps/overview). We'll use Tonkeeper for the example. + +1. Open your wallet app. +1. Go to your USDT balance. +1. Tap "Send" or "Transfer". +1. Enter the recipient's address. +1. Enter the amount of USDT to send. +1. Optionally add a comment/memo. +1. Confirm and sign the transaction. + +### Programmatic transfer + +If you're building an application, you need to send a special message to your Jetton wallet. To do this, you need to: + +- [Find your USDT jetton wallet address](/standard/tokens/jettons/how-to-find) +- [Create the correct transfer message](/standard/tokens/jettons/how-to-transfer) +- Attach sufficient TON for fees + + + +### Important notes about sending programmatically + +- _Amount format_: USDT uses 6 decimals. To send 1 USDT, use `1000000` (in elementary units). +- _Gas fees_: Always attach enough TON (\~0.1 TON) to cover fees. +- _Forward amount_: You should always set `forward_amount` to a positive number. This amount will be credited to the recipient's TON wallet along with the USDT. If you don't want to send any TONs along with USDT, set `forward_amount` to `1`, meaning 1 nanoton (0.000000001 TON). +- _Comments_: You can add a text comment that will be visible to the recipient. + +## How to receive USDT + +To receive USDT, share TON wallet address. However, programmatically processing incoming USDT payments is more complex than it appears. + +For businesses, exchanges, or other services that need to programmatically detect and process incoming USDT payments, refer to the [payment processing guide](/ecosystem/processing/overview). + +### Why is receiving complex? + +When someone sends you USDT: + +1. They send a message to **their** USDT jetton wallet. +1. Then their jetton wallet sends a message to **your** USDT jetton wallet. +1. Your jetton wallet may also send a notification message. + +This multi-step process requires: + +- Monitoring the correct jetton wallet address. +- Understanding the message chain. +- Parsing jetton transfer notifications. +- Handling edge cases (first-time receives, insufficient gas, etc.) + +## USDT in Testnet + +There is no USDT in Testnet. However, you can create your own test Jetton for development and testing purposes. Use [this web tool](https://minter.ton.org/?testnet=true#) or follow the [guide](/standard/tokens/jettons/how-to-mint) on how to do it programmatically. diff --git a/resources/images/tether.png b/resources/images/tether.png new file mode 100644 index 00000000..3a3cf3e0 Binary files /dev/null and b/resources/images/tether.png differ