Preview. Requires
@avnu/avnu-sdk >= 4.2.0 and a proving backend: a STRK20-capable wallet (starknet.js >= 10.4) or the Starknet privacy SDK. The sell token must already be in your private balance — deposit into the pool first. Questions? Reach out on Telegram.Setup
The snippets below assume a few objects are already wired up:
The paymaster client is built into the SDK: it targets
starknet.paymaster.avnu.fi by default (override with AvnuOptions.paymasterBaseUrl, e.g. sepolia.paymaster.avnu.fi for testing).
Wallet setup
Private swaps need theWalletAccountV6 flavor of the starknet.js account — it carries the STRK20 privacy methods (strk20PrepareInvoke, strk20Balances). Build it around the connected wallet as for any SDK usage: see Initialize your account.
Detect STRK20 support
The STRK20 privacy methods (wallet_strk20PrepareInvoke, wallet_strk20Balances, …) ship with wallet API >= 0.10.3 — Ready and Xverse today. Probe the connected wallet before surfacing private swaps in your UI:
wallet_supportedWalletApi throw on the probe — catch and treat them as not capable.
How it works
A private swap is anapply_action transaction relayed by avnu’s paymaster. No user signature is needed, since everything settles on-chain straight from the proof. executePrivateSwap orchestrates the four steps:
- Pool fee. The paymaster returns the pool fee to withdraw (token, recipient, amount).
- Private calls.
quoteToCalls({ private: true }): the backend setstakerAddress = executorand returns the inner swapcallsplus theexecutorAddress. - Proof. Your injected
PrivateSwapProverbuilds and proves the private transaction: withdraw the sell amount to the executor, withdraw the pool fee, open a note for the bought token, and invoke the executor with the serialized swap calls. - Submit. The paymaster relays the proof on-chain. The relayer pays gas; the pool fee reimburses it.
{ call, proof } artifact.
Execute a private swap
Implement the prover
Theprover is where the cryptography lives. It receives a PrivateSwapPlan (sell/buy tokens, amounts, executorAddress, inner calls, pool fee) and returns the proven call.
With a STRK20-capable wallet
If the connected wallet supports STRK20 (see Detect STRK20 support), the SDK ships a ready-made prover. The wallet keeps the keys and notes and generates the proof; the dapp only describes actions:wallet_strk20PrepareInvoke yourself instead, buildStrk20Actions(plan) returns the four STRK20 actions to prove; map the wallet’s { call, proof } artifact to PrivateSwapCallAndProof.
With the Starknet privacy SDK
When you manage keys and notes yourself, describe the same four actions with the privacy SDK’stransfers builder:
Open is a privacy SDK sentinel that opens a note for the swap output, whose amount is only known after execution. The inner calls are serialized with starknet.js’s transaction.fromCallsToExecuteCalldata_cairo1; the executor expects [buyToken, ...serializedCalls, openNoteId]. Both proving backends produce the same { call, proof } artifact.
Manual control
executePrivateSwap wraps three functions you can also call yourself:
Key parameters
The SDK’s private swap functions always run in thesponsored_private fee mode: the relayer pays gas, the user pays the pool fee from their private balance.
string
required
Token used to pay the pool fee (e.g. STRK, ETH, USDC). The paymaster converts the base STRK amount to this token via its price oracle.
'slow' | 'normal' | 'fast'
default:"normal"
Relayer priority tip.
string
required
The privacy pool contract address. The SDK exports the pools whitelisted by the paymaster:
PRIVACY_POOL_ADDRESS (mainnet) and SEPOLIA_PRIVACY_POOL_ADDRESS.PrivateSwapProver
required
Your proving backend:
buildAndProve(plan) returns the proven { call, proof }. For STRK20 wallets, use createStrk20WalletProver(account). The SDK never handles private keys, notes, or proof generation.string
Optional fail-fast check: when provided, it is compared to
quote.chainId before any paymaster or proving round-trip.string
required
Portal API key, the same one used for gasfree — the paymaster requires it for the sponsored modes. Server-side only: do not ship it in client code. Browser dapps should split the flow:
buildPrivateSwapFee and submitPrivateSwap behind server endpoints, proving (prover) client-side with the user’s wallet.Related
Privacy Overview
Privacy pool, fees, and transaction types
Get Quotes
Fetch solver-optimized swap quotes