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

# Quickstart

Get a quote and executable transaction with one allowance request, then confirm and submit.

This Direct swap uses your application's existing signer to supply tokens, submit the transaction and receive the output. For separate payer and executor accounts, see [Delegated Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/delegated-execution-with-permit2-witness).

Call `swapAllowance()` once to obtain the quote, selected paths and validated transaction. Review its terms and submit the same result after confirmation.

### Install and initialize

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

Initialize the client with BSC Mainnet defaults and use an existing ethers v6 `signer` on chain ID 56. See [Overview](https://docs.peach.ag/documentation/bsc/aggregator/readme) for production configuration and service compatibility.

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

const client = new PeachClient(BSC_MAINNET_CONFIG);
```

### Get the quote and transaction

Use the application's `tokenIn`, `tokenOut`, input `amount` and `outputDecimals`. Validate the decimal input and convert it with `ethers.parseUnits(value, inputDecimals)`. `amount` is a positive `bigint` in input-token base units. Obtain output decimals from token metadata; native BNB uses 18.

#### Prepare and review

`swapAllowance()` requests fresh transaction data and a signed execution plan from the Peach API. The SDK validates them; your `signer` later signs and submits the transaction.

```typescript
const executor = await signer.getAddress();
const prepared = await client.swapAllowance({
  from: tokenIn, target: tokenOut, amount, executor,
  slippageBps: 50, // 0.5%; 100 bps = 1%
  deadlineSecs: 300,
});
if (prepared.amountIn !== amount) throw new Error("Prepared input differs from the order");
console.log("Expected output:", ethers.formatUnits(prepared.expectAmountOut, outputDecimals));
console.log("Minimum received:", ethers.formatUnits(prepared.tx.amountOutMin, outputDecimals));
```

Render the logged expected output and minimum received in your confirmation view. **Wait for the user to accept these fresh terms before approval or submission.** Logging them alone is not confirmation.

`prepared.expectAmountOut` is net recipient output; `prepared.tx.amountOutMin` is the signed minimum. Display both with output-token decimals without deducting fees or slippage again. Use the user's chosen `slippageBps`; the returned signed deadline determines validity.

#### Approve and execute

Run this step only for the accepted plan. Do not call `swapAllowance()` again in the submit handler.

```typescript
const approval = await client.buildDirectApprovalRequest(prepared, await signer.getAddress());
if (approval) {
  const approvalTx = await signer.sendTransaction(approval.tx);
  if ((await approvalTx.wait())?.status !== 1) throw new Error("Approval failed");
}
if (prepared.execution.plan.deadline <= BigInt(Math.floor(Date.now() / 1000))) {
  throw new Error("Plan expired; prepare and review a new swap");
}
const tx = await client.executeSwap(prepared, signer);
console.log("Transaction hash:", tx.hash); // Save this before waiting for confirmation.
const receipt = await tx.wait();
if (receipt?.status !== 1) throw new Error("Swap failed");
```

The approval helper skips native BNB and sufficient existing allowance. For ERC20 approval, the helper requests **unlimited allowance** to the validated Execution Router; disclose this in the wallet flow. Wait for approval confirmation before sending the swap.

Optional simulation fits after approval and before `executeSwap()`: call `client.simulateSwap(prepared, prepared.executor)`. Its `userAmountOut` is a current-state estimate, not the final settled amount. See [Direct Swaps](https://docs.peach.ag/documentation/bsc/aggregator/editor/direct-allowance).

### When to prepare again

After order, wallet or network changes, or if approval consumes the plan's validity, prepare and review fresh terms. Keep confirmed allowance where sufficient. Never edit signed fields, and disable duplicate submission while the trade is active.

If a send times out, inspect the transaction hash or wallet nonce before retrying; the transaction may already have been sent. See [Client Configuration](https://docs.peach.ag/documentation/bsc/aggregator/editor/configuration-and-error-handling) for error handling.

### Next steps

See [Quotes and Routing](https://docs.peach.ag/documentation/bsc/aggregator/editor/quotes-and-routing) for prepared quotes and route display, [Slippage](https://docs.peach.ag/documentation/bsc/aggregator/editor/slippage) and [Fees](https://docs.peach.ag/documentation/bsc/aggregator/editor/fees-slippage-and-settlement) for trade settings, and [Transaction Safety](https://docs.peach.ag/documentation/bsc/aggregator/editor/validation-approvals-and-expiry) for validation and expiry. For upgrades, see [Migration Guide](https://docs.peach.ag/documentation/bsc/aggregator/editor/migration-guide).


---

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