> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mpcvault.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TON

> Send GRAM and jettons, submit TON contract messages, and sign TON Connect proofs with MPCVault.

Examples use [API client signing](https://docs.mpcvault.com/api-reference/overview.md#preparation).

## Signing request types

| Payload | Use |
| - | - |
| [`tonSendNative`](https://docs.mpcvault.com/api-reference/rest/create-signing-request) | Transfer GRAM, TON's native asset. |
| [`tonSendToken`](https://docs.mpcvault.com/api-reference/rest/create-signing-request) | Transfer jettons. |
| [`tonSendCustom`](https://docs.mpcvault.com/api-reference/rest/create-signing-request) | Submit contract messages, including initialization data when needed. |
| [`tonMessage`](https://docs.mpcvault.com/api-reference/rest/create-signing-request) | Sign a TON Connect proof. |

To sign transactions you build yourself or messages you format yourself, use [raw signing](https://docs.mpcvault.com/api-reference/overview.md#raw-signing).

## Wallet

[Create a wallet](https://docs.mpcvault.com/api-reference/rest/create-wallet.md) with `networkType: "NETWORK_TYPE_TON"`. Fund it with [GRAM (formerly TON)](https://ton.org/media/) for the transfer and fees, plus the jetton balance for jetton transfers. MPCVault includes wallet deployment in the first outgoing transaction when needed.

## Send GRAM

This TON Mainnet example sends `1 GRAM`.

```bash theme={null}
curl -X POST https://api.mpcvault.com/v1/createSigningRequest \
  -H "Content-Type: application/json" \
  -H "x-mtoken: <API_TOKEN>" \
  -d '{
    "vaultUuid": "<VAULT_UUID>",
    "callbackClientSignerPublicKey": "<CLIENT_SIGNER_OPENSSH_PUBLIC_KEY>",
    "broadcastTx": true,
    "tonSendNative": {
      "from": "<TON_ADDRESS>",
      "to": "<RECIPIENT_TON_ADDRESS>",
      "value": "1000000000",
      "comment": "<RECIPIENT_COMMENT>"
    }
  }'
```

`value` is an integer string in [nanograms](https://docs.ton.org/api/v2/accounts/get-address-balance): `1 GRAM = 1,000,000,000 nanograms`. If the recipient requires a deposit memo, put it in `comment` (up to 50 Unicode characters). Omit `comment` when none is required. Transaction `notes` are separate and do not appear on-chain.

## Send USDT (Jetton)

Replace `tonSendNative` with this payload in the same request:

```json theme={null}
{
  "tonSendToken": {
    "from": "<TON_ADDRESS>",
    "to": "<RECIPIENT_TON_ADDRESS>",
    "mintAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
    "amount": "1000000",
    "comment": "<RECIPIENT_COMMENT>"
  }
}
```

This example sends `1 USDT` on TON Mainnet (six decimals). `mintAddress` is [Tether's TON Mainnet USDT jetton master](https://tether.to/en/supported-protocols/). `to` is the recipient's TON wallet address. GRAM pays transaction fees.

## Send contract messages

Build the contract message bodies, then replace `tonSendNative` with this payload:

```json theme={null}
{
  "tonSendCustom": {
    "from": "<TON_ADDRESS>",
    "payload": "<BASE64_UTF8_TRANSACTION_JSON>"
  }
}
```

The outer `payload` is standard base64 of the following UTF-8 JSON. Encode it using [Encode bytes](https://docs.mpcvault.com/api-reference/data-types.md#encode-bytes):

```json theme={null}
{
  "from": "<TON_ADDRESS>",
  "network": "-239",
  "messages": [
    {
      "address": "<CONTRACT_TON_ADDRESS>",
      "amount": "50000000",
      "payload": "<BASE64_MESSAGE_BODY_BOC>"
    }
  ]
}
```

Each `messages[].amount` is the native GRAM amount attached to that message, as an integer string in nanograms. Each `messages[].payload` is a base64 Bag of Cells (BOC) containing the contract message body. Optional `messages[].state_init` is a base64 BOC of the contract's initialization data. The outer base64-encoded JSON contains these inner base64 BOC strings.

## Sign and track

[Sign the request](https://docs.mpcvault.com/api-reference/overview.md#sign-the-request). The returned `txHash` is the hash of the signed external message, **not the on-chain transaction hash**. Track its delivery through the message trace below.

Use TON Center's [trace lookup by message hash](https://docs.ton.org/api/v3/actions-and-traces/get-traces) on Mainnet:

```bash theme={null}
curl --get "https://toncenter.com/api/v3/traces" \
  -H "X-API-Key: <TONCENTER_API_KEY>" \
  --data-urlencode "msg_hash=<TX_HASH>" \
  --data-urlencode "include_actions=true"
```

* Find the sending wallet's transaction in `traces[].transactions`, then check `description.aborted: false`, `description.compute_ph.success: true` and `description.action.success: true`. Follow the intended messages through the [complete trace](https://docs.ton.org/foundations/traces); wallet execution alone does not establish downstream success.
* For GRAM, verify delivery to the expected recipient and amount without a bounced payment. For jettons, verify the expected jetton master, recipient and raw amount through the recipient's jetton-wallet transaction. For custom calls, check the contract's expected result.
* An empty or incomplete trace can reflect indexing delay. Keep tracking the same external-message hash until the intended downstream result is known.

## Sign a TON Connect proof

Use this payload with the shared [message-signing flow](https://docs.mpcvault.com/api-reference/overview.md#sign-a-message):

```json theme={null}
{
  "tonMessage": {
    "from": "<TON_ADDRESS>",
    "type": "TYPE_DEFAULT",
    "content": "<BASE64_UTF8_TON_PROOF_JSON>"
  }
}
```

`content` is standard base64 of this UTF-8 `ton_proof` envelope. Encode it using [Encode bytes](https://docs.mpcvault.com/api-reference/data-types.md#encode-bytes):

```json theme={null}
{
  "address": "<TON_ADDRESS>",
  "network": "-239",
  "proof": {
    "timestamp": 1792713600,
    "domain": { "lengthBytes": 11, "value": "example.com" },
    "payload": "<SERVER_CHALLENGE>"
  }
}
```

Use the signing wallet's address, the current Unix timestamp in seconds, your application's domain and its UTF-8 byte length, and a verifier-issued, single-use challenge. Verify the proof using [TON's verification flow](https://docs.ton.org/applications/ton-connect/how-to/ton-proof).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.