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

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

Mode
Before
Now

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

Client
Existing method
Use instead

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

Old quote input or result
Swap equivalent

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

Existing compatible endpoint
Recommended endpoint

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?