Skip to main content

Testing on Testnet

Test the full gasless flow end-to-end before deploying to mainnet.

1. Fund Your Testnet Relayer

Your VELUMX_API_KEY works on both mainnet and testnet — the relayer routes based on the network field in each request. You still need STX in your relayer’s testnet balance.
  1. Log in to the VelumX Dashboard and copy your Relayer Address.
  2. Go to the Stacks Testnet Faucet and request STX for your relayer address.
  3. Repeat for your test wallet address — you’ll need testnet STX to hold tokens for USER_PAYS testing.

2. Switch the SDK to Testnet

Also pass network: 'testnet' to buildSponsoredContractCall:

3. Use Testnet Contract Addresses

Testnet deployer addresses start with ST. The Bitflow testnet deployer is ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM. If you’re testing against your own paymaster contract, deploy it to testnet first using Clarinet or the Hiro Platform.

4. Run a Full DEVELOPER_SPONSORS Test


5. Verify on the Testnet Explorer

Once you have a txid, check it on the Stacks Testnet Explorer:
Look for:
  • Status: success — the sponsored transaction was accepted and executed.
  • Sponsored by: your relayer address — confirms VelumX co-signed correctly.
  • Fee payer: your relayer address — confirms the relayer paid STX gas, not the user.

6. Common Testnet Issues