Skip to main content
Crypto Readout

Crypto markets, protocols and policy

How to deposit and withdraw with Matic.js and confirm transfers

Polygon bridge deposit and withdrawal with Matic.js: initialize POSClient, approve and deposit ERC-20 tokens, then wait for a checkpoint and confirm the exit.

By Crypto Readout Editorial4 min read#95086a

How to deposit and withdraw with Matic.js and confirm transfers

Polygon bridge deposits and withdrawals with Matic.js use POSClient to move ERC-20 tokens from Ethereum to Polygon PoS and back, with transaction hashes and status checks confirming each stage. For a transfer outside your app, Polygon bridge gives you a way to move supported assets between Ethereum and Polygon PoS.

Run an ERC-20 deposit and withdrawal

Matic.js wraps the bridge contracts and builds the proof needed to release tokens on Ethereum after a Polygon withdrawal. You need Ethereum and Polygon RPC URLs, a signer with ETH and POL for transaction costs, and the mapped token address on each network.

  1. Install and initialize. In your Node.js or browser project, install Matic.js and one provider plugin: @maticnetwork/maticjs-ethers for ethers, or @maticnetwork/maticjs-web3 for web3. Import the plugin, call use(plugin), then initialize a POSClient with the network, version, and parent and child providers. The parent provider connects to Ethereum; the child connects to Polygon PoS. The signer must be able to sign transactions on the chain each call uses.
  2. Choose the token and approve it. Use posClient.erc20(address, true) for the Ethereum (parent) token; posClient.erc20(address) targets the Polygon (child) token. On the parent token, call approve(amount) and wait for the transaction. Read its hash with getTransactionHash(). Approval lets the bridge contract transfer that amount from the signer; it is a separate Ethereum transaction from the deposit.
  3. Deposit to Polygon. Call deposit(amount, userAddress) on the parent token, where userAddress is the Polygon address that should receive the tokens. Wait for the transaction and save its hash with getTransactionHash(). That hash identifies the Ethereum deposit. Matic.js status checks can confirm whether it is deposited; keep the hash so the app can check the same transfer later.
  4. Start the withdrawal on Polygon. After the deposited tokens are available on the child token, call withdrawStart(amount) there. Save the resulting burn transaction hash. This transaction starts the return route: the Polygon-side tokens are burned, and the Ethereum exit must wait for the bridge checkpoint that recognizes that burn.
  5. Wait for the checkpoint, then exit. Poll posClient.isCheckPointed(burnTxHash) with the burn hash. Continue only when it returns true; calling withdrawExit before then fails because the checkpoint proof is not ready. Once ready, use the parent token’s withdrawExit(burnTxHash) or withdrawExitFaster(burnTxHash). The faster method gets the proof from a proof API. The regular method builds it through many RPC calls, which can hit provider rate limits. A rate-limited attempt may need a provider with more capacity or a later retry. Save the exit transaction hash and don’t submit the exit twice: a second exit reverts. Check isWithdrawExited(burnTxHash) first if the app is retrying after a timeout.
  6. Confirm completion. Treat the flow as done only after isDeposited(depositTxHash) returns true for the deposit and isWithdrawExited(burnTxHash) returns true for the exit. Keep the approval, deposit, burn, and exit hashes with their statuses so the app can resume polling after a restart and distinguish a pending checkpoint from a completed withdrawal.

The critical dependency is the checkpoint: Matic.js can prepare the exit proof, but Ethereum cannot complete the release until the burn is checkpointed. Persisting each hash and checking the final status gives the app a clear record of both directions.

Related

Matic.js vs calling RootChainManager directly

Matic.js provides a POSClient interface around the bridge contracts and handles building the exit proof. Calling RootChainManager directly means your app must manage the contract interactions and proof flow itself.

How to bridge ERC-721 with Matic.js

This flow covers ERC-20 tokens. ERC-721 bridging uses NFT-specific bridge methods and token approvals, so adapt the app to the Matic.js NFT interface instead of using the ERC-20 calls here.

Questions developers ask next

How long until isCheckPointed returns true?

It depends on when the burn transaction is included in a checkpoint. Poll the burn hash and proceed only when isCheckPointed returns true; don’t assume a fixed wait time in the app.

Does Matic.js support Polygon zkEVM?

This procedure is for Polygon PoS through POSClient. It does not describe a zkEVM bridge flow, so use the SDK and bridge instructions intended for that network.

How do I estimate gas for withdrawExit?

Estimate against the Ethereum transaction using the configured parent provider and signer. The proof-building route can affect RPC load, and the transaction’s gas estimate can vary with the proof and network conditions; handle estimation errors before submitting.

Can Matic.js bridge native ETH?

The calls here move ERC-20 tokens. Native ETH is not an ERC-20 token, so this approve-and-deposit flow does not apply to it; use the bridge method intended for the asset type.