> ## Documentation Index
> Fetch the complete documentation index at: https://scaffoldstacks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Testnet deployment

> Deploy your dApp to Stacks testnet

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

## Contents

* [Requirements](#requirements)
* [Get testnet tokens](#get-testnet-tokens)
* [Deploy to testnet](#deploy-to-testnet)
* [Start frontend](#start-frontend)
* [Test interactions](#test-interactions)
* [Redeploy after changes](#redeploy-after-changes)
* [Troubleshooting](#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](https://explorer.hiro.so/sandbox/faucet?chain=testnet)
2. Request STX and sBTC
3. Add your mnemonic to `Testnet.toml`:

```toml theme={null}
[accounts.deployer]
mnemonic = "your 24 word seed phrase"
derivation = "m/44'/5757'/0'/0/0"
```

## Deploy to testnet

```bash theme={null}
stacksdapp deploy --network testnet
```

Preview without broadcasting:

```bash theme={null}
stacksdapp deploy --network testnet --dry-run
```

Deploy a single contract:

```bash theme={null}
stacksdapp deploy --network testnet --contract counter
```

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

## Start frontend

```bash theme={null}
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:

```bash theme={null}
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](/local-devnet) first
* Check contract requirements

### Frontend issues

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