Swap with the TypeScript SDK

A Shield Swap trade has two transactions. The request spends the input record and writes a pending output. The claim delivers the output and any unspent input as token records. Handle both transactions in your integration. The trade settles once the claim is accepted and the returned records are available.

Plan the route

In v0.12.1, you can request a quote with client.quote({ from, to, amountIn: "1", slippageBps: 50 }) and submit it with client.swap({ quote }). See the Quickstart for a complete example. Use the manual steps below if you need to supply execution parameters yourself. planSwap resolves token metadata, requests a route and quote, checks each pool against current chain controls, applies a slippage floor, and fetches the required program imports.

import { parseUnits } from "@provablehq/shield-swap-sdk"

const from = await client.tokenData("USDCx")
const plan = await client.planSwap({
  from: from.id,
  to: "ETH",
  amountIn: parseUnits("1.5", from.decimals),
  slippageBps: 50,
})

Amounts passed to transaction actions are raw base units. 50 basis points means 0.5 percent slippage.

Submit the request

Use swap for one pool and swapMultiHop for a route with two or more pools.

const handle = plan.multiHop
  ? await client.swapMultiHop({
      poolKeys: plan.poolKeys,
      tokenInId: plan.from.id,
      amountIn: plan.amountIn,
      expectedOut: plan.expectedOut,
      slippageBps: plan.slippageBps,
      imports: plan.imports,
    })
  : await client.swap({
      poolKey: plan.poolKeys[0]!,
      tokenInId: plan.from.id,
      amountIn: plan.amountIn,
      expectedOut: plan.expectedOut,
      slippageBps: plan.slippageBps,
      imports: plan.imports,
    })

The returned handle contains the data needed to claim the output. A local client with fileBlindedIdentityStore records it before the action returns. If you do not use that store, save the handle in your own database before ending the request flow. Do not submit another request because a confirmation wait timed out. Check the transaction and mapping state first. A second submission can spend another record and create another trade.

Claim the output

The pending output becomes readable after the request finalizes. Both route types use claimSwapOutput.

import { SwapOutputNotFinalizedError } from "@provablehq/shield-swap-sdk"

async function claimWhenReady() {
  for (let attempt = 0; attempt < 20; attempt++) {
    try {
      return await client.claimSwapOutput({
        handle,
        imports: plan.imports,
      })
    } catch (error) {
      if (!(error instanceof SwapOutputNotFinalizedError)) throw error
      await new Promise((resolve) => setTimeout(resolve, 15_000))
    }
  }

  throw new Error("swap output is still pending")
}

const claim = await claimWhenReady()
console.log(claim.amountOut, claim.amountRemaining)

amountOut is the received output. amountRemaining is the unused portion of the original input. Wrapped assets are paid out as records of the underlying asset. For a multi-hop route, each later hop must consume its intermediate input. A partial fill in a later hop rejects the route. Only unused original input can appear as the final refund.

Verify settlement

Use publicClient.getConfirmedTransaction({ id }) for both the request and claim transaction IDs. Both must report accepted. Then check that client.getSwapOutput({ swapId: handle.swapId }) returns null and that the account has the claim’s returned token records. An absent pending output or an empty getUnclaimedSwaps() result does not establish settlement on its own. Match the accepted claim to the swap ID and its output commitments to the decrypted records. See Verify swap settlement for the complete quickstart verifier.

Recover pending claims

For long-running local clients, check the configured identity store at startup.

const pending = await client.getUnclaimedSwaps()

for (const swap of pending.swaps) {
  if (!swap.claimable || !swap.handle) continue

  await client.claimSwapOutput({
    handle: swap.handle,
  })
}

getUnclaimedSwaps reads swap_outputs from chain. It returns per-token totals and handles that can be claimed from the store alone. In v0.12.1, claimSwapOutput resolves program imports from the output tokens automatically. Older records without a complete handle may require reconcileSwapHistory().

Run concurrent swaps safely

The composed client reserves a distinct confidential address for each local swap. Use one store and one writer for each local account. A file store protects reservations across restarts, but it does not coordinate multiple processes or machines. Two concurrent swaps cannot spend the same input token record. Using different input tokens avoids that collision. For the same token, serialize record selection and submission or reserve distinct records in your own transaction queue. A connected wallet manages its own confidential addresses and record requests. Follow the wallet’s pending-transaction model and wait for a terminal state before reusing any record. See Trader workflow, output claims and refunds, and failures and recovery for the protocol rules behind these actions.

Understand Shield Swap

Trading reference

Concepts

Data and confidentiality

Security and controls

Math and accounting

Program reference

Swap with the TypeScript SDK

Plan the route

Submit the request

Claim the output

Verify settlement

Recover pending claims

Run concurrent swaps safely

​Plan the route

​Submit the request

​Claim the output

​Verify settlement

​Recover pending claims

​Run concurrent swaps safely

Plan the route

Submit the request

Claim the output

Verify settlement

Recover pending claims

Run concurrent swaps safely