python

Soroban AMM Python Client Examples

This folder contains Python scripts showing how to interact with the Soroban AMM contracts using the Stellar Python SDK (stellar-sdk).

It contains examples for the following contracts:

• AMM Pool Contract (client.py)
• Factory Contract (factory_client.py)
• Governance Contract (governance_client.py)
• TWAP Consumer Contract (twap_client.py)

Install

Set up a virtual environment and install the required dependencies:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

---

1. AMM Pool Client (client.py)

Demonstrates adding liquidity, quoting, and executing swaps on a specific pool.

Configure

Set the environment variables before running the script:

export AMM_CONTRACT_ID=<deployed AMM contract id>
export SOURCE_SECRET=<secret key for the transaction source and LP/trader>
export TOKEN_IN_CONTRACT_ID=<token A or token B contract id>
export SWAP_AMOUNT_IN=100000
export SWAP_MIN_OUT=0

Run

python client.py

---

2. Factory Client (factory_client.py)

Demonstrates deploying and querying pools registry via the pool factory.

Configure

Set the environment variables before running the script:

export FACTORY_CONTRACT_ID=<deployed factory contract id>
export SOURCE_SECRET=<secret key for the transaction source and deployer>
export TOKEN_A_CONTRACT_ID=<token A contract id>
export TOKEN_B_CONTRACT_ID=<token B contract id>
export FEE_BPS=30 # Optional, defaults to 30

Run

python factory_client.py

---

3. Governance Client (governance_client.py)

Demonstrates submitting fee proposals, querying proposal status/details, and casting LP-weighted votes (supporting For, Against, and Abstain).

Configure

Set the environment variables before running the script:

export GOV_CONTRACT_ID=<deployed governance contract id>
export SOURCE_SECRET=<secret key for the proposer/voter LP holder>
export PROPOSAL_FEE_BPS=50 # Optional, target pool fee to propose (defaults to 50)
export PROPOSAL_ID=<proposal ID to query/vote on> # Optional, if not set, a new proposal is created
export VOTE_CHOICE=For # Optional: For, Against, or Abstain (defaults to For)

Run

python governance_client.py

---

4. TWAP Consumer Client (twap_client.py)

Demonstrates reading a manipulation-resistant time-weighted average price from the TWAP consumer contract: it saves a price snapshot for a pool, reads the TWAP (single direction and both directions) over a window, optionally validates a real-time spot price against the TWAP, and lists the pools the consumer is tracking.

A TWAP over window_seconds needs a snapshot taken roughly window_seconds ago, so in production save_snapshot is invoked on a schedule (e.g. a keeper every minute). When run once, the read step will report that it needs an earlier snapshot; run the script again after window_seconds has elapsed, or set SAVE_SNAPSHOT=false to read against snapshots saved previously.

Configure

Set the environment variables before running the script:

export TWAP_CONTRACT_ID=<deployed TWAP consumer contract id>
export POOL_CONTRACT_ID=<AMM pool contract id to read prices from>
export SOURCE_SECRET=<secret key for the transaction source / snapshot keeper>
export WINDOW_SECONDS=60 # Optional, TWAP window in seconds (defaults to 60)
export SAVE_SNAPSHOT=true # Optional, set to false to skip saving a snapshot
export SPOT_PRICE=<price, 1_000_000 scale> # Optional, enables spot-vs-TWAP validation
export MAX_DEVIATION_BPS=500 # Optional, allowed spot/TWAP deviation (defaults to 500)

Run

python twap_client.py