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. Treat both transactions as one workflow. The user’s trade is settled after the claim is accepted and the returned records are available.

Plan the route

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 required for the claim. A local client with fileBlindedIdentityStore records it before the action returns. If you do not use that store, persist the handle in your own database before leaving 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.

Recover pending claims

Long-running local clients should inspect the configured identity store after startup.

const pending = await client.getUnclaimedSwaps()

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

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

getUnclaimedSwaps reads swap_outputs from chain. It returns per-token totals and handles that can be claimed from the store alone. 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. Input token records are a separate source of contention. Two concurrent swaps cannot spend the same 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.

Start

Build

Trade

Provide liquidity

Swap with the TypeScript SDK

Plan the route

Submit the request

Claim the output

Recover pending claims

Run concurrent swaps safely

​Plan the route

​Submit the request

​Claim the output

​Recover pending claims

​Run concurrent swaps safely

Plan the route

Submit the request

Claim the output

Recover pending claims

Run concurrent swaps safely