Peach Aggregator SDK

TypeScript SDK for route discovery and PeachExecutionRouter swaps on BSC.

Install

npm install @masterpeach/aggregator-sdk ethers

Version 0.2.0 replaces the legacy swap and Permit2 AllowanceTransfer APIs. getQuote() is display-only; migrate execution to prepareSwap(), simulateSwap(), and executeSwap(). For delegated swaps, use the Permit2 Witness flow below. See the frontend integration guide for the complete migration workflow.

Initialize

Deployment addresses come from Aggregator responses. They do not need to be passed to the constructor.

import { BSC_MAINNET_CONFIG, PeachClient } from '@masterpeach/aggregator-sdk';
import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);
const client = new PeachClient(BSC_MAINNET_CONFIG, provider, {
  api: { baseUrl: 'https://api.cipheron.org' },
});

Display Quote

getQuote() only calls GET /router/find_routes. Its result is for display and route inspection; it does not contain executable calldata.

const quote = await client.getQuote({
  srcToken,
  dstToken,
  amountIn,
  options: {
    depth: 3,
    splitCount: 5,
    providers: ['PANCAKEV3'], // optional; omit for the server's enabled set
  },
});

console.log(quote.amountOut, quote.route, quote.gasEstimate);

The SDK treats provider names as open strings. New Aggregator providers do not require an SDK release.

Direct Allowance

Use this flow when payer === executor. The recipient may be independent.

const signer = await provider.getSigner();
const executor = await signer.getAddress();

const prepared = await client.prepareDirectSwap({
  from: srcToken,
  target: dstToken,
  amount: amountIn,
  executor,
  recipient,
  slippageBps: 50,
  deadlineSecs: 300,
});

const approval = await client.buildDirectApprovalRequest(prepared, executor);
if (approval) {
  const approvalTx = await signer.sendTransaction(approval.tx);
  await approvalTx.wait();
}

const swapTx = await client.executeSwap(prepared, signer);
await swapTx.wait();

For ERC20 input, approval is granted to prepared.approvalSpender, which is validated against the server-built ExecutionPlan. Native input needs no ERC20 approval.

To preflight the exact server transaction after approval, call simulateSwap(prepared, executor) and read receipt.userAmountOut.

Permit2 Witness

Use this flow when payer !== executor. The payer signs the typed data and the executor sends the final transaction.

const prepared = await client.prepareDelegatedSwap({
  from: srcToken,
  target: dstToken,
  amount: amountIn,
  payer,
  executor,
  recipient,
  slippageBps: 50,
  deadlineSecs: 300,
});

const payerSignature = await client.signPayerAuthorization(
  prepared,
  payerSigner,
);
const ready = await client.buildDelegatedSwap(prepared, payerSignature);
const swapTx = await client.executeSwap(ready, executorSigner);
await swapTx.wait();

The payer must first grant the input token's base ERC20 allowance to Permit2. Use checkPermit2BaseAllowance() to inspect it.

Unified Preparation

prepareSwap() chooses the mode from the roles:

const prepared = await client.prepareSwap({
  from,
  target,
  amount,
  payer,
  executor,
  recipient,
  slippageBps: 50,
});

if (prepared.executionMode === 'DIRECT_ALLOWANCE') {
  // optional ERC20 approval, then executeSwap(prepared, executorSigner)
} else {
  // signPayerAuthorization(), buildDelegatedSwap(), then executeSwap()
}

Native Tokens

Use NATIVE_TOKEN_ADDRESS or set nativeIn/nativeOut on prepareSwap(). The SDK sends WBNB to the API and validates the returned native mode and transaction value.

Custom Fees

Display quotes can project a fee using QuoteOptions.customFee. The executable request must carry the same fee explicitly:

const prepared = await client.prepareSwap({
  from,
  target,
  amount,
  payer,
  executor,
  recipient,
  customFeeBps: 20,
  customFeeReceiver: feeReceiver,
});

The SDK validates the server response and sends its to, data, and value unchanged. Changing slippage, deadline, roles, fee, or route requires a new prepareSwap() request.

Security Checks

Before returning or sending a transaction, the SDK validates:

• execution mode and status
• payer, executor, recipient, chain, token, and native mode
• legacy Router response metadata and the ExecutionRouter transaction target
• calldata selector, canonical encoding, plan hash, and route hash
• the settlement-policy hash bound into the signed ExecutionPlan
• Aggregator and payer signatures where applicable
• transaction target and native value

Documentation

• Getting started
• Core flows
• API reference
• Permit2 Witness
• Frontend integration

License

MIT