BNB Beacon Chain Token Recovery Tool: Self-Service User Guide

TL;DR

• From 1 July 2026, the BNB Beacon Chain Token Recovery Tool will move to Phase 3 and become a self-service process.
• Users can recover eligible BEP2 and BEP8 tokens to BNB Smart Chain using the Token Recover Self-Service Tool that runs locally on their computer.
• You will need Node.js 24+, a Beacon Chain-compatible wallet, a receiving BSC wallet, and a small amount of BNB for gas.

As part of the BNB Beacon Chain Token Recovery Tool Sunset Plan, Phase 3 will begin on 1 July 2026. This means that the current BNB Chain's hosted token recovery tool will be discontinued.

Users who still need to recover BEP2 or BEP8 tokens from the BNB Beacon Chain to BNB Chain (BSC) must now use the Token Recover Self-Service Tool which runs locally on your computer, allowing you to complete the recovery without relying on a third-party custodial service.

This guide covers everything you need to complete the recovery successfully.

What You Need Before Starting

Before starting, prepare the following:

1. Node.js version 24.0.0 or later installed on your computer.
2. A package manager: npm, yarn, pnpm, or bun.
3. Your BNB Beacon Chain address (starts with "bnb1..."). This is the address holding the tokens you want to recover.
4. A Beacon Chain-compatible browser wallet with access to that address
5. A BNB Smart Chain (BSC) wallet address to receive the recovered tokens
6. A small amount of BNB in that BSC wallet to pay for gas

When you have these, you can begin installing and running the tool locally.

Install and Run the Tool Locally

Step 1: Clone the repository

Open your terminal and run:

git clone https://github.com/bnb-chain/token-recover-self-service-tools.git cd token-recover-self-service-tools

Step 2: Install dependencies

npm install

Step 3: Configure the API endpoint (Optional)

By default, the tool points to BNB Chain Mainnet. If you want to test on Testnet first, copy the example environment file and edit it:

cp .env.example .env.local

Then open .env.local and set:

NEXT_PUBLIC_APPROVAL_API=https://testnet-token-recover-api.bnbchain.org

The BSC explorer links in the UI will automatically switch to testnet.bscscan.com when this is set.

Step 4: Start the application

npm run dev

Step 5: Open in your browser

Open http://localhost:3000

You will see a four-step guided recovery flow. Follow the steps exactly.

How to Recover your Assets

Step 1: Get Recoverable Tokens

Enter your BNB Beacon Chain address (the "bnb1..." address) in the input field and click to fetch.

The tool will display a list of all tokens eligible for recovery on that address. Identify the token you want to recover and note its symbol.

Note: If no tokens appear, the address may have no recoverable balance or may already have been processed.

Step 2: Generate and Sign Message in your Beacon Chain Wallet

Enter:

• Token Symbol: The token symbol shown in Step 1
• Amount: The amount you want to recover (e.g. 0.00001000). The tool automatically converts this to the correct onchain base units internally.
• To BSC Address: The BSC address that will receive the tokens. The receiving BSC address must belong to a wallet you control. You will need to use the same wallet in Step 4.
• Network: Beacon Chain Mainnet (or Testnet if testing)

Click Generate Sign Message, followed by Sign with Wallet.

Approve the signing request in your wallet. The tool receives back two values:

• signature: A long hex string starting with 0x
• publicKey: Your Beacon Chain public key

Security note: Only sign this message in a browser where you trust all installed extensions. Do not sign on shared computers or when multiple wallet extensions are active simultaneously. The tool does not broadcast anything at this stage and no transaction occurs here.

Note: If the signature returned by your wallet does not start with "0x", add the "0x" prefix manually before proceeding.

Step 3: Request Approval

With the signature and public key from Step 2 in hand, click Get Approval.

The approval server will validate the signed request and return:

• proofs: a list of Merkle proof hashes
• approval_signature:  the server's countersignature authorising the recovery

These values are automatically populated in the tool. You do not need to copy or store them manually, they carry through to Step 4 automatically.

Note: If approval fails, check that the token symbol and BSC address exactly match the information signed in Step 2.

Step 4: Build the Recover Payload and Submit on BSC Wallet

This is the final step. Click Build Recover Payload.

The tool assembles a complete payload containing:

• The token symbol (encoded as bytes32)
• The amount (encoded as a hex integer in base units)
• Your Beacon Chain owner signature and public key
• The server's approval signature
• The full Merkle proof array

Important: The tool generates this payload locally only. No transaction is broadcast automatically.

You must now call the recover function on the BNB Chain recovery contract yourself using your BSC wallet (the same address you specified as "To BSC Address" in Step 2).

Recovery contract address: 0x0000000000000000000000000000000000003000 (BscScan)

To complete the recovery:

1. Connect your BSC wallet to BSC Mainnet
2. Open the recovery contract on BscScan
3. Select Write Contract and connect your wallet
4. Call the recover function using the generated payload
5. Set the gas limit to at least 1,000,000
6. Confirm the transaction

Once confirmed onchain, the recovered tokens will be sent to your BSC wallet.

Note: Both the owner signature and the approval signature must start with "0x". If either is missing the prefix, add it before submitting.

Note that two separate wallets are required. The BSC address entered in Step 2 must match the wallet used in Step 4.

Testnet Practice Run

To test the recovery flow before using Mainnet:

1. Set NEXT_PUBLIC_APPROVAL_API=https://testnet-token-recover-api.bnbchain.org in your .env.local file.
2. Restart the dev server (npm run dev).
3. Use your Beacon Chain Testnet address and a BSC Testnet wallet.

The UI will automatically link to testnet.bscscan.com for transaction verification.

Troubleshooting 

No tokens shown in Step 1

Verify you have entered the correct Beacon Chain address. Ensure the address format begins with "bnb1". The address is case-sensitive.

Wallet does not respond in Step 2

Ensure your Beacon Chain-compatible wallet extension is active and unlocked in the same browser. Disable or remove other wallet extensions that may conflict.

Approval fails in Step 3

Check that the token symbol matches exactly (including hyphen and number suffix). Check that your BSC address is a valid 0x-prefixed EVM address.

Transaction reverts in Step 4

Confirm your gas limit is set to 1,000,000 or higher. Ensure your BSC wallet has sufficient BNB for gas. Confirm both signatures are 0x-prefixed.

Signature missing 0x prefix

Some wallet implementations omit the 0x prefix. Prepend "0x" to the signature string before using it in Step 3 or Step 4.

Security Reminders

• Only use the official GitHub repository.
• Do not use third-party mirrors or modified versions of the tool.
• Never share your private key or seed phrase.
• Use a trusted computer and browser.
• Report vulnerabilities through the repository’s Security Policy, not through a public GitHub issue.

Quick Reference

For the latest updates and known issues, refer to the GitHub repository.

If you face any issues with recovery, reach out for support via our Telegram Support Bot.