Shield Swap Setup

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	Trade via a UI in a browser with a connected wallet.
TypeScript SDK	Add private trading to web/browser apps, trading terminals, Node.js services, or JS/TS based trading agents.
Python SDK	Add private trading to Python based trading strategies/agents.
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.

Install

TypeScript
Python
CLI

Services, scripts, and agents

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

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:

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

Install Python 3.11 or later, then install the SDK in the application’s Python environment:

python -m pip install "shield-swap-sdk==0.6.1"

Install Node.js 22 or later, then install the CLI:

npm install -g @provablehq/shield-swap-cli@0.12.1
shield-swap --help

The --help option lists all available Shield Swap commands.

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.

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 explains the private key, view key, compute key, and address.

TypeScript
Python
CLI

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.

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:

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 },
)

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.

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.

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.

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, then rerun the command. The CLI does not load .env files automatically.

2. Setup a trading client

TypeScript
Python
CLI

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:

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.

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. The connected wallet authorizes trades.

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.

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)

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

shield-swap balances --network mainnet

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.

TypeScript
Python
CLI

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.

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.

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.

from aleo_shield_swap import Journal

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

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.

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.

TypeScript
Python
CLI

await client.authenticateShieldSwap()

dex.api.authenticate(
    address,
    lambda message: str(private_key.sign(message.encode())),
)

shield-swap setup authenticates and saves an API token for later commands. Confirm the configured account can read its balances:

shield-swap balances --network mainnet

Get or redeem a referral code (optional)

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

TypeScript
Python
CLI

Get the account’s referral codegetMyReferralCode() calls GET /referral/my-code to retrieve your shareable code or create one if permitted:

const { code: myReferralCode } = await client.api.getMyReferralCode()

Redeem another trader’s codeReplace REFERRAL_CODE with the code another trader shared with you:

const referralCode = "REFERRAL_CODE"
await client.api.redeemReferralCode(referralCode)

Get the account’s referral codemy_referral_code() calls GET /referral/my-code to retrieve the account’s shareable code or create one if permitted:

my_referral_code = dex.api.my_referral_code()

Redeem another trader’s code

import os

referral_code = os.environ.get("SHIELD_SWAP_REFERRAL_CODE")
if referral_code:
    dex.api.redeem_code(referral_code)

Get the account’s referral codeUse the account saved by setup to retrieve its shareable code or create one if permitted:

shield-swap redeem --generate --network mainnet --execute

Redeem another trader’s codeReplace REFERRAL_CODE with the code another trader shared with you:

shield-swap redeem --code REFERRAL_CODE --network mainnet --execute

Omit --execute to preview either action. Run generation and redemption separately.

Next Steps

Fund the trading accountFollow the Fund guide to add assets to the configured Shield Swap trading account.Run full examplesThe TypeScript examples in the Shield Swap JS/TS SDK and Python examples in the Shield Swap SDK cover account setup, funding, quoting, submission, and claiming. Follow the run instructions to try them with test tokens on testnet.

Start

Trade

Provide liquidity

Integration guides

Install

Services, scripts, and agents

Browser

Configure

1. Setup an account

Services, scripts, and agents

Browser apps

2. Setup a trading client

Client setup for services, scripts, and agents

Browser client setup

3. Configure optional storage

Client setup for services, scripts, and agents

Browser client setup

4. Authenticate with the API

Get or redeem a referral code (optional)

Next Steps

Install Shield Wallet

Create or import an account

Create a new account

Import an existing account

​Install

​Services, scripts, and agents

​Browser

​Configure

​1. Setup an account

​Services, scripts, and agents

​Browser apps

​2. Setup a trading client

​Client setup for services, scripts, and agents

​Browser client setup

​3. Configure optional storage

​Client setup for services, scripts, and agents

​Browser client setup

​4. Authenticate with the API

​Get or redeem a referral code (optional)

​Next Steps

​Install Shield Wallet

​Create or import an account

​Create a new account

​Import an existing account

Install

Services, scripts, and agents

Browser

Configure

1. Setup an account

Services, scripts, and agents

Browser apps

2. Setup a trading client

Client setup for services, scripts, and agents

Browser client setup

3. Configure optional storage

Client setup for services, scripts, and agents

Browser client setup

4. Authenticate with the API

Get or redeem a referral code (optional)

Next Steps

Install Shield Wallet

Create or import an account

Create a new account

Import an existing account