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

# Set up the TypeScript SDK

> Set up the Shield Swap TypeScript SDK for chain reads, API access, swaps, and liquidity.

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

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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.

```bash theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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.

```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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.

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

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

```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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.

```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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](../rest/authentication).

## Read state

Use the API to discover markets and metadata. Read execution-critical pool state from chain before signing.

```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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.

```typescript theme={"languages":{"custom":["/languages/leo.tmLanguage.json"]}}
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](./swaps) or [SDK liquidity](./liquidity). The [package source and examples](https://github.com/ProvableHQ/veil/tree/main/packages/shield-swap) document the complete SDK surface.