Testnet deployment

Deploy Clarity smart contracts to Stacks testnet with stacksdapp deploy — faucet STX, dry-run fees, and publish your dApp for testing.

Deploy to Stacks testnet to test your dApp with real network conditions before mainnet. Testnet is the recommended first deploy target (no Docker required).

Contents

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

Requirements

Requirement	Notes
Clarinet	3.23+ (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"

Never commit real mnemonics. The bundled pre-commit hook blocks likely seed phrases in Testnet.toml and Mainnet.toml.

Deploy to testnet

stacksdapp check && stacksdapp generate && stacksdapp test
stacksdapp deploy --network testnet --yes

Use --yes for non-interactive deploys (CI and agents). Preview without broadcasting:

stacksdapp deploy --network testnet --dry-run

Deploy a single contract:

stacksdapp deploy --network testnet --contract counter

Wait for on-chain confirmation:

stacksdapp deploy --network testnet --yes --wait-confirm

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 --yes
# counter-v2, counter-v3, ...

The CLI handles versioning automatically unless you pass --no-auto-version.

Troubleshooting

Transaction failures

• Check gas fees
• Verify mnemonic and derivation path
• Ensure sufficient testnet balance
• Add --yes if deploy hangs on interactive prompts

Contract errors

• Run stacksdapp check for syntax validation
• Test locally with devnet first
• Check contract requirements
• For SIP tokens: omit (impl-trait …) on testnet (templates ship without it)

Frontend issues

• Verify network configuration in .env.local (NEXT_PUBLIC_NETWORK=testnet)
• Check browser console for errors
• Ensure wallet is set to testnet
• Do not run stacksdapp dev (devnet) when contracts were deployed to testnet