> 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/direct-allowance/native-bnb.md).

# Native BNB

Swap native BNB and understand the sentinel address, WBNB and transaction value.

Import `NATIVE_TOKEN_ADDRESS` from `@masterpeach/aggregator-sdk` to identify native BNB. Its value, shown below, is a placeholder rather than an ERC20 contract. `isNativeTokenAddress(address)` recognizes it case-insensitively.

<table><thead><tr><th>Asset</th><th width="394.70703125">Value used in SDK token parameters</th><th>Handling</th></tr></thead><tbody><tr><td>Native BNB</td><td><code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code></td><td>Native balance; 18 decimals; no ERC20 approval for input</td></tr><tr><td>WBNB on BSC Mainnet</td><td><code>0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c</code></td><td>ERC20 balance and allowance</td></tr></tbody></table>

Pass the sentinel as `from` or `target` when quoting or preparing. Read native BNB balance with `provider.getBalance(walletAddress)` and format it with `ethers.formatEther()`. ERC20 helpers such as `getTokenInfo()` and `client.getBalance()` expect token contract addresses; do not pass the sentinel to them or use it as a transaction destination.

Quotes use `amountIn` and preparation uses `amount`. Native input uses 18-decimal BNB base units in both calls. For ERC20 input and BNB output, both amount fields use the input ERC20's decimals.

### Supported swaps

| Input → output          | Direct Swaps                 | Delegated Swaps |
| ----------------------- | ---------------------------- | --------------- |
| ERC20 → ERC20           | Supported                    | Supported       |
| Native BNB → ERC20      | Supported; no ERC20 approval | Unsupported     |
| ERC20 → Native BNB      | Supported                    | Supported       |
| Native BNB → Native BNB | Rejected                     | Rejected        |

These are SDK capabilities. The selected deployment must also support the mode and have a route.

### Swap BNB

Use the initialized `client` and your signer's address as the executor, as in [Quickstart](https://docs.peach.ag/documentation/bsc/aggregator/quickstart). Preview with the same native sentinel and amount before calling this preparation helper.

```typescript
import { ethers } from "ethers";
import { NATIVE_TOKEN_ADDRESS, PeachClient } from "@masterpeach/aggregator-sdk";

export async function prepareBNBSwap(client: PeachClient, executor: string, tokenOut: string) {
  const prepared = await client.prepareDirectSwap({
    from: NATIVE_TOKEN_ADDRESS,
    target: tokenOut,
    amount: ethers.parseEther("0.01"),
    executor,
    slippageBps: 50, // 0.5%
    deadlineSecs: 300,
  });
  return prepared;
}
```

After preparation, display `prepared.expectAmountOut` and `prepared.tx.amountOutMin` using output-token decimals. Once the user accepts them, follow Quickstart’s approval/submission step; the approval helper returns `undefined` for native input.

For native output, put an ERC20 address in `from` and `NATIVE_TOKEN_ADDRESS` in `target`. Use input-token decimals for the amount. Format BNB output with 18 decimals.

### Addresses and transaction value

The SDK normalizes the native sentinel to configured WBNB for route requests. As a result, `quote.srcToken` / `quote.dstToken` and prepared `tokenIn` / `tokenOut` contain WBNB addresses for native requests. Quotes expose `srcNative` / `dstNative`; prepared plans expose `nativeMode`. Keep the original sentinel in your order state when preparing again.

Preparation also accepts explicit `nativeIn` or `nativeOut` flags; quotes recognize native assets through the sentinel. Use the sentinel consistently across preview and preparation in a basic integration.

Native mode `0` means ERC20 input/output, `1` means native input, and `2` means native output. For native input the validated transaction value equals prepared input; for other modes it is zero. `executeSwap()` preserves that value.

Do not add BNB to an ERC20-input swap or overwrite `tx.value`. Native input requires enough balance for input plus gas. For ERC20 input, the executor still needs BNB for gas, and any payer approval needs gas in the payer's account.


---

# 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/direct-allowance/native-bnb.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.