Migration Guide
Update an existing integration to the swap methods introduced in SDK 0.5.0.
Upgrade with npm install @masterpeach/aggregator-sdk@latest ethers@^6. This page covers the changes from the old quote-then-prepare flow. For complete examples, use Quickstart for Allowance or Delegated Swaps for Permit2.
Change the request sequence
Allowance
getQuote() → prepareDirectSwap()
swapAllowance()
Permit2
getQuote() → prepareDelegatedSwap() → payer signs → buildDelegatedSwap()
swapPermit2() → payer signs → swapPermit2Build()
The swap methods include quoting and routing. Allowance needs one Aggregator request; Permit2 still needs two, with payer signing between them. Approval, simulation and transaction submission are separate. After confirmation, submit the same returned prepared or ready object with executeSwap(); do not prepare again in the submit handler.
Rename methods
PeachClient
prepareSwap()
swap()
PeachClient
prepareDirectSwap()
swapAllowance()
PeachClient
prepareDelegatedSwap()
swapPermit2()
PeachClient
buildDelegatedSwap()
swapPermit2Build()
The old names remain deprecated compatibility aliases with matching parameters and return types. PeachClient.swap() is not deprecated: in 0.5.0 it selects by payer/executor roles and returns a Direct/Delegated union. Use swapAllowance() when you need a fixed PreparedDirectSwap type.
Update fields and imports
from, target
Unchanged
amountIn
amount
options.providers, options.depth, options.splitCount
Top-level providers, depth, splitCount
options.customFee.feeAccount, options.customFee.feeBps
customFeeReceiver, customFeeBps
quote.amountOut (net output)
prepared.expectAmountOut
quote.route.totalAmountOut (gross output)
prepared.amountOut
quote.route.routes[0].steps
Allowance prepared.raw.paths; the path shape differs
No signed minimum in the old quote
Allowance prepared.tx.amountOutMin
Do not display gross prepared.amountOut as recipient output. For Permit2, tx is available only after build; its minimum is validated against signed calldata at that stage. See Quotes and Routing for result fields and Delegated Swaps for the signing boundary.
Remove ProtocolType imports and use provider strings returned by getAvailableProviders(). RouteDiscovery is no longer exported; the swap methods obtain routes and transaction data together.
HTTP endpoint migration
GET /router/swap
GET /router/swap/allowance
GET /router/swap/prepare
GET /router/swap/permit2
POST /router/swap/build
POST /router/swap/permit2/build
Permit2 build still sends only quote_id and payer_signature in a JSON body. See the BSC HTTP API for request and response schemas.
Migration checklist
Remove the standalone quote prerequisite and apply the field mappings above.
Prepare with the real executor. Allowance requires
payer = executor; Permit2 requires a different payer and an explicit recipient.Keep the correct approval target: the returned Allowance spender, or canonical Permit2 for delegated input.
Reuse the accepted result. After order changes or expiry, prepare and confirm again, including a new Permit2 signature. Prevent duplicate submission and inspect uncertain sends before retrying. See Transaction Safety.
find_routes, getQuote() and ApiClient.findRoutes() remain available for compatibility. find_routes is planned for future deprecation; no removal date is announced. Its parameters remain in the legacy quote reference.
Last updated
Was this helpful?