For the complete documentation index, see llms.txt. This page is also available as Markdown.

Delegated Swaps

Use Permit2 Witness when the payer and executor are different accounts.

The payer supplies ERC20 input and signs authorization; a different executor submits the swap and pays gas. Set an explicit recipient. The SDK supports native BNB output, but not native input.

The flow has two Aggregator requests: swapPermit2() prepares the plan, then swapPermit2Build() builds the transaction after payer signing. Approval, simulation and submission are separate actions.

Initialize the client as in Quickstart. The examples use client, token addresses, input amount, outputDecimals, an explicit recipient, and separate payerSigner and executorSigner connected to BSC. Import ethers from ethers and PERMIT2_ADDRESS from @masterpeach/aggregator-sdk.

1. Prepare the swap

Run this after the user chooses to trade.

const payer = await payerSigner.getAddress();
const executor = await executorSigner.getAddress();
const prepared = await client.swapPermit2({
  from: tokenIn, target: tokenOut, amount, payer, executor, recipient,
  slippageBps: 50, // 0.5%
  deadlineSecs: 300,
});
if (prepared.amountIn !== amount) throw new Error("Prepared input differs from the order");

Before signing, have the payer review prepared.amountIn, prepared.expectAmountOut, payer, executor, recipient, prepared.payerAuthorization.deadline and the requested slippage. slippageBps: 50 means 0.5%; use the user's chosen tolerance. The first request returns the expected output and freezes the route; build does not search again.

Signing authorizes execution. Once shared, the signature lets the designated executor submit while the plan remains valid. A later UI confirmation cannot revoke it.

Preparation exposes the plan hash and authorization. Its raw response also contains amount_out_min, but the high-level prepared object has no executable tx or decoded execution yet. The SDK validates the minimum against signed calldata after build. Do not present the raw prepare value as a pre-signature independently validated minimum; a stronger pre-signature guarantee requires additional API support.

2. Approve, sign, and build

The approval transaction is sent to the input ERC20 contract, granting canonical Permit2 permission to spend the exact prepared amount. The following Witness authorization is an EIP-712 message signature binding the plan to the Execution Router.

Build returns TRANSACTION_READY. Before submission, display the built expected output and ready.tx.amountOutMin using outputDecimals. This review controls your application's submission; the payer has already authorized execution. Do not deduct slippage again or edit the transaction.

The built result retains the original preparation as ready.prepared. Read its token and amount metadata there; signed execution values are in ready.execution.plan.

3. Execute the swap

Optionally call client.simulateSwap(ready, ready.executor) before submission. It requires the payer's input balance and confirmed base allowance. The executor needs BNB for gas.

Expired plans and retries

The SDK revalidates expiry before signing and building. If the plan expires, prepare again and obtain a new payer signature. Repreparing does not revoke a previous signature. See Transaction Safety for input changes and allowance reuse, and Client Configuration for failures and uncertain submissions.

The current SDK accepts only 64-byte compact or 65-byte payer signatures. Do not assume general ERC-1271 smart-contract-wallet compatibility; it has not been established for this workflow.

Last updated

Was this helpful?