Set up the TypeScript SDK

@provablehq/shield-swap-sdk adds typed Shield Swap actions to a Veil client. Use the extended wallet client for Shield Swap reads, writes, and records; publicClient for general ledger queries such as transaction acceptance; and client.api for indexed REST methods. The SDK handles record selection, program imports, swap planning, confidential addresses, and position math for applications that sign Shield transactions. This guide targets SDK version 0.12.1. For a complete testnet trade, start with the Quickstart.

Install

pnpm add @provablehq/shield-swap-sdk@0.12.1 @provablehq/veil-core@0.12.1

Local-key clients also need the network package, which installs the underlying Provable SDK.

pnpm add @provablehq/veil-aleo-sdk@0.12.1

Create a local client

This example uses mainnet. Change loadNetwork("mainnet") to loadNetwork("testnet") for testnet. shieldSwapActions({ api: {} }) selects the Shield API host for the client’s network; you do not need to supply its URL.

import { loadNetwork } from "@provablehq/veil-aleo-sdk"
import { shieldSwapActions } from "@provablehq/shield-swap-sdk"
import { swapFileStore } from "@provablehq/shield-swap-sdk/node"

const aleo = await loadNetwork("mainnet")

const privateKey = process.env.SHIELD_SWAP_PRIVATE_KEY
if (!privateKey) throw new Error("Set SHIELD_SWAP_PRIVATE_KEY before continuing")
const { walletClient, publicClient, account } = aleo.createAleoClient({ privateKey })

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

createAleoClient configures the hosted gateway, record scanner, delegated proving, and FeeMaster payment by default. The default gateway needs no Provable API credentials. Pass useFeeMaster: false when the account should pay its own transaction fees. The default confidential-address store protects concurrent swaps through one client, but it lives in memory and is lost when the process exits. For bots and services, use swapFileStore, an alias of fileBlindedIdentityStore, to retain pending claims across restarts. Use a separate store for each network and account. Change the path when switching this example to testnet, and keep .shield-swap/ out of source control.

Keep private keys, Provable credentials, API tokens, and confidential-address files out of source control.

Connect a wallet

The wallet holds keys and records and proves transactions. Pass Shield Swap’s algorithm grants when connecting, then extend the wallet client.

import { createWalletClient } from "@provablehq/veil-core"
import { fromWalletAdapter } from "@provablehq/veil-aleo-wallet-adapter"
import {
  SHIELD_SWAP_ALGORITHM_GRANTS,
  shieldSwapActions,
} from "@provablehq/shield-swap-sdk"

await adapter.connect(network, decryptPermission, {
  algorithmsAllowed: SHIELD_SWAP_ALGORITHM_GRANTS,
})

const { account, transport } = fromWalletAdapter(adapter)
const client = createWalletClient({ account, transport }).extend(
  shieldSwapActions({ api: {} }),
)

A connected wallet supplies record requests to transaction actions. The local-key client can find its own records through the configured scanner.

Authenticate the API

Pool and token discovery and public market data do not require credentials. Routes, positions, and unclaimed outputs require authentication and acceptance of the current Terms of Use. getBalances reads records and chain state without a DEX API credential.

await client.authenticateShieldSwap()

authenticateShieldSwap() signs a challenge and stores the session on the API client. Long-running services can create an API token once and pass it as shieldSwapActions({ api: { apiToken } }) on later runs. See Authentication.

Read state

Use the API to discover markets and metadata. Before signing, read the pool state needed for execution from chain.

const pools = await client.api.getPools({ limit: 50 })
const balances = await client.getBalances()

const market = pools.data[0]
if (!market) throw new Error("no pools are available")

const poolKey = market.key
const pool = await client.getPool({ poolKey })
const slot = await client.getSlot({ poolKey })
const controls = await client.getTradeControls({ poolKey })

if (!pool || !slot || !controls.tradeable) {
  throw new Error("pool is unavailable")
}

Token amounts use raw base units and bigint. Apply token decimals only when parsing user input or formatting output. Pool price and fee-growth values use Q128.128 fixed-point representation. For transaction acceptance, call await publicClient.getConfirmedTransaction({ id: transactionId }) and inspect status. This method is not on the extended wallet client by default. See Verify swap settlement to check the swap, claim, and returned records together.

Resolve program imports

Shield Swap calls token programs dynamically. Write actions need the source for each token program plus the AMM’s declared imports.

const token0 = await client.tokenData(pool.token0)
const token1 = await client.tokenData(pool.token1)
if (!token0.ammTokenProgram || !token1.ammTokenProgram) {
  throw new Error("pool token program is missing")
}

const imports = await client.resolveDexImports({
  tokenPrograms: [token0.ammTokenProgram, token1.ammTokenProgram],
})

Resolve imports once for a route or pool and reuse the map. Continue with SDK swaps or SDK liquidity. The package source and examples document the full SDK.

Understand Shield Swap

Trading reference

Concepts

Data and confidentiality

Security and controls

Math and accounting

Program reference

Set up the TypeScript SDK

Install

Create a local client

Connect a wallet

Authenticate the API

Read state

Resolve program imports

​Install

​Create a local client

​Connect a wallet

​Authenticate the API

​Read state

​Resolve program imports

Install

Create a local client

Connect a wallet

Authenticate the API

Read state

Resolve program imports