Skip to content

Latest commit

 

History

History
 
 

pancake-swap-example

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
templates
templates
 
 
README.md
README.md
 
 
app.py
app.py
 
 
env.example
env.example
 
 
requirements.txt
requirements.txt
 
 
swapper.py
swapper.py
 
 
wallet_utils.py
wallet_utils.py
 
 

README.md

🌬️ PancakeSwap Testnet Python + Web3 Swap Example

A complete starter project that lets you swap tBNB to any token, and BEP-20 to BEP-20 tokens on the BNB Testnet, using either a web UI (TrustWallet) or a Python-based API with mnemonic/private key support.

📅 Table of Contents

  1. Introduction
  2. Project Structure
  3. Flow Overview
  4. Setup Guide
  5. Frontend Swap Usage
  6. Swagger API Usage
  7. Getting a Testnet Wallet & Address
  8. Getting a Router Contract
  9. Getting Testnet tBNB Tokens
  10. Web Swap Walkthrough (Trust Wallet)
  11. API Walkthrough: tBNB ➔ USDC
  12. API Walkthrough: USDC ➔ tCAKE
  13. Note on Wallet Loading

✨ Introduction

This repo demonstrates:

  • Swapping tokens on the BNB Smart Chain (Testnet)
  • Using web3.py and ethers.js
  • Trust Wallet frontend (tBNB ➔ Token)
  • Swagger-based API (tBNB ➔ Token and Token ➔ Token)
  • Secure wallet management via .env (mnemonic or private key)

🌎 Flow Overview (Mermaid Diagram)

graph TD;
    A[User] -->|TrustWallet| B(HTML + ethers.js)
    A -->|API Call| C(Flask + Swagger)
    B --> D{"Router Contract (Testnet)"}
    C --> D
    D -->|Sends Txn| E[BNB Testnet Chain]
    E --> F[BscScan Explorer]
Loading

🗂️ Project Structure

.
├── app.py                 # Flask app + Swagger docs
├── swapper.py             # Core backend swap logic
├── wallet_utils.py        # Load wallet from mnemonic/private key
├── templates/
│   └── index.html         # Simple swap UI with TrustWallet
├── .env.example           # Sample env vars
├── requirements.txt       # Python deps

⚙️ Setup Guide

# 1. Clone and install
pip install -r requirements.txt

# 2. Copy and fill .env
cp .env.example .env
# Set either MNEMONIC= or PRIVATE_KEY=

# 3. Run the app
python app.py

# 4. Open:
http://localhost:5000       # Web UI
http://localhost:5000/apidocs  # Swagger API

📉 Frontend Swap UI

  • Navigate to http://localhost:5000
  • Connect Trust Wallet / TrustWallet
  • Select a token to buy (e.g. tCAKE)
  • Enter amount in tBNB
  • Click Swap

All transactions go through:

Router: 0x9ac64cc6e4415144c455bd8e4837fea55603e5c3 (Testnet)
  • The router is a smart contract that acts as the main entry point for interacting with PancakeSwap (see it as a Pancake API Gateway).
  • The router used here is the testnet Pancake Router, if you are deploying to production environment, remember to update it with the mainnet router address.

📆 API Swap Usage (via Swagger)

Visit http://localhost:5000/apidocs to test:

/swap (tBNB ➔ Token)

POST /swap
{
  "token_out": "0x...", // the token address of the token you want to receive
  "amount_bnb": 0.01,
  "slippage": 1,
  "router_address": "0x9ac64cc6e4415144c455bd8e4837fea55603e5c3"
}
  • Pools are designed to pair WBNB ➔ Token, thus behind the scenes, we have to convert your tBNB to WBNB before swapping to your desired token.

/token-swap (Token ➔ Token)

POST /token-swap
{
  "token_in": "0x...", // the token address of the token you want to swap
  "token_out": "0x...", // the token address of the token you want to receive
  "amount_in": 0.1,
  "slippage": 1,
  "router_address": "0x9ac64cc6e4415144c455bd8e4837fea55603e5c3"
}
  • Pools are designed to pair WBNB ➔ Token, thus behind the scenes, we have to convert your token_in to WBNB before swapping to your desired token_out. This is unless you are swapping to WBNB, the function will directly swap to WBNB.

🚀 Getting Testnet Wallet & Address

  1. Visit https://chainlist.org/?testnets=true&search=bsc
  2. Add BNB Smart Chain Testnet to TrustWallet
  3. Create a wallet and copy your address

🏠 Getting a Testnet Swap Contract (Router)

You can use the PancakeSwap router on testnet:

0x9ac64cc6e4415144c455bd8e4837fea55603e5c3

⛽️ Getting tBNB Tokens

  1. Go to a BNB faucet:
  2. Paste your testnet wallet address
  3. Request a small amount of tBNB

🕹️ Web Swap Walkthrough (Trust Wallet)

  1. Open the this app (http://localhost:5000) in your Trust Wallet browser
  2. Connect your wallet (TrustWallet compatible)
  3. Choose your token (e.g. tCAKE)
  4. Enter amount of tBNB to swap
  5. Click Swap
  6. Confirm in wallet & view tx on BscScan

➡️ API Walkthrough: Swap tBNB ➔ USDC

POST /swap
{
  "token_out": "0x64544969ed7ebf5f083679233325356ebe738930", // USDC
  "amount_bnb": 0.05,
  "slippage": 1,
  "router_address": "0x9ac64cc6e4415144c455bd8e4837fea55603e5c3"
}

⚠️ The API automatically wraps BNB into WBNB for the swap path.

🔄 API Walkthrough: Swap USDC ➔ tCAKE

POST /token-swap
{
  "token_in": "0x64544969ed7ebf5f083679233325356ebe738930",   // USDC
  "token_out": "0xFa60D973F7642B748046464e165A65B7323b0DEE", // tCAKE
  "amount_in": 1.0,
  "slippage": 1,
  "router_address": "0x9ac64cc6e4415144c455bd8e4837fea55603e5c3"
}

✅ Automatically routes through WBNB if direct liquidity is missing.

🔐 Note: Wallet Auth (Mnemonic vs Private Key)

You can authenticate the backend wallet in 2 ways:

Option 1: Mnemonic Passphrase

MNEMONIC="twelve word seed phrase here"

Option 2: 256-bit Private Key

PRIVATE_KEY="your_private_key_here"

Update wallet_utils.py to select one.

✨ Credits

  • Powered by Web3.py
  • Router ABI: PancakeSwap v2
  • Frontend: ethers.js + TrustWallet / Trust Wallet
  • Backend: Flask + Swagger + Python

❤️ Contributing

PRs welcome! Want to improve the slippage calc? Add token approval UI? Jump in!