> ## 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.

# Shield Swap Setup

> Configure your trading setup to trade assets privately on Shield Swap.

<div className="shield-trade-switch not-prose" role="group" aria-label="Trading guide audience">
  <button type="button" id="trade-developers-option" data-trade-select="developers" aria-pressed="true" aria-controls="developers">Developers</button>
  <button type="button" id="trade-web-app-option" data-trade-select="web-app" aria-pressed="false" aria-controls="web-app">Web App</button>
</div>

<div id="developers" data-trade-view="developers" role="region" aria-labelledby="trade-developers-option">
  Shield Swap is a decentralized AMM exchange that enables private swaps between asset pairs. This guide introduces the SDKs, CLIs, and APIs available for Shield Swap and provides installation and configuration steps for each option.

  The table below lists the available trading options and when to use each.

  | Option | When to use it |
  | - | - |
  | [Web app](https://swap.shield.fi/) | Trade via a UI in a browser with a connected wallet. |
  | [TypeScript SDK](https://www.npmjs.com/package/@provablehq/shield-swap-sdk) | Add private trading to web/browser apps, trading terminals, Node.js services, or JS/TS based trading agents. |
  | [Python SDK](https://pypi.org/project/shield-swap-sdk/) | Add private trading to Python based trading strategies/agents. |
  | [Shield Swap CLI](https://www.npmjs.com/package/@provablehq/shield-swap-cli) | Agents or humans that need to run tool calls via CLI or shell scripts. |

  The sections below show how to set up your chosen trading tools for **mainnet**. To begin trading on testnet, use the [Quickstart](./quickstart).

  ## Install

  <Tabs>
    <Tab title="TypeScript">
      #### Services, scripts, and agents

      Install Node.js 22 or later and the SDK packages in an application that uses ES modules:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      npm install @provablehq/shield-swap-sdk@0.12.1 @provablehq/veil-aleo-sdk@0.12.1
      ```

      #### Browser

      For browser-based apps, install the trading SDK and wallet adapter packages:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      npm install @provablehq/shield-swap-sdk@0.12.1 @provablehq/veil-core@0.12.1 @provablehq/veil-aleo-wallet-adapter@0.12.1
      npm install @provablehq/aleo-wallet-adapter-shield @provablehq/aleo-types @provablehq/aleo-wallet-standard
      ```
    </Tab>

    <Tab title="Python">
      Install Python 3.11 or later, then install the SDK in the application's Python environment:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      python -m pip install "shield-swap-sdk==0.6.1"
      ```
    </Tab>

    <Tab title="CLI">
      Install Node.js 22 or later, then install the CLI:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      npm install -g @provablehq/shield-swap-cli@0.12.1
      shield-swap --help
      ```

      The `--help` option lists all available Shield Swap commands.
    </Tab>
  </Tabs>

  ## Configure

  ### 1. Setup an account

  Shield Swap runs on the Aleo network to enable private trades. The guide below shows how to setup an Aleo account for private trading.

  <Note>
    Your private key controls your account and its funds. Never share it or include it in source control or logs. Keep a secure backup of your private key or saved account files so you can restore the account later. [Aleo's account keys guide](https://docs.aleo.org/build/sdk/guides/create_account/index.html#account-keys) explains the private key, view key, compute key, and address.
  </Note>

  <Tabs>
    <Tab title="TypeScript">
      #### Services, scripts, and agents

      Load an existing mnemonic or private key to set up an account, or generate a new account if neither is available.

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { loadNetwork } from "@provablehq/veil-aleo-sdk"

      const aleo = await loadNetwork("mainnet")
      const mnemonic = process.env.SHIELD_SWAP_MNEMONIC
      const privateKey = process.env.SHIELD_SWAP_PRIVATE_KEY
      const account = mnemonic
        ? aleo.mnemonicToAccount(mnemonic)
        : privateKey
          ? aleo.privateKeyToAccount(privateKey)
          : aleo.generateAccount()
      ```

      A newly generated account exists only in memory. Save `account.privateKey` in your application's secret manager before ending the session so you can load the same account next time.

      #### Browser apps

      Browser apps use a connected wallet to manage the account and its private key. Select an existing account in the wallet, or create one there, then connect it from the app:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { ShieldWalletAdapter } from "@provablehq/aleo-wallet-adapter-shield"
      import { Network } from "@provablehq/aleo-types"
      import { WalletDecryptPermission } from "@provablehq/aleo-wallet-standard"
      import { SHIELD_SWAP_ALGORITHM_GRANTS } from "@provablehq/shield-swap-sdk"

      const adapter = new ShieldWalletAdapter()
      await adapter.connect(
        Network.MAINNET,
        WalletDecryptPermission.UponRequest,
        undefined,
        { algorithmsAllowed: SHIELD_SWAP_ALGORITHM_GRANTS },
      )
      ```
    </Tab>

    <Tab title="Python">
      Load an existing private key, or use a `Profile` to restore a saved account or create one if none exists. A profile is an account file managed by the SDK that stores the private key, address, and network locally for later sessions.

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import os
      from aleo import mainnet
      from aleo_shield_swap import Profile

      key = os.environ.get("SHIELD_SWAP_PRIVATE_KEY")
      if not key:
          profile = Profile.load_or_create(".shield-swap/python/mainnet", network="mainnet")
          if profile.network != "mainnet":
              raise SystemExit("This setup requires a mainnet profile")
          key = profile.private_key

      private_key = mainnet.PrivateKey.from_string(key)
      address = str(private_key.address)
      ```

      Use a separate profile directory for each account and network.
    </Tab>

    <Tab title="CLI">
      The CLI reuses the account saved in `.shield-swap/mainnet/state.json`. If none exists, it imports `SHIELD_SWAP_PRIVATE_KEY` or `SHIELD_SWAP_PRIVATE_KEY_FILE` when supplied; otherwise, `--new` creates and saves an account. Run later commands from the same directory to reuse it.

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

      Setup saves the account and credentials before checking funds. If it reports that the account holds no tokens on mainnet, [fund the printed address](./fund-and-bridge), then rerun the command. The CLI does not load `.env` files automatically.
    </Tab>
  </Tabs>

  ### 2. Setup a trading client

  <Tabs>
    <Tab title="TypeScript">
      #### Client setup for services, scripts, and agents

      The typescript SDK uses viem-like `Client` and `Action` semantics and allows clients to be extended with arbitrary actions. The step below uses the account created above to create a Wallet Client and extends it with Shield-Swap trading actions. In detail, `createAleoClient` creates a `WalletClient` configured with Aleo RPC and gas payment services. The example then extends it with `shieldSwapActions`, which provides actions for quoting, swapping, inventory management, and accessors to the Shield Swap API.

      Continue with `aleo` and `account` from step 1:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { shieldSwapActions } from "@provablehq/shield-swap-sdk"

      const { walletClient, publicClient } = aleo.createAleoClient({
        privateKey: account.privateKey,
      })
      let client = walletClient.extend(shieldSwapActions({ api: {} }))
      ```

      #### Browser client setup

      When building a web or browser application, a wallet manages the account, all token inventory records, and transaction signing. In this case, an `RPC` account must be created to request these services from a browser or embedded wallet.

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { createPublicClient, createWalletClient, fallback, http } from "@provablehq/veil-core"
      import { fromWalletAdapter } from "@provablehq/veil-aleo-wallet-adapter"
      import { shieldSwapActions } from "@provablehq/shield-swap-sdk"

      const { account, transport } = fromWalletAdapter(adapter)
      const rpc = http("https://edge.provable.com/api/v2", { network: "mainnet" })
      const publicClient = createPublicClient({ transport: rpc })
      const walletClient = createWalletClient({
        account,
        transport: fallback([transport, rpc]),
      })
      const client = walletClient.extend(shieldSwapActions({ api: {} }))
      ```

      `publicClient` reads chain state, including the transaction checks in [Swap](./swap#check-the-result-2). The connected wallet authorizes trades.
    </Tab>

    <Tab title="Python">
      The `python SDK` provides `web3.py` style semantics to communicate with Shield Swap and the Aleo Network. An `Aleo` object must be created and configured with an RPC provider, and should be configured with the account created in the previous step. From there, register with the Aleo Record Scanning service (that scans for token records) and use the configured **`Aleo`** object to create a **`ShieldSwap`** client.

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      from aleo import Aleo, HTTPProvider
      from aleo_shield_swap import ShieldSwap

      aleo = Aleo(HTTPProvider("https://edge.provable.com/api", network="mainnet"))
      account = aleo.account.from_private_key(private_key)
      aleo.default_account = account

      registration = aleo.records.register(account)
      if not registration["ok"]:
          raise RuntimeError(f"Record scanner registration failed: {registration['error']}")

      dex = ShieldSwap(aleo)
      ```
    </Tab>

    <Tab title="CLI">
      The Shield-Swap CLI auto-configures a client upon account registration. This configuration can be verified by checking the account’s balances.

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap balances --network mainnet
      ```
    </Tab>
  </Tabs>

  ### 3. Configure optional storage

  Persistent storage retains swap history and the secret data needed to claim an output after a restart. Configure it before submitting swaps if the application needs this recovery path.

  <Tabs>
    <Tab title="TypeScript">
      #### Client setup for services, scripts, and agents

      For faster trading, it’s recommended to persist recovery data. To enable this, configure a swap file store before authenticating or submitting swaps. If this step is skipped, recovery data and swap history are lost when the process exits.

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import { swapFileStore } from "@provablehq/shield-swap-sdk/node"

      const identities = swapFileStore(`.shield-swap/mainnet/${account.address}/swaps.json`)
      client = walletClient.extend(
        shieldSwapActions({ api: {}, blindedIdentities: identities }),
      )
      ```

      #### Browser client setup

      All browser configurations persist history and recovery data within the configured wallet. No storage configuration is required for browser applications.
    </Tab>

    <Tab title="Python">
      For faster trading, it’s recommended to persist recovery data. To enable this, attach a `Journal` to the `ShieldSwap` client before submitting swaps. If this step is skipped, swap history is not saved automatically, and the application will need to either manually record swap history or reconstruct it on every restart.

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      from aleo_shield_swap import Journal

      dex.journal = Journal(f".shield-swap/python/mainnet/{address}/journal.jsonl")
      ```
    </Tab>

    <Tab title="CLI">
      The CLI manages storage automatically. It retains the private key, API credentials, and claim data under `.shield-swap/mainnet/`. Run later commands from the same directory and keep it between sessions; no additional storage setup is needed.
    </Tab>
  </Tabs>

  ### 4. Authenticate with the API

  The Shield Swap API requires authentication via a signature over a challenge containing the current Terms of Use. The step below performs this signature and grants API access.

  <Tabs>
    <Tab title="TypeScript">
      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      await client.authenticateShieldSwap()
      ```
    </Tab>

    <Tab title="Python">
      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      dex.api.authenticate(
          address,
          lambda message: str(private_key.sign(message.encode())),
      )
      ```
    </Tab>

    <Tab title="CLI">
      `shield-swap setup` authenticates and saves an API token for later commands. Confirm the configured account can read its balances:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap balances --network mainnet
      ```
    </Tab>
  </Tabs>

  #### Get or redeem a referral code (optional)

  Optional referral code redemption can be redeemed via traders participating in Shield Swap incentive program.

  <Tabs>
    <Tab title="TypeScript">
      **Get the account’s referral code**

      `getMyReferralCode()` calls [GET /referral/my-code](../api-reference/referrals/get-my-referral-code) to retrieve your shareable code or create one if permitted:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      const { code: myReferralCode } = await client.api.getMyReferralCode()
      ```

      **Redeem another trader’s code**

      Replace `REFERRAL_CODE` with the code another trader shared with you:

      ```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      const referralCode = "REFERRAL_CODE"
      await client.api.redeemReferralCode(referralCode)
      ```
    </Tab>

    <Tab title="Python">
      **Get the account’s referral code**

      `my_referral_code()` calls [GET /referral/my-code](../api-reference/referrals/get-my-referral-code) to retrieve the account’s shareable code or create one if permitted:

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      my_referral_code = dex.api.my_referral_code()
      ```

      **Redeem another trader’s code**

      ```python theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      import os

      referral_code = os.environ.get("SHIELD_SWAP_REFERRAL_CODE")
      if referral_code:
          dex.api.redeem_code(referral_code)
      ```
    </Tab>

    <Tab title="CLI">
      **Get the account’s referral code**

      Use the account saved by `setup` to retrieve its shareable code or create one if permitted:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap redeem --generate --network mainnet --execute
      ```

      **Redeem another trader’s code**

      Replace `REFERRAL_CODE` with the code another trader shared with you:

      ```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
      shield-swap redeem --code REFERRAL_CODE --network mainnet --execute
      ```

      Omit `--execute` to preview either action. Run generation and redemption separately.
    </Tab>
  </Tabs>

  ## Next Steps

  **Fund the trading account**

  Follow the [Fund guide](./fund-and-bridge) to add assets to the configured Shield Swap trading account.

  **Run full examples**

  The [TypeScript examples in the Shield Swap JS/TS SDK](https://github.com/ProvableHQ/veil/tree/main/packages/shield-swap/examples/first-swap) and [Python examples in the Shield Swap SDK](https://github.com/ProvableHQ/python-sdk/tree/master/shield-swap-sdk/examples/first-swap) cover account setup, funding, quoting, submission, and claiming. Follow the [run instructions](./quickstart#run-packaged-examples) to try them with test tokens on testnet.
</div>

<div id="web-app" data-trade-view="web-app" role="region" aria-labelledby="trade-web-app-option" hidden>
  Shield Wallet holds the account you use with Shield Swap and asks you to approve connections and transactions. You can create a new account or import one you already use.

  ## Install Shield Wallet

  **Before you start**

  You'll need Chrome or a Chromium-based desktop browser, such as Brave.

  1. Open the [Shield Wallet extension in the Chrome Web Store](https://chromewebstore.google.com/detail/shield/hhddpjpacfjaakjioinajgmhlbhfchao).
  2. Install the extension through your browser's prompts.
  3. Open Shield Wallet from the extensions menu.

  ## Create or import an account

  Choose the path that matches whether you already have an account.

  ### Create a new account

  1. Select **Create Wallet** in Shield Wallet.
  2. Back up the seed phrase offline. It lets you restore the account if you lose access to this browser.
  3. Complete the wallet's prompts to name the account and set a password.

  The [extension setup guide](https://support.shield.app/en/articles/13123296-shield-browser-extension-setup-guide) covers each screen.

  ### Import an existing account

  <Warning>
    **Enter your seed phrase or private key only in Shield Wallet.** Shield Swap never needs either to connect your account.
  </Warning>

  1. Choose the import option during wallet setup.
  2. Follow the prompts to import with your existing seed phrase or private key.
  3. Check that the imported account shows the address you expect to use.

  If Shield Wallet is already set up, open the account selector and choose **Import**. The [wallet import guide](https://support.shield.app/en/articles/13162125-how-to-import-a-non-legacy-wallet-into-shield) covers importing an account created in Shield Wallet.

  Your account is ready in Shield Wallet. Continue to [Fund](./fund-and-bridge#web-app) to connect it to Shield Swap and add assets for trading.
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.