--- title: "POST /v2/migration/prepare" method: POST path: "/v2/migration/prepare" tags: ["Migration"] --- # POST /v2/migration/prepare `POST /v2/migration/prepare` Prepare ordered signable transactions that migrate every asset from `from` to `to`. ## Request body - MigrationPrepareRequest - `currency` string — fiat currency for the preview values - `from` string, address, required — legacy source wallet to drain - `gas_jetton_master` string, address — Master address of jetton that should be used to cover transactions fees. Must be supported by /v2/gasless/config and held by the source wallet. - `gas_payer` 'self' | 'battery' | 'gasless' — Who pays the gas: - `self` — the source wallet pays, as usual - `battery` — asset transfers are sponsored by the Tonkeeper Battery - `gasless` — source wallet pays with jetton, in this case `gas_jetton_master` is required too (only from this list: `/v2/gasless/config`) - `public_key` string — hex-encoded ed25519 public key of the source wallet. If `from` wallet is uninitialized, then public_key is used to infer wallet code - `to` string, address, required — destination wallet TON address ## Response `200` ordered transactions to sign and broadcast - MigrationPrepareResponse - `from` string, address, required - `to` string, address, required - `transactions` MigrationTransaction[], required — ordered; sign and broadcast in array order, one entry per external message - `boc` string, required — base64 BOC of the unsigned wallet body. The body type is determined by (wallet_version, sponsored): for v3/v4 it is always the external body — sign its hash, prepend the signature, wrap in an external message; for w5 with sponsored=false it is the external body with the signature appended as the trailing 512 bits; for w5 with sponsored=true it is the internal_signed body — sign and wrap it for /v2/gasless/send as in the gasless flow. - `commission` string — gasless only; the relay commission in indivisible gas-jetton units, embedded in the boc as a jetton transfer to the relay. Exact for the first transaction; an estimate for later ones (re-running prepare refreshes it). - `emulation` MessageConsequences, required — Result of emulating a wallet message on the current blockchain state: describes the expected on-chain consequences (trace, high-level AccountEvent, risk) for the signing wallet. For UI display only. - `event` AccountEvent, required — High-level view over a transaction trace caused by a single inbound message. TonAPI analyses the trace, detects known patterns and groups low-level transactions into user-facing actions (Jetton transfer, NFT purchase, etc.). Actions are a best-effort UI abstraction and may change; do not rely on them for protocol-critical logic. - `account` AccountAddress, required - `address` string, maybe-address, required - `icon` string - `is_scam` boolean, required — Is this account was marked as part of scammers activity - `is_wallet` boolean, required - `name` string — Display name. Data collected from different sources like moderation lists, dns, collections names and over. - `actions` Action[], required - `AddExtension` AddExtensionAction - `extension` string, address, required - `wallet` AccountAddress, required - … - `AuctionBid` AuctionBidAction - `amount` Price, required - … - `auction` AccountAddress, required - … - `auction_type` 'DNS.ton' | 'DNS.tg' | 'NUMBER.tg' | 'getgems', required - `bidder` AccountAddress, required - … - `nft` NftItem - … - `BuyXTR` BuyXTRAction - `amount` string, required - `recipient` AccountAddress, required - … - `ContractDeploy` ContractDeployAction - `address` string, address, required - `interfaces` string[], required - `DepositStake` DepositStakeAction — validator's participation in elections - `amount` integer, required - `implementation` 'whales' | 'tf' | 'liquidTF' | 'ffvault', required - `pool` AccountAddress, required - … - `stake_meta` Price - … - `staker` AccountAddress, required - … - `DepositTokenStake` DepositTokenStakeAction - `protocol` Protocol, required - … - `stake_meta` Price - … - `staker` AccountAddress, required - … - `DepositXTR` DepositXTRAction - `amount` string, required - `recipient` AccountAddress, required - … - `DomainRenew` DomainRenewAction - `contract_address` string, address, required - `domain` string, required - `renewer` AccountAddress, required - … - `ElectionsDepositStake` ElectionsDepositStakeAction - `amount` integer, required - `staker` AccountAddress, required - … - `ElectionsRecoverStake` ElectionsRecoverStakeAction - `amount` integer, required - `staker` AccountAddress, required - … - `ExtraCurrencyTransfer` ExtraCurrencyTransferAction - `amount` string, required — amount in quanta of tokens - `comment` string - `currency` EcPreview, required - … - `encrypted_comment` EncryptedComment - … - `recipient` AccountAddress, required - … - `sender` AccountAddress, required - … - `FlawedJettonTransfer` FlawedJettonTransferAction - `comment` string - `encrypted_comment` EncryptedComment - … - `jetton` JettonPreview, required - … - `received_amount` string, required — actually received amount in quanta of tokens - `recipient` AccountAddress - … - `recipients_wallet` string, address, required - `refund` Refund - … - `sender` AccountAddress - … - `senders_wallet` string, address, required - `sent_amount` string, required — sent amount in quanta of tokens - `GasRelay` GasRelayAction - `amount` integer, required - `relayer` AccountAddress, required - … - `target` AccountAddress, required - … - `JettonBurn` JettonBurnAction - `amount` string, required — amount in quanta of tokens - `jetton` JettonPreview, required - … - `sender` AccountAddress, required - … - `senders_wallet` string, address, required - `JettonMint` JettonMintAction - `amount` string, required — amount in quanta of tokens - `jetton` JettonPreview, required - … - `recipient` AccountAddress, required - … - `recipients_wallet` string, address, required - `JettonSwap` JettonSwapAction - `amount_in` string, required - `amount_out` string, required - `dex` string, required - `gram_in` integer - `gram_out` integer - `jetton_master_in` JettonPreview - … - `jetton_master_out` JettonPreview - … - `router` AccountAddress, required - … - `ton_in` integer — this field will gone after Sept. 2026, use gram_in instead - `ton_out` integer — this field will gone after Sept. 2026, use gram_out instead - `user_wallet` AccountAddress, required - … - `JettonTransfer` JettonTransferAction - `amount` string, required — amount in quanta of tokens - `comment` string - `encrypted_comment` EncryptedComment - … - `jetton` JettonPreview, required - … - `recipient` AccountAddress - … - `recipients_wallet` string, address, required - `refund` Refund - … - `sender` AccountAddress - … - `senders_wallet` string, address, required - `LiquidityDeposit` LiquidityDepositAction - `from` AccountAddress, required - … - `protocol` Protocol, required - … - `tokens` VaultDepositInfo[], required - … - `NftItemTransfer` NftItemTransferAction - `comment` string - `encrypted_comment` EncryptedComment - … - `nft` string, maybe-address, required - `payload` string — raw hex encoded payload - `recipient` AccountAddress - … - `refund` Refund - … - `sender` AccountAddress - … - `NftPurchase` NftPurchaseAction - `amount` Price, required - … - `auction_type` 'DNS.ton' | 'DNS.tg' | 'NUMBER.tg' | 'getgems', required - `buyer` AccountAddress, required - … - `nft` NftItem, required - … - `seller` AccountAddress, required - … - `OracleRequest` OracleRequestAction - `price_feeds` OraclePriceFeed[], required - … - `requester` AccountAddress, required - … - `response_to` AccountAddress, required - … - `Purchase` PurchaseAction - `amount` Price, required - … - `destination` AccountAddress, required - … - `invoice_id` string, required - `metadata` Metadata, required - … - `source` AccountAddress, required - … - `RemoveExtension` RemoveExtensionAction - `extension` string, address, required - `wallet` AccountAddress, required - … - `SetSignatureAllowedAction` SetSignatureAllowedAction - `allowed` boolean, required - `wallet` AccountAddress, required - … - `SmartContractExec` SmartContractAction - `contract` AccountAddress, required - … - `executor` AccountAddress, required - … - `gram_attached` integer, required — amount in nanograms - `operation` string, required - `payload` string - `refund` Refund - … - `ton_attached` integer — amount in nanograms - `Subscribe` SubscriptionAction - `admin` AccountAddress, required - … - `amount` integer - `beneficiary` AccountAddress, required - … - `initial` boolean, required - `price` Price, required - … - `subscriber` AccountAddress, required - … - `subscription` string, address, required - `TonTransfer` TonTransferAction - `amount` integer, required — amount in nanograms - `comment` string - `encrypted_comment` EncryptedComment - … - `recipient` AccountAddress, required - … - `refund` Refund - … - `sender` AccountAddress, required - … - `UnSubscribe` UnSubscriptionAction - `admin` AccountAddress, required - … - `beneficiary` AccountAddress, required - … - `subscriber` AccountAddress, required - … - `subscription` string, address, required - `WithdrawStake` WithdrawStakeAction — validator's participation in elections - `amount` integer, required - `implementation` 'whales' | 'tf' | 'liquidTF' | 'ffvault', required - `pool` AccountAddress, required - … - `staker` AccountAddress, required - … - `WithdrawStakeRequest` WithdrawStakeRequestAction — validator's participation in elections - `amount` integer - `implementation` 'whales' | 'tf' | 'liquidTF' | 'ffvault', required - `pool` AccountAddress, required - … - `stake_meta` Price - … - `staker` AccountAddress, required - … - `WithdrawTokenStakeRequest` WithdrawTokenStakeRequestAction - `protocol` Protocol, required - … - `stake_meta` Price - … - `staker` AccountAddress, required - … - `WithdrawXTR` WithdrawXTRAction - `amount` string, required - `user` AccountAddress, required - … - `base_transactions` string[], required - `simple_preview` ActionSimplePreview, required — shortly describes what this action is about. - `accounts` AccountAddress[], required - … - `action_image` string — a link to an image for this particular action. - `description` string, required - `fiat_value` string — the value of this action expressed in the requested fiat currency. - `name` string, required - `value` string - `value_image` string — a link to an image that depicts this action's asset. - `status` 'ok' | 'failed', required - `type` 'TonTransfer' | 'ExtraCurrencyTransfer' | 'ContractDeploy' | 'JettonTransfer' | 'FlawedJettonTransfer' | 'JettonBurn' | 'JettonMint' | 'NftItemTransfer' | 'Subscribe' | 'UnSubscribe' | 'AuctionBid' | 'NftPurchase' | 'DepositStake' | 'WithdrawStake' | 'WithdrawStakeRequest' | 'ElectionsDepositStake' | 'ElectionsRecoverStake' | 'JettonSwap' | 'SmartContractExec' | 'DomainRenew' | 'Purchase' | 'AddExtension' | 'RemoveExtension' | 'SetSignatureAllowedAction' | 'GasRelay' | 'DepositTokenStake' | 'WithdrawTokenStakeRequest' | 'LiquidityDeposit' | 'OracleRequest' | 'BuyXTR' | 'DepositXTR' | 'WithdrawXTR' | 'Unknown', required - `event_id` string, required - `ext_msg_hash` string — Normalized hash of the root external inbound message (hex). - `extra` integer, required — Net Gram change for this account not explained by actions, in nanograms: extra = final_balance - initial_balance - sum(explicit Gram changes from actions). extra < 0 - implicit fee, extra > 0 - refund. For UI display only - `in_progress` boolean, required — Event trace is not finished yet. Transactions still happening. - `is_scam` boolean, required — scam - `lt` integer, required - `progress` number, float, required — Event completion ratio in [0,1] - `timestamp` integer, required - `risk` Risk, required — Conservative upper bound on assets this wallet may lose if the emulated message is sent and the counterparty behaves maliciously. Values may exceed current balances (e.g. already-authorized future receipts). For UI display only. - `gram` integer, required — Maximum Gram amount that may leave the wallet in the worst case, in nanogram. - `jettons` JettonQuantity[], required — Jetton positions that may be debited from the wallet in the worst case. - `jetton` JettonPreview, required - `address` string, address, required - `custom_payload_api_uri` string - `decimals` integer, required - `description` string - `image` string, required - `name` string, required - `scaled_ui` ScaledUI - … - `score` integer, required - `symbol` string, required - `verification` 'whitelist' | 'graylist' | 'blacklist' | 'none', required - `quantity` string, required - `wallet_address` AccountAddress, required - `address` string, maybe-address, required - `icon` string - `is_scam` boolean, required — Is this account was marked as part of scammers activity - `is_wallet` boolean, required - `name` string — Display name. Data collected from different sources like moderation lists, dns, collections names and over. - `nfts` NftItem[], required — NFT items that may be transferred out of the wallet in the worst case. - `address` string, address, required - `approved_by` string[], required - `code_hash` string — Hash of the NFT item account code cell (hex) - `collection` object - `address` string, address, required - `description` string, required - `name` string, required - `data_hash` string — Hash of the NFT item account data cell (hex) - `dns` string - `include_cnft` boolean - `index` integer, required - `metadata` object, required - `owner` AccountAddress - `address` string, maybe-address, required - `icon` string - `is_scam` boolean, required — Is this account was marked as part of scammers activity - `is_wallet` boolean, required - `name` string — Display name. Data collected from different sources like moderation lists, dns, collections names and over. - `previews` ImagePreview[] - `resolution` string, required - `url` string, required - `sale` Sale - `address` string, address, required - `market` AccountAddress, required - … - `owner` AccountAddress - … - `price` Price, required - … - `trust` 'whitelist' | 'graylist' | 'blacklist' | 'none', required - `verified` boolean, required — Collection master contract confirmed that this item is part of collection - `ton` integer — this field will gone after Sept. 2026, use gram instead - `total_equivalent` number, float — Estimated equivalent of all assets at risk (Gram, jettons, NFTs) in the selected currency from currencyQuery (e.g. USD). Approximate, best-effort UI value. - `transfer_all_remaining_balance` boolean, required — True if the message semantics allow sweeping all current and future remaining Gram balance of the wallet (e.g. “send all” / drain patterns). - `trace` Trace, required - `children` Trace[] - `emulated` boolean - `interfaces` string[], required - `transaction` Transaction, required - `aborted` boolean, required - `account` AccountAddress, required - `address` string, maybe-address, required - `icon` string - `is_scam` boolean, required — Is this account was marked as part of scammers activity - `is_wallet` boolean, required - `name` string — Display name. Data collected from different sources like moderation lists, dns, collections names and over. - `action_phase` ActionPhase - `fwd_fees` integer, required - `result_code` integer, required - `result_code_description` string - `skipped_actions` integer, required - `success` boolean, required - `total_actions` integer, required - `total_fees` integer, required - `block` string, required - `bounce_phase` 'TrPhaseBounceNegfunds' | 'TrPhaseBounceNofunds' | 'TrPhaseBounceOk' - `compute_phase` ComputePhase - `exit_code` integer - `exit_code_description` string - `gas_fees` integer - `gas_used` integer - `skip_reason` 'cskip_no_state' | 'cskip_bad_state' | 'cskip_no_gas' | 'cskip_suspended' - `skipped` boolean, required - `success` boolean - `vm_steps` integer - `credit_phase` CreditPhase - `credit` integer, required - `fees_collected` integer, required - `destroyed` boolean, required - `end_balance` integer, required - `end_status` 'nonexist' | 'uninit' | 'active' | 'frozen', required - `hash` string, required - `in_msg` Message - `bounce` boolean, required - `bounced` boolean, required - `created_at` integer, required - `created_lt` integer, required - `decoded_body` unknown - `decoded_op_name` string - `destination` AccountAddress - … - `fwd_fee` integer, required - `hash` string, required - `ihr_disabled` boolean, required - `ihr_fee` integer, required - `import_fee` integer, required - `init` StateInit - … - `msg_type` 'int_msg' | 'ext_in_msg' | 'ext_out_msg', required - `op_code` string - `raw_body` string, cell — hex-encoded BoC with raw message body - `source` AccountAddress - … - `value` integer, required - `value_extra` ExtraCurrency[] - … - `lt` integer, required - `orig_status` 'nonexist' | 'uninit' | 'active' | 'frozen', required - `out_msgs` Message[], required - `bounce` boolean, required - `bounced` boolean, required - `created_at` integer, required - `created_lt` integer, required - `decoded_body` unknown - `decoded_op_name` string - `destination` AccountAddress - … - `fwd_fee` integer, required - `hash` string, required - `ihr_disabled` boolean, required - `ihr_fee` integer, required - `import_fee` integer, required - `init` StateInit - … - `msg_type` 'int_msg' | 'ext_in_msg' | 'ext_out_msg', required - `op_code` string - `raw_body` string, cell — hex-encoded BoC with raw message body - `source` AccountAddress - … - `value` integer, required - `value_extra` ExtraCurrency[] - … - `prev_trans_hash` string - `prev_trans_lt` integer - `raw` string, cell, required — hex encoded boc with raw transaction - `state_update_new` string, required - `state_update_old` string, required - `storage_phase` StoragePhase - `fees_collected` integer, required - `fees_due` integer - `status_change` 'acst_unchanged' | 'acst_frozen' | 'acst_deleted', required - `success` boolean, required - `total_fees` integer, required - `transaction_type` 'TransOrd' | 'TransTickTock' | 'TransSplitPrepare' | 'TransSplitInstall' | 'TransMergePrepare' | 'TransMergeInstall' | 'TransStorage', required - `utime` integer, required - `gas_spent` integer, required — TON burned as network fees by this transaction, in nanotons — the sum over every transaction in `emulation.trace`. For a transfer batch this is only part of the gas attached to its messages: the transfers name the destination wallet as response_destination, so the unburned remainder arrives there instead of returning to the source. For the final balance sweep it is the fee deducted from the swept amount. When `sponsored` is true these fees are covered by the relay, which charges `commission` instead. - `messages` MigrationOutMessage[], required — ordered raw internal messages carried by this transaction — the cells the wallet resends. These are what populate the payload/actions. - `boc` string, cell-base64, required — base64 BOC of the internal message cell the wallet resends - `mode` integer, required — send-mode byte (e.g. 3 for a transfer, 128 for the final balance sweep) - `seqno` integer, required — wallet seqno baked into the unsigned body - `sponsored` boolean — true — the Battery relay pays gas for this transaction; submit it via /v2/gasless/send. false — self-paid; sign and broadcast via /v2/blockchain/message as usual (e.g. the final TON sweep). - `state_init` string, cell-base64 — base64 BOC of the wallet StateInit (code + data). Present only on the first transaction when the source wallet is not yet initialized - `wallet_version` string, required — source wallet version (informational) ## Other responses - `409` — the migration is prepared but not executable as-is — see `error_code` - `default` — Some error during request processing --- [API](https://skmtc.dev/tonapi/apis/rest-api-to-ton-blockchain-explorer.md) · [All operations](https://skmtc.dev/tonapi/apis/rest-api-to-ton-blockchain-explorer/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tonapi/rest-api-to-ton-blockchain-explorer/revisions/fc4add7a71a0/schema)