Set up the TypeScript SDK

@provablehq/shield-swap-sdk adds typed Shield Swap actions to a Veil client. Chain reads and writes sit on client. Indexed REST methods sit on client.api. Use the SDK when an application needs to sign Shield transactions without implementing record selection, program imports, swap planning, confidential addresses, or position math from scratch. These guides target SDK version 0.7.0.

Install

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

Local-key clients also need the network package and the SDK used for confidential-address derivation.

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

Create a local client

This example uses mainnet. Change loadNetwork("mainnet") to loadNetwork("testnet") for testnet. The Shield API host follows the client’s network, so shieldSwapActions({ api: {} }) selects the matching API without a hardcoded URL.

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

const aleo = await loadNetwork("mainnet")

const scanner = aleo.createRemoteScanner({
  url: "https://api.provable.com/scanner",
  consumerId: process.env.ALEO_CONSUMER_ID,
  apiKey: process.env.ALEO_DPS_API_KEY,
})

const { walletClient, account } = aleo.createAleoClient({
  privateKey: process.env.SHIELD_SWAP_PRIVATE_KEY,
  networkUrl: "https://api.provable.com/v2",
  provingMode: "delegated",
  proverUrl: "https://api.provable.com/prove",
  consumerId: process.env.ALEO_CONSUMER_ID,
  apiKey: process.env.ALEO_DPS_API_KEY,
  records: scanner,
})

const client = walletClient.extend(
  shieldSwapActions({
    api: {},
    blindedIdentities: fileBlindedIdentityStore(
      ".shield-swap/blinded-identities.json",
    ),
  }),
)

The default in-memory confidential-address store protects concurrent swaps made through one client. It disappears when the process exits. Bots and services should use fileBlindedIdentityStore so pending claims survive restarts.

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 are public. Routes, balances, positions, swaps, and other account data require authentication and invited access.

await client.authenticateShieldSwap()

const access = await client.api.getAccessStatus()
if (!access.has_access) {
  await client.api.redeemAccessCode(inviteCode)
}

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. Read execution-critical pool state from chain before signing.

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.

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 complete SDK surface.

Start

Build

Trade

Provide liquidity

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