Skip to main content
Choose your path: SDK quickstart · CLI quickstart Swap 1 USDCx for ETH on testnet with Shield Swap CLI 0.11.1. The CLI submits the swap and claims the output in one run. Your trade is complete when the claim succeeds and the returned token records are available.

​
Before you start

Install Node.js 22 or later, which includes npm. These commands always use testnet, regardless of the network selected in the docs.

​
1. Install the CLI

The version command should print 0.11.1. Create .gitignore:
Run the rest of the commands from this directory. The CLI saves your private key, DEX credentials, and claim recovery data under .shield-swap/testnet/. Keep that directory between sessions and out of source control.

​
2. Create and fund the account

Setup creates your account and signs in to Shield Swap, then requests test tokens and waits for their records. The default gateway doesn’t require Provable API credentials. Delegated proving covers transaction fees, so you can start without a public ALEO balance. The sign-in message includes the current Terms of Use and related disclosures. Successful authentication records acceptance and grants API access. No invite code is required.
CLI 0.11.1 still prints this message when /referral/status returns has_access: false. In the current API, this field reports terms acceptance. Referral-code redemption does not grant access.Run shield-swap setup --network testnet again to sign in with a new challenge. If the message continues, check the API endpoint saved in .shield-swap/testnet/state.json and any SHIELD_SWAP_API_URL override. An older or custom deployment can have different access rules.
If setup stops, run shield-swap setup --network testnet to continue with the saved account.
Instead of --new, save your private key to a file outside this project and pass its path:
Do not paste the key into a command or commit the file. You can also set SHIELD_SWAP_PRIVATE_KEY in your shell. The CLI does not automatically load .env files.
In v0.11.1, setup also prints an ASK_NEXT_ACTION menu for agent integrations. You can skip that menu and continue with the balance check and quote below. Setup prints Account ... is ready on testnet and lists token balances. Check that the private column contains at least 1 USDCx:
Swaps spend token records from that balance. Public holdings cannot fund this swap. If the balance is still zero, wait for indexing and run the balance command again.

​
3. Quote and review

Without --execute, the command only prepares a quote. Check the following before submitting: The default slippage is 0.5% (50 basis points). To change it, add --slippage with a basis-point value. --amount takes a decimal token amount, such as 1 or 1.5. In v0.11.1, the CLI stops before submission if the output estimate is missing or unusable, or the minimum output is zero. If no route is available, run shield-swap pools --network testnet to find a tradeable pair.

​
4. Submit and claim

Use the same arguments and add --execute:
This command fetches and prints a fresh quote, then submits without asking for confirmation. The preview doesn’t lock the price. The contract uses the minimum output printed in this run, and running the command again starts another swap.
Quotes expire 60 seconds after the quote request starts. If the CLI reports an expired quote, it hasn’t submitted the swap. Request a new quote to continue. Proving and submitting can take a few minutes. The CLI then tries to claim the output, retrying while it waits for the output to become claimable. On success, it prints both transaction IDs and the amount of ETH received.

​
5. Verify settlement

Save the swap transaction ID, claim transaction ID, swap ID, and received amount printed by the command. Use the public testnet explorer API to check both transactions independently, replacing the placeholders with your IDs:
Look for "status": "accepted" in both responses. A transaction ID, HTTP 200, or successful CLI exit alone doesn’t confirm settlement. If a result is missing or the request fails, check again before submitting another trade. See Transaction lookup results for help with rejected or unavailable results. Check your updated balances:
If you started with 10 USDCx and 0.006 ETH and had no other activity or refund, expect 9 USDCx and 0.006 + received ETH. Use the amount you actually received; it can differ from the quote estimate. The scanner can lag behind the confirmed claim. If ETH is not visible yet, wait and check again. See Missing output records if the delay persists. Run the settlement verifier with your saved CLI account to check the exact output. It confirms that both transactions belong to the same swap and that swap_outputs[swap_id] is absent. It also matches a decrypted, unspent ETH record to the claim’s commitment and received amount. These checks don’t submit a transaction.
In v0.11.1, history can show a claimed row and an all-settled message, yet report zero settled swaps and leave out the received amount. This can happen when the local history has no recorded claim. Check the accepted claim and its matching output record to confirm settlement. Don’t submit another claim to fix the display.

​
Finish an interrupted swap

Do not run swap --execute again to recover a trade. Inspect the existing swap:
When the output is claimable, replace SWAP_ID with its ID from history:
If a transaction timed out, check Failures and recovery before submitting again. Do not resubmit an accepted claim. If your total balance is sufficient but no single record covers the swap, see Preparing token records.

​
Next steps