This release is a pre-release and may not be stable for production use.
aquarius-sdk
Installation: pip install aquarius-sdk==0.6.0.
Public API HTTP failures raise APIHTTPError, a subclass of AquariusError,
with status_code and retry_after in seconds (None when unavailable).
Response bodies, including draft-error details, are omitted; callers control retries.
The Python SDK for Aquarius — swaps, liquidity, and rewards on Stellar.
Status: 0.6.x — swaps and the liquidity lifecycle are complete and verified with real testnet transactions. Concentrated liquidity position management is available as a beta surface (the contracts are under an ongoing external audit). The API may still change before 1.0.
Swap through a specific pool
client.quote()/swap() route through the path-finding API. To pin a swap to
one pool you trust — your own routing, API independence — quote and swap on the
pool itself; the estimate comes from the router's on-chain estimate_swap:
pool = next(p for p in client.pools_for_pair(XLM, AQUA) if p.fee_bps == 10)
quote = pool.quote(XLM, AQUA, amount_in=100_0000000) # no signer needed
receipt = quote.execute() # swaps in this pool only
# or: pool.swap(XLM, AQUA, amount_in=100_0000000, retries=3)
Exact input only — the router has no single-pool strict-receive; for exact
output use client.quote(..., amount_out=...).
Concentrated liquidity positions (beta)
A position is the key (owner, tick_lower, tick_upper) on the pool contract — no
NFTs, merged on re-deposit, at most 20 ranges per account. Quotes come from the
contract's own estimators; execute/withdraw_position derive real slippage
guards from them:
pool = next(p for p in aqua.pools_for_pair(XLM, AQUA) if p.type == "concentrated")
est = pool.estimate_position_deposit(
{XLM: 10_0000000, AQUA: 100_0000000},
price_range=("0.9", "1.1"), # snaps to tick spacing; or tick_range=(lower, upper)
)
opened = est.execute(slippage=0.01) # min-liquidity guard from the estimate
pool.position_ranges() # all of the signer's ranges
pool.position_range_status(est.tick_lower, est.tick_upper) # in_range / below / above
pool.position_value(est.tick_lower, est.tick_upper) # principal / fees / total, split
pool.claim_position_fees(est.tick_lower, est.tick_upper)
pool.withdraw_position(est.tick_lower, est.tick_upper) # full close, auto-claims fees
tick_from_price, price_at_tick, and snap_tick are exported for range math —
integer-exact and identical across both language packages.
Requires stellar-sdk>=17.0.0,<18 with Protocol 30 support.
pip install aquarius-sdk
from stellar_sdk import Keypair
from aquarius import AquariusClient, Asset, XLM, SlippageError
AQUA = Asset.classic("AQUA", "GBNZ...AQUA")
aqua = AquariusClient(network="mainnet", signer=Keypair.from_secret(secret))
# exact input: quote, inspect, execute
quote = aqua.quote(XLM, AQUA, amount_in=100_0000000, slippage=0.01)
receipt = quote.execute()
# exact output: pass amount_out instead — strict-receive throughout
quote = aqua.quote(XLM, AQUA, amount_out=500_0000000)
Provider fees
Pass the collector configuration with the quote. The SDK keeps the fee math exact, routes through the collector, and sends output to recipient without requiring that address to sign:
from aquarius import ProviderFeeConfig
provider_fee = ProviderFeeConfig(
contract_id="C...",
fee_fraction=30, # 30 / fee_denominator=10_000 -> 0.3% of the output
fee_denominator=10_000,
recipient="G...",
)
quote = aqua.quote(
XLM,
AQUA,
amount_in=100_0000000,
slippage=0.005,
provider_fee=provider_fee,
)
receipt = quote.execute()
Omit recipient to send output back to the signer through the collector's legacy swap methods. Use amount_out instead of amount_in for an exact-output provider swap.
Liquidity
pools = aqua.pools_for_pair(XLM, AQUA) # discovered on-chain, sorted by type and fee
pool = pools[0] # Pool(type="volatile", fee_bps=10, ...)
result = pool.deposit({XLM: 50_0000000, AQUA: 2500_0000000}, slippage=0.01)
print(result.shares) # pool share tokens minted
pool.pending_rewards() # accrued AQUA, in stroops
pool.claim_rewards()
pool.withdraw(result.shares, slippage=0.01)
aqua.positions() # every pool where the signer holds shares
Deposit and withdrawal guards come from a simulation of the exact call, reduced by slippage — quoted-versus-executed drift is bounded the same way as for swaps. Reads (reserves(), pending_rewards(), pools_for_pair()) need no signer.
A withdraw or claim right after a deposit into a pool with rewards should first wait for the next ledger:
result = pool.deposit({XLM: 50_0000000, AQUA: 2500_0000000})
aqua.wait_for_next_ledger() # past the ledger that applied the deposit
pool.withdraw(result.shares)
Simulation runs on the latest ledger's state, but a transaction applies in a
later one. The rewards contract rewrites the user's reward entry only when
rewards accrued since the user's last checkpoint, so a withdraw simulated on
the deposit's own ledger declares that entry read-only and fails on-chain once
time has advanced. wait_for_next_ledger(ledger=None, timeout=30.0) waits until
the RPC's latest ledger is past ledger — by default the ledger of the client's
last on-chain transaction (confirmed or failed), or, if there is none, the
current one — polling getHealth about once a second, and returns the latest
ledger observed; it raises AquariusError on timeout. The SDK never waits on
its own.
Programmatic on-chain limit orders
Security migration in 0.6.0: create_onchain_limit_order() and
validate_onchain_limit_order_draft() now require expected_executor_reward_xlm.
Obtain it from get_limit_order_executor_reward() on the trusted settlement and
have the caller approve it before creating the order; never copy it from the
registry draft. The SDK compares the draft's canonical fee to that approved
value and reads the settlement fee again before building or placing.
If the fee changes or cannot be read, the operation stops before signing.
Each token's approval defaults to the amount this order needs (the XLM sale
amount plus the fee when selling XLM). To preserve a larger shared allowance,
pass an explicit max_allowances={token_contract: approved_total} ceiling.
The SDK rejects existing or required allowances above that ceiling, without
silently reducing or renewing them. Omitted token ceilings default to this
order's requirement. Set the allowance expiration explicitly as described below.
Receive-trustline support in Python 0.6.0a6:
registry validation accepts both the legacy proof and the exact
trust(maker) + input/reward transfer proof. The latter needs the upgraded
settlement for missing classic trustlines; it retains the same order body and ID.
An old proof cannot gain trustline permission after signing.
For programmatic placement from a G account, passing a classic receive asset
(code and issuer) automatically prepends trust to the same approvals/placement
batch, covered by one transaction signature. Native assets and assets known only by contract ID do not add trust.
Lower-level draft builders automatically add the call when buy_asset=Asset.classic(code, issuer)
is passed to validate_onchain_limit_order_draft (JavaScript: buyAsset in the
validation context). There is no auto-trust opt-in or opt-out flag. The builder
derives the SAC address from code/issuer and the validated network passphrase,
and rejects mismatched metadata. Direct OnchainLimitOrder construction also
requires network_passphrase (JavaScript: networkPassphrase) for a classic
receive asset. SAC itself handles an existing line or contract maker as a no-op
and rejects unsupported issuer receivers.
Creation still requires account reserve and issuer approval where applicable.
When migrating from earlier alphas, remove auto_trust / autoTrust
arguments. Direct JavaScript OnchainLimitOrder construction no longer has the
boolean parameter before buyAsset; prefer the validated draft/client methods.
The examples below target 0.6.0. Configure trusted
settlement and batcher addresses for CONTRACT_ONCHAIN placement:
import os
from aquarius import (
AquariusClient,
LimitOrderConfig,
NoRouteError,
XLM,
parse_find_path_response,
)
aqua = AquariusClient(
network="testnet",
signer=signer,
limit_orders=LimitOrderConfig(
settlement=os.environ["AQUARIUS_LIMIT_ORDER_SETTLEMENT"],
batcher=os.environ["AQUARIUS_BATCHER"],
),
)
current_ledger = aqua.latest_ledger()
expected_reward = aqua.get_limit_order_executor_reward()
# Present this fee and the allowance horizon for approval before proceeding.
order = aqua.create_onchain_limit_order(
XLM,
AQUA,
sell_amount=100_0000000,
min_buy_amount=500_0000000,
valid_after_ledger=current_ledger,
expires_at_ledger=current_ledger + 17_280,
expected_executor_reward_xlm=expected_reward,
allowance_expiration_ledger=current_ledger + 17_280,
)
receipt = order.place()
allowance_expiration_ledger is explicit because SEP-41 allowance() does not
return the existing expiration. Keep it at or beyond this order and every other
open order sharing the settlement allowance. It does not affect the order ID.
For custom C accounts, use validate_onchain_limit_order_draft() and
build_onchain_placement_args() with the account's own authorization policy.
These lower-level helpers do not query the network: supply an independently
approved fee and recheck the settlement before signing.
The existing contract is unchanged. A fee change after the transaction is signed
can still leave an unfillable order and its bounded allowance; the SDK never
silently increases the approved fee to compensate.
batcher is required only for CONTRACT_ONCHAIN placement. Registry reads,
cancellation, and filling need the trusted settlement address:
aqua = AquariusClient(
network="testnet",
signer=signer,
limit_orders=LimitOrderConfig(
settlement=os.environ["AQUARIUS_LIMIT_ORDER_SETTLEMENT"],
),
)
orders = aqua.open_limit_orders(maker=signer.public_key)
order = aqua.get_limit_order(orders[0].order_id)
order.cancel()
An independent filler can request an exact-send route and prepare execution:
response = aqua.api.find_path(
{
"token_in_address": order.order.sell_token,
"token_out_address": order.order.buy_token,
"amount": str(order.order.sell_amount),
},
exact_input=True,
)
route = parse_find_path_response(
response,
amount_in=order.order.sell_amount,
slippage_bps=0,
pair_label=f"{order.order.sell_token} -> {order.order.buy_token}",
)
xlm_token = XLM.contract_id(aqua.network.passphrase)
if route.amount_out < order.order.required_router_min(xlm_token):
raise NoRouteError("Current route does not meet the order minimum")
prepared = order.prepare_fill(route.swap_chain_xdr)
result = prepared.execute()
The existing generic path lookup and parser are reused unchanged. Route lookup
and limit policy are separate primitives. Before returning prepared, the SDK
validates the registry record, detached
ADDRESS_V2 invocation tree or confirmed on-chain placement, settlement
receipt, maker minimum, exact execution fee, and maximum transaction fee.
Preparation uses enforced authorization, preserves the maker's signed proof, and applies the configured CPU and resource fee headroom before checking that the maximum transaction fee is below the execution reward. A restore preamble aborts fill preparation without signing or submitting. Unsigned placement and cancellation builders also never sign or submit a restore transaction.
The prepared receipt is a simulation preview. Execution returns the validated receipt from the confirmed transaction and fails if that receipt is absent or violates the order's payout commitments.
Use the registry's current network and product lifetime limits. Expiration must
be at or below current_ledger + max_entry_ttl - 1, including for orders whose
valid-after ledger is in the future. The allowance horizon must satisfy the
network's current allowance limit and cover the order. Annual orders are not
supported by the agreed one-signature flow.
Split swaps (next release)
An exact-input swap that the backend splits across routes runs as one call to
the router's swap_split. find_path_split returns one plan, split or not. The
SDK checks it, then builds the call with the user's whole authorization:
swap_split with all its arguments and the one input transfer.
from aquarius import (
normalize_swap_split_plan, get_swap_minimum, build_swap_split_operation,
load_swap_resource_limits, assert_swap_authorization, assert_swap_resources,
get_swap_split_result,
)
response = aqua.api.find_path_split(
{"token_in_address": token_in, "token_out_address": token_out, "amount": amount_in}
)
plan = normalize_swap_split_plan(response, token_in, token_out, amount_in)
minimum = get_swap_minimum(plan.amount_out, "1") # percent: "1" = 1%
operation = build_swap_split_operation(
source=source, router=aqua.network.router, token_in=token_in,
token_out=token_out, plan=plan, minimum=minimum,
)
limits = load_swap_resource_limits(server, network_passphrase)
# Your code: simulate once with this fixed authorization, reject restore or
# error results, and assemble the unsigned transaction.
tx, events, retval, ledger = simulate_and_assemble(operation)
assert_swap_authorization(tx, source, operation.to_xdr_object().to_xdr())
if ledger < limits.latest_ledger:
raise ValueError("Stale simulation")
assert_swap_resources(tx, limits, {"events": events, "retval": retval})
output = get_swap_split_result(retval)
# Show the plan, minimum, output and fee before signing.
normalize_swap_split_plan raises NoRouteError without a route, and
ValueError("Invalid swap quote: <failed check>") for a plan that does not
match the request or the router's execution of it: ask for a new quote, there
is no fallback. It checks the requested input, stage shares (integers summing
to 10000), every chain token by token from token_in through each stage to
token_out, each part's input against the router's allocation of its stage
input, outputs that add up to the next stage's input (within u128) and to
amount_out, and that stages_xdr is the encoding of the readable stages the
builder encodes. A plan has at most 4 stages, 4 parts per stage and 4 hops per
chain. pools and tokens are display data from the API: the signed call is
built only from the validated token addresses, pool indexes, shares and
amounts.
The minimum comes from your slippage on the quoted amount_out, never from the
API's amount_out_min. To authorize the output trustline inside the swap, pass
trustline={"asset_code": ..., "issuer": ..., "network_passphrase": ...} and
omit batch. The builder verifies the asset is token_out and nests trust
under the swap authorization. The updated contract opens missing lines atomically;
XLM, WASM tokens, issuers, contract recipients and existing lines need no new line.
A missing line requires the recipient's authorization and XLM reserve; issuer
authorization restrictions still apply. Read get_swap_split_result(retval).
For provider fees, pass the same ProviderFeeConfig as provider_fee to
get_swap_minimum(plan.amount_out, slippage, provider_fee) and
build_swap_split_operation. The quote is gross; the minimum and returned
amount are net of one fee rounded up on the total. An explicit recipient selects
swap_split_to. Missing-line authorization is supported only for source;
a different recipient needs an existing line or separately supplied authorization.
Use the collector's actual fee denominator and cap. Existing collectors are not
upgradeable: split swaps require a newly deployed compatible collector, as well
as the updated router. Publishing the SDK does not upgrade either contract.
Use aqua.assemble_transaction(transaction, operation, simulation) after your
successful simulation to preserve the fixed operation and apply SDK CPU and
resource-fee headroom; then check the assembled envelope's resources. It does
not simulate again, sign, submit or restore storage.
Explicit batch retains legacy external [trust, swap_split] behavior; only
that mode uses get_swap_split_result(retval, with_trustline=True).
Install this prerelease with pip install aquarius-sdk==0.7.0a1.
What the SDK handles for you
- Routing — quotes come from the find-path API; the swap chain XDR is passed through untouched.
- Transaction lifecycle — simulation, assembly, submission with congestion retries (same-hash resubmission with backoff), and confirmation polling.
- Fixed authorization — every contract write and unsigned transaction uses client-built authorization trees. Preparation simulates in
enforcemode, uses the response for resources, and preserves the exact operation and auth through restore and sequence retries. RPC-returned auth is never added, including when the supplied list is empty. - Archived state — if simulation reports expired ledger entries, the SDK restores them (one extra signed transaction) and retries automatically.
- Typed errors —
SlippageError(withrequote()),PausedError(kill switches — not your bug),NoRouteError,UserRejectedError,TxTimeoutError.
Signers
A stellar-sdk Keypair works as-is. Custom signers provide public_key plus sign(tx_xdr) -> str returning the signed envelope XDR. Reads — quote() — need no signer at all.
Escape hatches
quote.build_transaction() returns the simulated, unsigned envelope XDR for external signing flows, with the same fixed authorization as execute(). client.api is the typed REST client.
client.contract_call(fn, *scvals) invokes the router raw and authorizes only
that exact root call with source-account credentials. Raw calls that previously
relied on simulation to discover nested permissions must now provide those
permissions explicitly with auth=[...], or use the corresponding high-level
method such as pool.deposit(). An incomplete tree fails during enforced
simulation before the contract transaction is signed.
For example, an explicit raw reward claim mirrors the router and pool calls:
from stellar_sdk import scval
from aquarius.authorization import authorized_invocation, source_account_entry
user = scval.to_address(public_key) # the transaction source account
args = [
user,
scval.to_vec([scval.to_address(token) for token in pool.tokens]),
scval.to_bytes(pool.pool_hash),
]
entry = source_account_entry(authorized_invocation(
aqua.network.router, "claim", args,
[authorized_invocation(pool.address, "claim", [user])],
))
aqua.contract_call("claim", *args, auth=[entry])
Pass auth=[] when the call requires no authorization; the empty list remains
empty after assembly. Reads and estimates can still use recording simulation,
but their recorded auth never enters a transaction for signing. Archived-state
restoration remains a separate footprint operation when a signer is available.
Infrastructure
Defaults point at the protocol's own endpoints: the mainnet RPC is
https://soroban-rpc.aqua.network — the same node the Aquarius web app and
backend use. Running your own infrastructure? Every endpoint is overridable:
aqua = AquariusClient(
network="mainnet",
rpc_url="https://your-rpc.example.com",
horizon_url="https://your-horizon.example.com",
)
Fees
base_fee (default 100_000 stroops) is the inclusion fee bid. On top of it,
every Soroban transaction declares a resource fee taken from simulation, raised
by resource_fee_headroom (default 0.5, i.e. +50%; 0 disables):
aqua = AquariusClient(network="mainnet", signer=signer, resource_fee_headroom=0.3)
The declared resource fee is a cap: the network charges the non-refundable part
plus the refundable part actually consumed (rent, events, return value) and
refunds the rest, so headroom costs nothing unless it is used. The refundable
part depends on ledger state at apply time, so the bare simulated fee can fall
short and fail the transaction on-chain with
INVOKE_HOST_FUNCTION_INSUFFICIENT_REFUNDABLE_FEE. The headroom is applied
before signing (also to automatic restore transactions and to
quote.build_transaction()), so wallets see and sign the final fee.
The source account must hold the full declared fee — inclusion fee plus
resource fee plus headroom: it is debited before execution, and the unused part
is refunded after apply. When spending the whole XLM balance, leave that margin.
Re-preparing the XDR from quote.build_transaction() with stellar-sdk's own
prepare_transaction re-simulates and replaces the resource fee, which drops the
headroom.
Declared CPU instructions are a hard limit too: a transaction that needs more
than it declares fails on-chain with
INVOKE_HOST_FUNCTION_RESOURCE_LIMIT_EXCEEDED, and actual usage can exceed the
simulated count by several percent. So the simulated instructions are raised by
instruction_headroom (default 0.25, i.e. +25%; 0 disables), capped at the
network's per-transaction limit (read from the network config and cached), and
the resource fee by the compute fee of the added instructions — non-refundable,
under 0.0001 XLM for a typical swap at current mainnet rates — before the fee
headroom is applied on top. Restore transactions run no contract code and keep
the simulated instructions.
aqua = AquariusClient(network="mainnet", signer=signer, instruction_headroom=0.4)
Amounts
All amounts are integers in token base units (stroops for classic assets: 1 token = 10^7).
Questions and integration help: Discord.
Maintenance
misty-forest maintains the Aquarius SDK, including security review, vulnerability remediation, and ongoing development.
Metadata
Release files for aquarius-sdk 0.7.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aquarius_sdk-0.7.0a1.tar.gz | 103.3 kB | With provenance | Details for aquarius_sdk-0.7.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aquarius_sdk-0.7.0a1-py3-none-any.whl | Python 3 | none | any | Details for aquarius_sdk-0.7.0a1-py3-none-any.whl |
Total release size: 170.9 kB
Release files / aquarius_sdk-0.7.0a1.tar.gz
| Download URL | aquarius_sdk-0.7.0a1.tar.gz |
|---|---|
| Size | 103.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0423df368f5431fe6b5b3ba1f92608a1ce0fc875d3f0b5974ca603dc5d21e6be
|
|
BLAKE2b-256 checksum How to use checksums |
2e42786cfad1f16f5744a7d5d9d40c052639aeb44ef4f972e61000232fbb5b08
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / aquarius_sdk-0.7.0a1-py3-none-any.whl
| Download URL | aquarius_sdk-0.7.0a1-py3-none-any.whl |
|---|---|
| Size | 67.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6091f62e49e7bbb7b83daf6717e8d8c133a7fd8ec6acb7b1a7fb8e6138efe3f4
|
|
BLAKE2b-256 checksum How to use checksums |
93b486b8d6beb80e0e499d8a333844bb28ab6fc6c44d40dd524c99505ead271e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for aquarius-sdk 0.7.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aquarius_sdk-0.7.0a1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.