Testnet deployment

Deploy your dApp to Stacks testnet

Deploy to Stacks testnet to test your dApp with real network conditions before mainnet.

Contents

• Requirements
• Get testnet tokens
• Deploy to testnet
• Start frontend
• Test interactions
• Redeploy after changes
• Troubleshooting

Requirements

Requirement	Notes
Clarinet	3.21+ (stacksdapp doctor)
Testnet STX	Gas fees
Testnet sBTC	Only if your contracts use it
Deployer mnemonic	In contracts/settings/Testnet.toml

Get testnet tokens

1. Visit the Hiro testnet faucet
2. Request STX and sBTC
3. Add your mnemonic to Testnet.toml:

[accounts.deployer]
mnemonic = "your 24 word seed phrase"
derivation = "m/44'/5757'/0'/0/0"

Deploy to testnet

stacksdapp deploy --network testnet

Preview without broadcasting:

stacksdapp deploy --network testnet --dry-run

Deploy a single contract:

stacksdapp deploy --network testnet --contract counter

This generates a deployment plan, submits transactions, and updates deployments.json.

Start frontend

stacksdapp dev --network testnet

Opens at http://localhost:3000 connected to testnet.

Test interactions

• Connect Leather or Xverse (set to Testnet)
• Use the debug UI to call contract functions
• Verify wallet prompts and confirmations

Redeploy after changes

Contracts are immutable. Changes create new versions:

stacksdapp deploy --network testnet
# counter-v2, counter-v3, ...

The CLI handles versioning automatically.

Troubleshooting

Transaction failures

• Check gas fees
• Verify mnemonic and derivation path
• Ensure sufficient testnet balance

Contract errors

• Run stacksdapp check for syntax validation
• Test locally with devnet first
• Check contract requirements

Frontend issues

• Verify network configuration in .env.local
• Check browser console for errors
• Ensure wallet is set to testnet