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

# Make your first swap with the CLI

> Install the CLI, fund a testnet account, and swap 1 USDCx for ETH.

Choose your path: [SDK quickstart](./sdk) · **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

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
mkdir shield-first-swap-cli
cd shield-first-swap-cli
npm install -g @provablehq/shield-swap-cli@0.11.1
shield-swap --version
```

The version command should print `0.11.1`.

Create `.gitignore`:

```gitignore theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
node_modules/
.shield-swap/
```

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

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap setup --new --network testnet
```

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.

<Accordion title="CLI reports NEEDS_INVITE_CODE">
  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.
</Accordion>

If setup stops, run `shield-swap setup --network testnet` to continue with the saved account.

<Accordion title="Use an existing testnet account">
  Instead of `--new`, save your private key to a file outside this project and pass its path:

  ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
  shield-swap setup --private-key-file /path/to/my-key.txt --network testnet
  ```

  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.
</Accordion>

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:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap balances --network testnet
```

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

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap swap --from USDCx --to ETH --amount 1 --network testnet
```

Without `--execute`, the command only prepares a quote. Check the following before submitting:

| Field | What to check |
| - | - |
| `network` | Testnet |
| `sell` | 1 USDCx |
| `buy` | Estimated ETH output |
| `floor` | Minimum ETH output accepted after slippage |
| `route` | One to three pools used for the swap |
| `claim` | Yes, in this run |

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`:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap swap --from USDCx --to ETH --amount 1 --network testnet --execute
```

<Warning>
  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.
</Warning>

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:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
curl --fail-with-body --silent --show-error \
  "https://api.explorer.provable.com/v1/testnet/transaction/confirmed/SWAP_TRANSACTION_ID"
curl --fail-with-body --silent --show-error \
  "https://api.explorer.provable.com/v1/testnet/transaction/confirmed/CLAIM_TRANSACTION_ID"
```

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](../verify-settlement#check-both-transactions) for help with rejected or unavailable results.

Check your updated balances:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap balances --network testnet
```

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](../failures-and-recovery#missing-output-records) if the delay persists.

Run the [settlement verifier](../verify-settlement#verify-the-output-record) 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.

<Accordion title="History says claimed but reports zero settled swaps">
  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.
</Accordion>

## Finish an interrupted swap

Do not run `swap --execute` again to recover a trade. Inspect the existing swap:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap history --network testnet
```

When the output is claimable, replace `SWAP_ID` with its ID from history:

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
shield-swap history --claim --swap-id SWAP_ID --network testnet --execute
```

If a transaction timed out, check [Failures and recovery](../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](../preparing-token-records).

## Next steps

* [Build with an SDK](./sdk) to add swaps to an application or bot.
* [Trader workflow](../trader-workflow) explains the full swap and claim lifecycle.