Jetton Airdrop Technical and Commercial Terms (T&C Terms)

These T&C Terms shall be read in conjunction with the Airdrop Terms of Use

Service enables a mass token distribution model where the recipient (Recipient) pays a fixed fee in TONs and receives jettons (Jettons). The distribution is carried out to a fixed list of Recipients. In the following, we will refer to the Jetton distribution process as an Airdrop.

How it works

1. The Airdrop organizer (Airdrop admin) prepares a file with a fixed list of Recipients (Airdrop file)
2. The Airdrop admin creates a new project in Ton Console and fills in the Airdrop data
3. The Airdrop admin connects their wallet via TON Connect (in Ton Console) and deploys the Airdrop smart contracts
4. The Airdrop admin on their hosting raises a dApp that allows the Recipient to connect their wallet and receive Jettons by paying a fee

Airdrop file preparation

File format requirements

1. CSV format with a comma delimiter
2. Contain a header in the format: recipient,amount
3. Jetton amount in minimal indivisible units (example: 1000000 for 1 USDT where decimals=6). Decimals can be found in the Jetton metadata (opens in a new tab). The value must be positive, and decimal points are not allowed.
4. Recipient's wallet addresses in user-friendly or raw format (Address formats (opens in a new tab)) with no duplicates
5. File size up to 10,000,000 records

Airdrop file example

recipient,amount
0:d0ef5351eb05503c10a447543113b315e772d147c51aaa81aa308b5cae99e07e,2567953998
0:199b41bcda2472b057d72f80e2e8ba5e15dcb776e68c9eeea393dad668248068,3127429615
0:aa1e7af003374652e13f705b8c7010b3cf8708f5f98f43c999b8ec4e2c0e0cdf,562536354

Airdrop file hash verification

After downloading the Airdrop file, verify the sha256 hash of your original file and the hash in the Ton Console.

Airdrop admin

When creating a new Airdrop in Ton Console, you will need to connect your wallet via Ton Connect. The address of this wallet will be recorded as the Airdrop admin`s address for the contracts.

Jetton for distribution

To create an Airdrop you will need to specify the address of the Jetton master contract (Jetton Architecture (opens in a new tab)) in a user-friendly or raw format. For example: Notcoin address is EQAvlWFDxGF2lXm67y4yzC17wYKD9A0guwPkMs1gOsM__NOT (Tonviewer (opens in a new tab)).

If you have created a Jetton not based on the standard smart contract or are sending a Jetton minted by someone else, be cautious. Custom smart contract logic may disrupt the distribution process (e.g. the transfer fees may be significantly higher). Use only trusted Jettons.

Claim Fee

This is a key Airdrop setting. It determines how much the Recipient will pay for the request of Jettons via a claim message (Claim) in addition to any other fees paid by the Recipient.

When a Recipient signs a Claim message via Ton Connect, they pay a Claim fee (Claim fee) in TON for the distribution contract to accept the message. In addition to the Claim fee, the Recipient also pays a blockchain fee for sending this message.

Example:

claim_fee = 0.15 TON
blockchain_fee(forward_fee + gas_fee + ...) = ~0.0076 TON
recipient_pays = claim_fee + blockchain_fee = 0.15 + ~0.0076 = ~0,1576 TON

Fee Sharing

The Claim fee is used to cover blockchain fees incurred during the claim process, and the remainder is sent to special distribution smart contracts.

Example of a Claim operation in the testnet: Tonviewer (opens in a new tab).

In the given example, the distributor contract will receive excess (Excess) = 0.1147384 TON. distributor_balance_change is equal to +0.112809142 TON and is slightly less than the Excess due to blockchain fees for the payment of which the Airdrop admin is responsible. The estimate amount could be seen in the Value flow tab of the given Claim operation example.

The amount of TONs received by the distributor contract is divided in the following proportion:

royalty_receiver_share = royalty_coefficient * excess

admin_share = excess - royalty_receiver_share - blockchain_fee,

where the royalty receiver share is the fees of Scalable Data Solutions Inc and admin share is the fees of the Airdrop admin.

The blockchain fees shall be paid are charged both at the time of receiving Excess and upon executing any subsequent transactions involving distribution contracts.

dApp for Recipients to claim Jettons

Airdrop admin should deploy a dApp on their side (website, landing page) where the Recipient can connect their wallet via Ton Connect and sign a Claim.

Reference application

You can find the reference application here (opens in a new tab). You can find the source code here: GitHub (opens in a new tab).

To configure the reference application, use the following URL format:

https://tonkeeper.github.io/airdrop-reference-dapp/?airdropId=<ID>

• Replace <ID> with the Airdrop ID from Ton Console.

API for dApp interaction

Our backend has a method for interacting with the Claim dApp. Through it, the dApp receives the necessary data for the Recipient.

When you click the Enable claim button in the Ton Console dashboard, you grant the Recipients access to this method; when you click Disable claim, you close it.

GET {host}/v1/airdrop/claim/{address}?id={airdrop_id}

Returns (or error):

{
  "claim_message": {
    "mode": 3,
    "address": "EQBdywJayJlH1PQDDNr1cX8_wOIFzxLpptbA3m5VxXPGR7wz",
    "state_init": "base64string",
    "payload": "base64string",
    "amount": "150000000"
  },
  "jetton_amount": "58701809",
  "jetton": "EQAZG3WSEZCd0qj-4QtCcGtMKDH9OoGD4godKRe65ceQj6Hf"
}

Where request parameters:

1. host - address of Claim API: https://mainnet-airdrop.tonapi.io
2. address - Recipient address in raw form. Example: 0:585eacf04d4df6c8a2e4f1ed1008e1ac3e36e14cbc37cddaf1f329a50ad43853
3. airdrop_id - unique Airdrop ID from the Airdrop dashboard in Ton Console. Example: fa541433-ceef-4286-a76c-1be7c6198632

The dApp should retrieve the address from the wallet connected through Ton Connect.

Where response parameters:

claim_message - contains the data necessary for forming a message via Ton Connect

1. mode - message sending mode (Ton Connect always sends with mode 3)
2. address - destination address of the message in user-friendly format containing the bounce flag
3. state_init - serialized state init cell in base64 format
4. payload - serialized body cell in base64 format
5. amount - amount of TONs attached to the message (Claim Fee)

jetton_amount - Jetton amount in minimal indivisible units (from the Airdrop file) jetton - address of the Jetton master contract

Response error codes

Error format

{
  "code": 2,
  "message": "locked"
}

423 (Locked)

• {"code":1, "message":"not processed yet"} - the Airdrop data has not yet been processed. Wait for processing. The error CANNOT appear if the workflow in the Ton Console is followed.
• {"code":2, "message":"locked"} - the error occurs if the Claim is set to Disabled in the Ton Console.
• {"code":3, "message":"already claimed"} - the Recipient has already claimed previously.
• {"code":4, "message":"blockchain overload"} - the blockchain is overloaded. Claim temporarily suspended. Try claiming later.

400 (Bad request)

• invalid id: <err> - an incorrect Airdrop ID was provided.
• invalid recipient address: <err> - an incorrect Recipient address was provided.

404 (Not found)

• "entity not found" - the specified Recipient address or Airdrop ID was not found.

500 (Internal error)

• "internal error" - some internal server error.

Blockchain load limitation

To smooth blockchain load and ensure stable operation, method /v1/airdrop/claim has specific rate limits. If the blockchain is currently under high load (many messages in the shard queue), method /v1/airdrop/claim is blocked ({"code":4, "message":"blockchain overload"} 423 error) for some Recipients until the load decreases. This limitation is technically justified, and removing it won't improve the Claim situation for Recipients, as their Claims will still be delayed.

Example call Claim function from dApp

import { tonConnectUI } from '@tonconnect/ui';
 
function claimJetton(claimId, userAddress) {
    const claimUrl = `https://mainnet-airdrop.tonapi.io/v1/airdrop/claim/${userAddress}?id=${airdropId}`;
    fetch(claimUrl)
        .then((response) => response.json())
        .then(({ claimMessage }) => {
            tonConnectUI.sendTransaction({
                validUntil: Math.floor(Date.now() / 1000) + 300, // 5 minutes
                messages: [
                    {
                        address: claimMessage.address,
                        amount: claimMessage.amount,
                        payload: claimMessage.payload,
                        stateInit: claimMessage.state_init,
                    },
                ],
            });
        })
        .catch((error) => console.error('Error:', error));
}
 
claimJetton('<ID of Airdrop from tonconsole>', '<User address from tonConnectUI>');

Test Сlaim button

Distribution completion procedure

Before withdrawing profit and remaining Jettons, you need to properly complete the distribution to prevent Recipients from attempting to Claim after the distribution has ended.

First, you need to click the Disable claim button to deactivate the API Claim endpoint through the dApp. Second, click the Complete airdrop button to send special messages that lock the distribution contracts. After this, you can safely withdraw the remaining Jettons and accumulated TONs from the distribution contracts to the Airdrop admin`s address.