> 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/readme.md).

# Overview

How BSC Aggregator finds routes and prepares swaps for the Execution Router.

Use `@masterpeach/aggregator-sdk` **0.3.0** with ethers v6 to integrate BSC swaps. The Peach API finds routes across supported liquidity and builds transactions for the Peach Execution Router. All quotes and swaps are exact input.

### How it works

1. **Preview:** call `getQuote()` to display prices and routes. It requires no approval or signature and returns no executable transaction.
2. **Trade:** when the user chooses to swap, prepare fresh terms for review, complete any required authorization, optionally simulate, and submit with `executeSwap()`.

Preparation searches again, so the output may differ from the preview. Quote and preparation inputs share `from` / `target`; carry `getQuote()`'s `amountIn` into preparation's `amount` and copy routing settings from `options` to the top level. Review the available terms before authorization. In delegated execution, the signed minimum output is available only after signing and build; [Delegated Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/delegated-execution-with-permit2-witness) explains this limit.

The service builds `to`, `data` and `value` and signs the execution plan. The SDK validates the response; the executor's signer signs and submits the transaction. These are separate signatures. Direct preparation returns transaction data immediately; delegated execution obtains it through `buildDelegatedSwap()` after the payer signs the Permit2 authorization.

### Get started

| Your goal                               | Start here                                                                                                            |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Integrate swaps with an existing signer | [Quickstart](https://docs.peach.ag/documentation/bsc/aggregator/quickstart)                                           |
| Display prices and available routes     | [Quotes and Routing](https://docs.peach.ag/documentation/bsc/aggregator/editor/quotes-and-routing)                    |
| Spend and submit from the same wallet   | [Direct Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/direct-allowance)                            |
| Submit a different payer's swap         | [Delegated Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/delegated-execution-with-permit2-witness) |
| Swap native BNB                         | [Native BNB](https://docs.peach.ag/documentation/bsc/aggregator/editor/direct-allowance/native-bnb)                   |
| Add integrator fees                     | [Fees](https://docs.peach.ag/documentation/bsc/aggregator/editor/fees-slippage-and-settlement)                        |

### Execution flows

<table><thead><tr><th width="166.7890625">Flow</th><th>Roles</th><th>Authorization</th><th>SDK sequence after confirmation</th></tr></thead><tbody><tr><td>Direct Allowance</td><td><code>payer = executor</code>; recipient may differ</td><td>ERC20 allowance to <code>prepared.approvalSpender</code>; none for native input</td><td>Prepare → approval if needed → optional simulation → execute</td></tr><tr><td>Permit2 Witness</td><td><code>payer != executor</code>; recipient required</td><td>ERC20 allowance to Permit2, then payer's EIP-712 signature</td><td>Prepare → base approval if needed → sign → build → optional simulation → execute</td></tr></tbody></table>

The **payer** supplies input tokens, the **executor** submits the swap and pays its gas, and the **recipient** receives the output. The payer pays gas for any ERC20 approval; signing the Permit2 message requires no gas.

### Installation and network

```bash
npm install @masterpeach/aggregator-sdk@0.3.0 ethers@^6
```

Use Node.js 18+ or a modern browser with an ethers-compatible provider. The package supplies ESM, CommonJS and TypeScript declarations.

<table><thead><tr><th width="203.703125">Setting</th><th>BSC Mainnet</th></tr></thead><tbody><tr><td>Chain ID</td><td><code>56</code></td></tr><tr><td>SDK preset</td><td><code>BSC_MAINNET_CONFIG</code></td></tr><tr><td>Preset RPC</td><td><code>https://bsc-dataseed.binance.org</code></td></tr><tr><td>WBNB</td><td><code>0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c</code></td></tr><tr><td>Native BNB sentinel</td><td><code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code>; 18 decimals</td></tr><tr><td>Canonical Permit2</td><td><code>0x000000000022D473030F116dDEE9F6B43aC78BA3</code></td></tr></tbody></table>

Import `NATIVE_TOKEN_ADDRESS` from the SDK to identify native BNB in token parameters. It is a placeholder, not an ERC20 contract. See [Native BNB](https://docs.peach.ag/documentation/bsc/aggregator/editor/direct-allowance/native-bnb) for input/output handling.

Amounts use integer base units (`bigint`). Read each ERC20's decimals before using `ethers.parseUnits()` or `ethers.formatUnits()`. WBNB input requires allowance; native BNB input does not.

### Production API

The SDK defaults to **`https://api.peach.ag`**. Use a BSC Mainnet RPC and wallet signer (chain ID `56`).

The SDK validates router addresses from the execution response. See [Client Configuration](https://docs.peach.ag/documentation/bsc/aggregator/editor/configuration-and-error-handling) to pin them to verified addresses.

Production execution compatibility has not yet been verified for this documentation. Confirm support for the v0.3.0 workflow before enabling trading.

Continue with [Quickstart](https://docs.peach.ag/documentation/bsc/aggregator/quickstart) or the [SDK Reference](https://docs.peach.ag/documentation/bsc/aggregator/editor/configuration-and-error-handling/sdk-reference). For upgrades, see the renamed parameters and removed exports in [Changelog](https://docs.peach.ag/documentation/bsc/aggregator/markdown).


---

# 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/readme.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.