
py-stellar-base
Teaches AI coding agents how to build Stellar blockchain applications using stellar-sdk: transactions, operations, Horizon API, Soroban smart contracts, XDR/SCVal, async workflows, and SEP protocols.
- version
- 17.0.1
- GitHub stars
- 370
Install
/plugin install py-stellar-base@stellarcnRun it inside Claude Code after adding the marketplace with /plugin marketplace add StellarCN/py-stellar-base.
Contents
Discovered from sourceSkills 1
Stellar Python SDK (stellar-sdk)
Write correct Python for the Stellar network using the stellar-sdk package. This file is
self-contained; load a file from references/ only when the task needs that topic.
Install
pip install stellar-sdk # core (sync)
pip install "stellar-sdk[aiohttp]" # adds async clients (ServerAsync, SorobanServerAsync, ...)
pip install "stellar-sdk[shamir]" # adds Shamir secret sharing
Import style
Prefer the top-level package for public APIs:
from stellar_sdk import Keypair, Asset, Network, Server, TransactionBuilder, scval
Use submodules for SEP and contract helpers:
from stellar_sdk.contract import ContractClient, AssembledTransaction
from stellar_sdk.sep import stellar_web_authentication, stellar_toml
Sync-first
Default to the synchronous Server and SorobanServer. Use ServerAsync,
SorobanServerAsync, and ContractClientAsync only when the surrounding app is async or
the user asks for async. See references/async.md.
Critical rules (do not violate)
- String amounts, never floats.
"350.1234567", not350.1234567. Lumens have 7 decimal places; floats lose precision. - Never hardcode secret seeds. Load from env / a secret manager:
Keypair.from_secret(os.environ["STELLAR_SECRET_KEY"]). - Always set a timeout with
.set_timeout(...)(or explicit time bounds). A transaction without one can hang in the pending pool indefinitely. - Use the correct network passphrase.
Network.TESTNET_NETWORK_PASSPHRASEvsNetwork.PUBLIC_NETWORK_PASSPHRASE. Signatures are network-specific. TransactionBuilder.build()increments the source account's sequence number. If you build but do not submit (or submission fails withtx_bad_seq), reload the account withserver.load_account(...)before building again.- For Soroban, simulate/prepare before signing.
server.prepare_transaction(tx)(orAssembledTransaction.simulate()) fills in footprint, auth, and resource fees. Signing before this produces an invalid transaction. - Convert contract args with
scval.to_*and read results withscval.from_*/scval.to_native. Never pass raw Python values to a contract. - Restore archived state with
simulate(restore=True)or a restore-footprint op when simulation reports archived entries. - Close async clients with
async withor an explicitawait server.close(). - Catch specific SDK exceptions (
NotFoundError,BadRequestError,PrepareTransactionException, …), not a broadexcept Exception.
Minimal end-to-end examples
1. Create / load a keypair
import os
from stellar_sdk import Keypair
# New random account (fund it before use — see example 2).
kp = Keypair.random()
print(kp.public_key) # G... (safe to share)
print(kp.secret) # S... (secret — never log or commit in real code)
# Load an existing account from the environment.
signer = Keypair.from_secret(os.environ["STELLAR_SECRET_KEY"])
2. Build, sign, and submit a payment
import os
from stellar_sdk import Asset, Keypair, Network, Server, TransactionBuilder
server = Server("https://horizon-testnet.stellar.org")
source_keypair = Keypair.from_secret(os.environ["STELLAR_SECRET_KEY"])
destination = "GD2JXEFGEO53CNQ22KN2ICOQ2LOASCABQHAIOMLZV265C246PFKKHPYU"
# Reload right before building so the sequence number is current.
source_account = server.load_account(source_keypair.public_key)
transaction = (
TransactionBuilder(
source_account=source_account,
network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE,
base_fee=100,
)
.add_text_memo("Hello, Stellar!")
.append_payment_op(destination, Asset.native(), "350.1234567") # string amount
.set_timeout(30)
.build()
)
transaction.sign(source_keypair)
response = server.submit_transaction(transaction)
print(response["hash"])
New testnet accounts can be funded by Friendbot:
requests.get("https://friendbot.stellar.org", params={"addr": kp.public_key}).
3. Query Horizon
from stellar_sdk import Server
server = Server("https://horizon.stellar.org")
account = "GB6NVEN5HSUBKMYCE5ZOWSK5K23TBWRUQLZY3KNMXUZ3AQ2ESC4MY4AQ"
# Call builders are chainable; .call() executes the request.
records = server.payments().for_account(account).order(desc=False).limit(10).call()
for record in records["_embedded"]["records"]:
print(record["type"])
4. Invoke a Soroban contract (read-only)
from stellar_sdk import Network, scval
from stellar_sdk.contract import AssembledTransaction, ContractClient
assembled: AssembledTransaction[list[str]] = ContractClient(
"CACZTW72246RA2MOCNKUBRRRRPT26UZ7LXE5ZHH44OGKIMCTQJ74O4D5",
"https://soroban-testnet.stellar.org:443",
Network.TESTNET_NETWORK_PASSPHRASE,
).invoke(
"hello",
[scval.to_symbol("world")],
parse_result_xdr_fn=lambda r: [scval.from_symbol(s) for s in scval.from_vec(r)],
)
print(assembled.result()) # read-only: no signing/submitting needed
For a state-changing call, pass source= and signer= to invoke(...), then
assembled.sign_and_submit(). See references/soroban.md.
Reference index
Load on demand:
references/quickstart.md— install → keypair → fund → payment → query → contract.references/transactions.md— transaction lifecycle, memos, preconditions, fee bump, multisig, XDR round-trips, sequence-number pitfalls.references/operations.md— catalog of every operation and itsappend_*_opbuilder.references/horizon.md— Horizon clients, call builders, pagination, streaming, errors.references/async.md— async clients and patterns (stellar-sdk[aiohttp]).references/soroban.md— Soroban RPC client +ContractClient/AssembledTransaction.references/xdr_scval.md— SCVal conversion,Address(incl. muxedM.../W...), XDR encode/decode, TxRep.references/sep.md— SEP support matrix and common flows (SEP-01/10/45/...).references/security.md— key handling, validation, signing-safety rules.references/troubleshooting.md— exception hierarchy and common failures.
Full API docs: https://stellar-sdk.readthedocs.io/
Sponsors
Details
- Marketplace
- StellarCN/py-stellar-base
- Author
- overcat
- Category
- Development
- License
- Apache-2.0