> For the complete documentation index, see [llms.txt](https://docs.peach.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peach.ag/documentation/bsc/aggregator/editor/migration-guide.md).

# 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](https://docs.peach.ag/documentation/bsc/aggregator/quickstart) for Allowance or [Delegated Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/delegated-execution-with-permit2-witness) 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.&#x20;

### 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](https://docs.peach.ag/documentation/bsc/aggregator/editor/quotes-and-routing) for result fields and [Delegated Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/delegated-execution-with-permit2-witness) 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](https://docs.peach.ag/api-reference/readme) 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](https://docs.peach.ag/documentation/bsc/aggregator/editor/validation-approvals-and-expiry).

`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](https://docs.peach.ag/documentation/bsc/aggregator/editor/quotes-and-routing#legacy-quote-reference).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peach.ag/documentation/bsc/aggregator/editor/migration-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
