API Documentation¶
Classes¶
Address¶
-
class
stellar_base.address.
Address
(address=None, secret=None, network='TESTNET', horizon=None)[source]¶ The
Address
object, which represents an address (public key) on Stellar’s network.An
Address
is initialized via a public key string, or derived via a secret seed. The network on which the account exists is also specified, as it is used to verify and set attributes via connecting to Horizon. It mostly exists as a helper class for Horizon operations on a given account ID.Parameters: - address (str) – The address string that represents this
Address
. - secret (str) – The secret seed string that is used to derive the
address for this
Address
. - network (str) – The network to connect to for verifying and retrieving additional attributes from. Must be either ‘PUBLIC’ or ‘TESTNET’.
- horizon (Horizon) – The
Horizon
instance to use for connecting to for additional information for the account to which this address corresponds to.
-
effects
(sse=False, **kwargs)[source]¶ Retrieve the effects JSON from this instance’s Horizon server.
Retrieve the effects JSON response for the account associated with this
Address
.Parameters: sse (bool) – Use the SSE client for connecting to Horizon.
-
get
()[source]¶ Retrieve the account data that corresponds to this
Address
.Retrieve the account data from Horizon for the account that corresponds to this
Address
. Attempt to retrieve the following attributes from Horizon:- Sequence Number
- Balances
- Paging Token
- Thresholds
- Flags
- Signers
- Data
Raises: - AccountNotExistError – If the account does not exist, shown by a 404 response from a Horizon server.
- Exception – If any other problems come up, or if a network connection happens.
-
offers
(**kwargs)[source]¶ Retrieve the offers JSON from this instance’s Horizon server.
Retrieve the offers JSON response for the account associated with this
Address
.Parameters: sse (bool) – Use the SSE client for connecting to Horizon.
-
operations
(sse=False, **kwargs)[source]¶ Retrieve the operations JSON from this instance’s Horizon server.
Retrieve the operations JSON response for the account associated with this
Address
.Parameters: sse (bool) – Use the SSE client for connecting to Horizon.
- address (str) – The address string that represents this
Asset¶
-
class
stellar_base.asset.
Asset
(code, issuer=None)[source]¶ The
Asset
object, which represents an asset and its corresponding issuer on the Stellar network.For more information about the formats used for asset codes and how issuers work on Stellar’s network, see Stellar’s guide on assets.
Parameters: - code (str) – The asset code, in the formats specified in Stellar’s guide on assets.
- issuer (str) – The strkey encoded issuer of the asset. Note if the currency is the native currency (XLM (Lumens)), no issuer is necessary.
-
classmethod
from_xdr
(xdr)[source]¶ Create an
Asset
object from its base64 encoded XDR representation.Parameters: xdr (bytes) – The base64 encoded XDR Asset object. Returns: A new Asset
object from its encoded XDR representation.
-
classmethod
from_xdr_object
(asset_xdr_object)[source]¶ Create a
Asset
from an XDR Asset object.Parameters: asset_xdr_object – The XDR Asset object. Returns: A new Asset
object from the given XDR Asset object.
-
is_native
()[source]¶ Return true if the
Asset
is the native asset.Returns: True if the Asset is native, False otherwise.
-
static
native
()[source]¶ Create a
Asset
with the native currency.Currently, the native currency is Stellar Lumens (XLM)
Returns: A new Asset
representing the native currency on the Stellar network.
Builder¶
-
class
stellar_base.builder.
Builder
(secret=None, address=None, horizon=None, network=None, sequence=None, fee=100)[source]¶ The
Builder
object, which uses the builder pattern to create a list of operations in aTransaction
, ultimately to be submitted as aTransactionEnvelope
to the network via Horizon (seeHorizon
).Parameters: - secret (str) – The base32 secret seed for the source address.
- address (str) – The base32 source address.
- horizon (
Horizon
) – The horizon instance to use for submitting the created transaction. - network (str) – The network string that describes which version of Horizon to use, either the live net (‘PUBLIC’) or the test net (‘TESTNET’). Defaults to TESTNET if an instance of Horizon has not been passed to the horizon param.
- sequence (int) – The sequence number to use for submitting this transaction with (must be the current sequence number of the source account)
- fee (int) – The network base fee is currently set to 100 stroops (0.00001 lumens). Transaction fee is equal to base fee times number of operations in this transaction.
-
add_hash_memo
(memo_hash)[source]¶ Set the memo for the transaction to a new
HashMemo
.Parameters: memo_hash (bytes) – A 32 byte hash to use as the memo. Returns: This builder instance.
-
add_id_memo
(memo_id)[source]¶ Set the memo for the transaction to a new
IdMemo
.Parameters: memo_id (int) – A 64 bit unsigned integer to set as the memo. Returns: This builder instance.
-
add_memo
(memo)[source]¶ Set the memo for the transaction build by this
Builder
.Parameters: memo ( Memo
) – A memo to add to this transaction.Returns: This builder instance.
-
add_ret_hash_memo
(memo_return)[source]¶ Set the memo for the transaction to a new
RetHashMemo
.Parameters: memo_return (bytes) – A 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding. Returns: This builder instance.
-
add_text_memo
(memo_text)[source]¶ Set the memo for the transaction to a new
TextMemo
.Parameters: memo_text (str) – The text for the memo to add. Returns: This builder instance.
-
add_time_bounds
(time_bounds)[source]¶ Add a time bound to this transaction.
Add a the UNIX timestamp, determined by ledger time, of a lower and upper bound of when this transaction will be valid. If a transaction is submitted too early or too late, it will fail to make it into the transaction set. maxTime equal 0 means that it’s not set.
Parameters: time_bounds (list) – A list of two Unix timestamps representing the lower and upper bound of when a given transaction will be valid. Returns: This builder instance.
-
append_account_merge_op
(destination, source=None)[source]¶ Append a
AccountMerge
operation to the list of operations.Parameters: Returns: This builder instance.
-
append_allow_trust_op
(trustor, asset_code, authorize, source=None)[source]¶ Append an
AllowTrust
operation to the list of operations.Parameters: - trustor (str) – The account of the recipient of the trustline.
- asset_code (str) – The asset of the trustline the source account is authorizing. For example, if an anchor wants to allow another account to hold its USD credit, the type is USD:anchor.
- authorize (bool) – Flag indicating whether the trustline is authorized.
- source (str) – The source address that is establishing the trust in the allow trust operation.
Returns: This builder instance.
-
append_create_account_op
(destination, starting_balance, source=None)[source]¶ Append a
CreateAccount
operation to the list of operations.Parameters: Returns: This builder instance.
-
append_create_passive_offer_op
(selling_code, selling_issuer, buying_code, buying_issuer, amount, price, source=None)[source]¶ Append a
CreatePassiveOffer
operation to the list of operations.Parameters: - selling_code (str) – The asset code for the asset the offer creator is selling.
- selling_issuer (str) – The issuing address for the asset the offer creator is selling.
- buying_code (str) – The asset code for the asset the offer creator is buying.
- buying_issuer (str) – The issuing address for the asset the offer creator is selling.
- amount (int) – Amount of the asset being sold. Set to 0 if you want to delete an existing offer.
- price (float) – Decimal representation of the price of 1 unit of selling in terms of buying. For example, if you wanted to sell 30 XLM and buy 5 BTC, the price would be (5 / 30). Note that this does not take a tuple/dict with a numerator/denominator at this time.
- source (str) – The source address that is creating a passive offer on Stellar’s distributed exchange.
Returns: This builder instance.
-
append_hashx_signer
(hashx, signer_weight, source=None)[source]¶ Add a HashX signer to an account.
Add a HashX signer to an account via a
SetOptions <stellar_base.operation.SetOptions
operation. This is a helper function forappend_set_options_op()
.Parameters: Returns: This builder instance.
-
append_inflation_op
(source=None)[source]¶ Append a
Inflation
operation to the list of operations.Parameters: source (str) – The source address that is running the inflation operation. Returns: This builder instance.
-
append_manage_data_op
(data_name, data_value, source=None)[source]¶ Append a
ManageData
operation to the list of operations.Parameters: - data_name (str) – String up to 64 bytes long. If this is a new Name it will add the given name/value pair to the account. If this Name is already present then the associated value will be modified.
- data_value (str, bytes, None) – If not present then the existing Name will be deleted. If present then this value will be set in the DataEntry. Up to 64 bytes long.
- source (str) – The source account on which data is being managed. operation.
Returns: This builder instance.
-
append_manage_offer_op
(selling_code, selling_issuer, buying_code, buying_issuer, amount, price, offer_id=0, source=None)[source]¶ Append a
ManageOffer
operation to the list of operations.Parameters: - selling_code (str) – The asset code for the asset the offer creator is selling.
- selling_issuer (str) – The issuing address for the asset the offer creator is selling.
- buying_code (str) – The asset code for the asset the offer creator is buying.
- buying_issuer (str) – The issuing address for the asset the offer creator is selling.
- amount (int) – Amount of the asset being sold. Set to 0 if you want to delete an existing offer.
- price (float) – Decimal representation of the price of 1 unit of selling in terms of buying. For example, if you wanted to sell 30 XLM and buy 5 BTC, the price would be (5 / 30). Note that this does not take a tuple/dict with a numerator/denominator at this time.
- offer_id (str) – The ID of the offer. 0 for new offer. Set to existing offer ID to update or delete.
- source (str) – The source address that is managing an offer on Stellar’s distributed exchange.
Returns: This builder instance.
-
append_op
(operation)[source]¶ Append an
Operation
to the list of operations.Add the operation specified if it doesn’t already exist in the list of operations of this
Builder
instance.Parameters: operation ( Operation
) – The operation to append to the list of operations.Returns: This builder instance.
-
append_path_payment_op
(destination, send_code, send_issuer, send_max, dest_code, dest_issuer, dest_amount, path, source=None)[source]¶ Append a
PathPayment
operation to the list of operations.Parameters: - destination (str) – The destination address (Account ID) for the payment.
- send_code (str) – The asset code for the source asset deducted from the source account.
- send_issuer (str) – The address of the issuer of the source asset.
- send_max (int) – The maximum amount of send asset to deduct (excluding fees).
- dest_code (str) – The asset code for the final destination asset sent to the recipient.
- dest_issuer (str) – Account address that receives the payment.
- dest_amount (str) – The amount of destination asset the destination account receives.
- path (list) – A list of asset tuples, each tuple containing a (code, issuer_address) for each asset in the path. For the native asset, an empty string is used for the issuer address.
- source (str) – The source address of the path payment.
Returns: This builder instance.
-
append_payment_op
(destination, amount, asset_code='XLM', asset_issuer=None, source=None)[source]¶ Append a
Payment
operation to the list of operations.Parameters: Returns: This builder instance.
-
append_pre_auth_tx_signer
(pre_auth_tx, signer_weight, source=None)[source]¶ Add a PreAuthTx signer to an account.
Add a PreAuthTx signer to an account via a
SetOptions <stellar_base.operation.SetOptions
operation. This is a helper function forappend_set_options_op()
.Parameters: Returns: This builder instance.
-
append_set_options_op
(inflation_dest=None, clear_flags=None, set_flags=None, master_weight=None, low_threshold=None, med_threshold=None, high_threshold=None, home_domain=None, signer_address=None, signer_type=None, signer_weight=None, source=None)[source]¶ Append a
SetOptions
operation to the list of operations.Parameters: - inflation_dest (str) – The address in which to send inflation to on
an
Inflation
operation. - clear_flags (int) – Indicates which flags to clear. For details about the flags, please refer to Stellar’s documentation on Accounts. The bit mask integer subtracts from the existing flags of the account. This allows for setting specific bits without knowledge of existing flags.
- set_flags (int) – Indicates which flags to set. For details about the flags, please refer to Stellar’s documentation on Accounts. The bit mask integer adds onto the existing flags of the account. This allows for setting specific bits without knowledge of existing flags.
- master_weight (int) – Weight of the master key. This account may also add other keys with which to sign transactions using the signer param.
- low_threshold (int) – A number from 0-255 representing the threshold this account sets on all operations it performs that have a low threshold.
- med_threshold (int) – A number from 0-255 representing the threshold this account sets on all operations it performs that have a medium threshold.
- high_threshold (int) – A number from 0-255 representing the threshold this account sets on all operations it performs that have a high threshold.
- home_domain (str) – Sets the home domain of an account. See Stellar’s documentation on Federation.
- signer_address (str) – The address of the new signer to add to the source account.
- signer_type (str) – The type of signer to add to the account. Must be in (‘ed25519PublicKey’, ‘hashX’, ‘preAuthTx’). See Stellar’s documentation for Multi-Sign for more information.
- signer_weight (int) – The weight of the signer. If the weight is 0, the signer will be deleted.
- source (str) – The source address for which options are being set.
Returns: This builder instance.
- inflation_dest (str) – The address in which to send inflation to on
an
-
append_trust_op
(destination, code, limit=None, source=None)[source]¶ Append a
ChangeTrust
operation to the list of operations.Parameters: Returns: This builder instance.
-
federation_payment
(fed_address, amount, asset_code='XLM', asset_issuer=None, source=None)[source]¶ Append a
Payment
operation to the list of operations using federation on the destination address.Translates the destination stellar address to an account ID via
federation
, before creating a new payment operation viaappend_payment_op()
.Parameters: - fed_address (str) – A Stellar Address that needs to be translated into a valid account ID via federation.
- amount (int) – The amount of the currency to send in the payment.
- asset_code (str) – The asset code for the asset to send.
- asset_issuer (str) – The address of the issuer of the asset.
- source (str) – The source address of the payment.
Returns: This builder instance.
-
gen_compliance_xdr
()[source]¶ Create an XDR object representing this builder’s transaction to be sent over via the Compliance protocol (notably, with a sequence number of 0).
Intentionally, the XDR object is returned without any signatures on the transaction.
See Stellar’s documentation on its Compliance Protocol for more information.
-
gen_te
()[source]¶ Generate a
TransactionEnvelope
around the generated Transaction via the list of operations in this instance.Returns: A transaction envelope ready to send over the network. Return type: TransactionEnvelope
-
gen_tx
()[source]¶ Generate a
Transaction
object from the list of operations contained within this object.Returns: A transaction representing all of the operations that have been appended to this builder. Return type: Transaction
-
gen_xdr
()[source]¶ Create an XDR object around a newly generated
TransactionEnvelope
.Returns: An XDR object representing a newly created transaction envelope ready to send over the network.
-
get_sequence
()[source]¶ Get the sequence number for a given account via Horizon.
Returns: The current sequence number for a given account Return type: int
-
import_from_xdr
(xdr)[source]¶ Create a
TransactionEnvelope
via an XDR object.In addition, sets the fields of this builder (the transaction envelope, transaction, operations, source, etc.) to all of the fields in the provided XDR transaction envelope.
Parameters: xdr – The XDR object representing the transaction envelope to which this builder is setting its state to.
-
next_builder
()[source]¶ Create a new builder based off of this one with its sequence number incremented.
Returns: A new Builder instance Return type: Builder
-
sign
(secret=None)[source]¶ Sign the generated
TransactionEnvelope
from the list of this builder’s operations.Parameters: secret (str) – The secret seed to use if a key pair or secret was not provided when this class was originaly instantiated, or if another key is being utilized to sign the transaction envelope.
-
sign_preimage
(preimage)[source]¶ Sign the generated transaction envelope using a Hash(x) signature.
Parameters: preimage (str) – The value to be hashed and used as a signer on the transaction envelope.
-
submit
()[source]¶ Submit the generated XDR object of the built transaction envelope to Horizon.
Sends the generated transaction envelope over the wire via this builder’s
Horizon
instance. Note that you’ll typically want to sign the transaction before submitting via the sign methods.Returns: A dict representing the JSON response from Horizon. Raises: HTTPError
Keypair¶
-
class
stellar_base.keypair.
Keypair
(verifying_key, signing_key=None)[source]¶ The
Keypair
object, which represents a signing and verifying key for use with the Stellar network.Instead of instantiating the class directly, we recommend using one of several class methods:
Parameters: - verifying_key (ed25519.VerifyingKey) – The verifying (public) Ed25519 key in the keypair.
- signing_key (ed25519.SigningKey) – The signing (private) Ed25519 key in the keypair.
-
account_xdr_object
()[source]¶ Create PublicKey XDR object via public key bytes.
Returns: Serialized XDR of PublicKey type.
-
address
()[source]¶ Get the public key encoded as a strkey.
See
encode_check()
for more details on the strkey encoding process.Returns: The public key encoded as a strkey. Return type: str
-
classmethod
deterministic
(mnemonic, passphrase='', lang='english', index=0)[source]¶ Generate a
Keypair
object via a deterministic phrase.Using a mnemonic, such as one generated from
StellarMnemonic
, generate a new keypair deterministically. UsesStellarMnemonic
internally to generate the seed from the mnemonic, using PBKDF2.Parameters: - mnemonic (str) – A unique string used to deterministically generate keypairs.
- passphrase (str) – An optional passphrase used as part of the salt during PBKDF2 rounds when generating the seed from the mnemonic.
- lang (str) – The language of the mnemonic, defaults to english.
- index (int) –
The index of the keypair generated by the mnemonic. This allows for multiple Keypairs to be derived from the same mnemonic, such as:
>>> from stellar_base import Keypair >>> m = 'hello world' # Don't use this mnemonic in practice. >>> kp1 = Keypair.deterministic(m, lang='english', index=0) >>> kp2 = Keypair.deterministic(m, lang='english', index=1) >>> kp3 = Keypair.deterministic(m, lang='english', index=2)
Returns: A new
Keypair
instance derived from the mnemonic.
-
classmethod
from_address
(address)[source]¶ Generate a
Keypair
object via a strkey encoded public key.Parameters: address (str) – A base32 encoded public key encoded as described in encode_check()
Returns: A new Keypair
with only a verifying (public) key.
-
classmethod
from_base58_seed
(base58_seed)[source]¶ Generate a
Keypair
object via Base58 encoded seed.Deprecated since version 0.1.7: Base58 address encoding is DEPRECATED! Use this method only for transition to strkey encoding.
Parameters: base58_seed (str) – A base58 encoded encoded secret seed. Returns: A new Keypair
derived from the secret seed.
-
classmethod
from_raw_seed
(raw_seed)[source]¶ Generate a
Keypair
object via a sequence of bytes.Typically these bytes are random, such as the usage of
os.urandom()
inKeypair.random()
. However this class method allows you to use an arbitrary sequence of bytes, provided the sequence is 32 bytes long.Parameters: raw_seed (bytes) – A bytes object used as the seed for generating the keypair. Returns: A new Keypair
derived by the raw secret seed.
-
classmethod
from_seed
(seed)[source]¶ Generate a
Keypair
object via a strkey encoded seed.Parameters: seed (str) – A base32 encoded secret seed string encoded as described in encode_check()
.Returns: A new Keypair
instance derived by the secret seed.
-
raw_public_key
()[source]¶ Get the bytes that comprise the verifying (public) key.
Returns: The verifying key’s bytes.
-
raw_seed
()[source]¶ Get the bytes of the signing key’s seed.
Returns: The signing key’s secret seed as a byte sequence. Return type: bytes
-
seed
()[source]¶ Get the secret seed encoded as a strkey.
See
encode_check()
for more details on the strkey encoding process.Returns: The secret seed encoded as a strkey. Return type: str
-
sign
(data)[source]¶ Sign a bytes-like object using the signing (private) key.
Parameters: data (bytes) – The data to sign Returns: The signed data Return type: bytes
-
sign_decorated
(data)[source]¶ Sign a bytes-like object and return the decorated signature.
Sign a bytes-like object by signing the data using the signing (private) key, and return a decorated signature, which includes the last four bytes of the public key as a signature hint to go along with the signature as an XDR DecoratedSignature object.
Parameters: data (bytes) – A sequence of bytes to sign, typically a transaction.
-
signature_hint
()[source]¶ Get the signature hint derived from the public key in this
Keypair
.Get the last four bytes of the public key to be used as a signature hint when utilizing decorated signatures.
Memo¶
-
class
stellar_base.memo.
Memo
[source]¶ The
Memo
object, which represents the base class for memos for use with Stellar transactions.The memo for a transaction contains optional extra information about the transaction taking place. It is the responsibility of the client to interpret this value.
See the following implementations that serve a more practical use with the library:
NoneMemo
- No memo.TextMemo
- A string encoded using either ASCII or UTF-8, up to- 28-bytes long.
IdMemo
- A 64 bit unsigned integer.HashMemo
- A 32 byte hash.RetHashMemo
- A 32 byte hash intended to be interpreted as the- hash of the transaction the sender is refunding.
See Stellar’s documentation on Transactions for more information on how memos are used within transactions, as well as information on the available types of memos.
-
class
stellar_base.memo.
TextMemo
(text)[source]¶ The
TextMemo
, which represents MEMO_TEXT in a transaction.Parameters: text (str) – A string encoded using either ASCII or UTF-8, up to 28-bytes long.
-
class
stellar_base.memo.
IdMemo
(memo_id)[source]¶ The
IdMemo
which represents MEMO_ID in a transaction.Parameters: memo_id (int) – A 64 bit unsigned integer.
-
class
stellar_base.memo.
HashMemo
(memo_hash)[source]¶ The
HashMemo
which represents MEMO_HASH in a transaction.Parameters: memo_hash (bytes) – A 32 byte hash.
-
class
stellar_base.memo.
RetHashMemo
(memo_return)[source]¶ The
RetHashMemo
which represents MEMO_RETURN in a transaction.MEMO_RETURN is typically used with refunds/returns over the network - it is a 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding.
Parameters: memo_return (bytes) – A 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding.
Network¶
-
class
stellar_base.network.
Network
(passphrase=None)[source]¶ The
Network
object, which represents a Stellar network.This class represents such a stellar network such as the public livenet and the Stellar Development Foundation Test network.
Parameters: passphrase (str) – The passphrase for the network
Operation¶
-
class
stellar_base.operation.
Operation
(opts)[source]¶ The
Operation
object, which represents an operation on Stellar’s network.An operation is an individual command that mutates Stellar’s ledger. It is typically rolled up into a transaction (a transaction is a list of operations with additional metadata).
Operations are executed on behalf of the source account specified in the transaction, unless there is an override defined for the operation.
For more on operations, see Stellar’s documentation on operations as well as Stellar’s List of Operations, which includes information such as the security necessary for a given operation, as well as information about when validity checks occur on the network.
The
Operation
class is typically not used, but rather one of its subclasses is typically included in transactions.Parameters: opts (dict) – A dict of options for creating this Operation
. By default, this only pulls out the source account via opts.source.-
classmethod
from_xdr
(xdr)[source]¶ Create the appropriate
Operation
subclass from the XDR structure.Decode an XDR base64 encoded string and create the appropriate
Operation
object.Parameters: xdr (str) – The XDR object to create an Operation
(or subclass) instance from.
-
static
from_xdr_amount
()[source]¶ Converts an amount from an XDR object into its appropriate integer representation.
Each asset amount is encoded as a signed 64-bit integer in the XDR structures. An asset amount unit (that which is seen by end users) is scaled down by a factor of ten million (10,000,000) to arrive at the native 64-bit integer representation. For example, the integer amount value 25,123,456 equals 2.5123456 units of the asset. This scaling allows for seven decimal places of precision in human-friendly amount units.
This static method correctly divides the value by the scaling factor in order to get the proper units of the asset.
See Stellar’s documentation on Asset Precision for more information.
Parameters: value (int) – The amount to convert to a string from an XDR int64 amount.
-
static
to_xdr_amount
()[source]¶ Converts an amount to the appropriate value to send over the network as a part of an XDR object.
Each asset amount is encoded as a signed 64-bit integer in the XDR structures. An asset amount unit (that which is seen by end users) is scaled down by a factor of ten million (10,000,000) to arrive at the native 64-bit integer representation. For example, the integer amount value 25,123,456 equals 2.5123456 units of the asset. This scaling allows for seven decimal places of precision in human-friendly amount units.
This static method correctly multiplies the value by the scaling factor in order to come to the integer value used in XDR structures.
See Stellar’s documentation on Asset Precision for more information.
Parameters: value (str) – The amount to convert to an integer for XDR serialization.
-
classmethod
Transaction¶
-
class
stellar_base.transaction.
Transaction
(source, opts)[source]¶ The
Transaction
object, which represents a transaction on Stellar’s network.A transaction contains a list of operations (see
Operation
), which are all executed in order as one ACID transaction, along with an associated source account, fee, account sequence number, list of signatures, both an optional memo and an optional timebound. Typically aTransaction
is placed in aTransactionEnvelope
which is then signed before being sent over the network.For more information on Transactions in Stellar, see Stellar’s guide on transactions.
Parameters: - source (str) – A strkey encoded account ID (public key) of the source account for the transaction.
- opts (dict) –
A dict that contains the primary components of the transaction. The following keys are searched from the dict:
- opts.sequence - The current sequence number of the source account. The sequence number is incremented by 1 automatically, as is necessary for a new transaction for a given source account.
- opts.time_bounds - A list of two Unix timestamps representing the lower and upper bound of when a given transaction will be valid. NOTE: This should likely be an object containing a minTime and maxTime attribute instead, and the implementation may change.
- opts.memo - The memo being sent with the transaction, being
represented as one of the subclasses of the
Memo
object. Defaults toNoneMemo
. - opts.fee - The fee amount for the transaction, which should equal BASE_FEE (currently 100 stroops) multiplied by the number of operations in the transaction. See Stellar’s latest documentation on fees for more information.
- opts.operations: A list of
Operation
objects (typically its subclasses as defined instellar_base.operation
to be included in the transaction. By default this is an empty list.
-
add_operation
(operation)[source]¶ Add an
Operation
to this transaction.This method will only add an operation if it is not already in the transaction’s list of operations, i.e. every operation in the transaction should be unique.
Parameters: operation (Operation) – The operation to add to this transaction.
-
classmethod
from_xdr_object
(tx_xdr_object)[source]¶ Create a
Transaction
object from a Transaction XDR object.
-
to_xdr_object
()[source]¶ Creates an XDR Transaction object that represents this
Transaction
.
-
xdr
()[source]¶ Packs and base64 encodes this
Transaction
as an XDR string.
TransactionEnvelope¶
-
class
stellar_base.transaction_envelope.
TransactionEnvelope
(tx, opts=None)[source]¶ The
TransactionEnvelope
object, which represents a transaction envelope ready to sign and submit to send over the network.When a transaction is ready to be prepared for sending over the network, it must be put into a
TransactionEnvelope
, which includes additional metadata such as the signers for a given transaction. Ultimately, this class handles signing and conversion to and from XDR for usage on Stellar’s network.Parameters: - tx (
Transaction
) – The transaction that is encapsulated in this envelope. - opts (dict) –
Additional options, such as:
- opts.signatures, which contains a list of signatures that have already been created.
- opts.network_id, which contains the network ID for which network this transaction envelope is associated with.
-
classmethod
from_xdr
(xdr)[source]¶ Create a new
TransactionEnvelope
from an XDR string.Parameters: xdr (bytes) – The XDR string that represents a transaction envelope.
-
hash_meta
()[source]¶ Get the XDR Hash of the signature base.
This hash is ultimately what is signed before transactions are sent over the network. See
signature_base()
for more details about this process.Returns: The XDR Hash of this transaction envelope’s signature base.
-
sign
(keypair)[source]¶ Sign this transaction envelope with a given keypair.
Note that the signature must not already be in this instance’s list of signatures.
Parameters: keypair ( Keypair
) – The keypair to use for signing this transaction envelope.Raises: SignatureExistError
-
sign_hashX
(preimage)[source]¶ Sign this transaction envelope with a Hash(X) signature.
See Stellar’s documentation on Multi-Sig for more details on Hash(x) signatures.
Parameters: preimage (str) – The “x” value to be hashed and used as a signature.
-
signature_base
()[source]¶ Get the signature base of this transaction envelope.
Return the “signature base” of this transaction, which is the value that, when hashed, should be signed to create a signature that validators on the Stellar Network will accept.
It is composed of a 4 prefix bytes followed by the xdr-encoded form of this transaction.
Returns: The signature base of this transaction envelope.
-
to_xdr_object
()[source]¶ Get an XDR object representation of this
TransactionEnvelope
.
-
xdr
()[source]¶ Get the base64 encoded XDR string representing this
TransactionEnvelope
.
- tx (
List of Operations¶
Create Account¶
-
class
stellar_base.operation.
CreateAccount
(opts)[source]¶ The
CreateAccount
object, which represents a Create Account operation on Stellar’s network.This operation creates and funds a new account with the specified starting balance.
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this CreateAccount
. This class pulls a ‘source’, ‘destination’, and ‘starting_balance’ via opts.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
CreateAccount
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
CreateAccount
.
-
classmethod
Payment¶
-
class
stellar_base.operation.
Payment
(opts)[source]¶ The
Payment
object, which represents a Payment operation on Stellar’s network.Sends an amount in a specific asset to a destination account.
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this Payment
. This class pulls a ‘source’, ‘destination’, ‘asset’, and ‘amount’ via opts.
Path Payment¶
-
class
stellar_base.operation.
PathPayment
(opts)[source]¶ The
PathPayment
object, which represents a PathPayment operation on Stellar’s network.Sends an amount in a specific asset to a destination account through a path of offers. This allows the asset sent (e.g., 450 XLM) to be different from the asset received (e.g, 6 BTC).
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this PathPayment
. This class pulls a ‘source’, ‘destination’, ‘send_asset’, ‘send_max’, ‘dest_asset’, ‘dest_amount’, and ‘path’ via opts.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
PathPayment
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
PathPayment
.
-
classmethod
Manage Offer¶
-
class
stellar_base.operation.
ManageOffer
(opts)[source]¶ The
ManageOffer
object, which represents a ManageOffer operation on Stellar’s network.Creates, updates, or deletes an offer.
If you want to create a new offer set Offer ID to 0.
If you want to update an existing offer set Offer ID to existing offer ID.
If you want to delete an existing offer set Offer ID to existing offer ID and set Amount to 0.
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this ManageOffer
. This class pulls several of the following from opts: ‘source’, ‘selling’, ‘buying’, ‘amount’, ‘price’, ‘offer_id’.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
ManageOffer
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
ManageOffer
.
-
classmethod
Create Passive Offer¶
-
class
stellar_base.operation.
CreatePassiveOffer
(opts)[source]¶ The
CreatePassiveOffer
object, which represents a CreatePassiveOffer operation on Stellar’s network.A passive offer is an offer that does not act on and take a reverse offer of equal price. Instead, they only take offers of lesser price. For example, if an offer exists to buy 5 BTC for 30 XLM, and you make a passive offer to buy 30 XLM for 5 BTC, your passive offer does not take the first offer.
Note that regular offers made later than your passive offer can act on and take your passive offer, even if the regular offer is of the same price as your passive offer.
Passive offers allow market makers to have zero spread. If you want to trade EUR for USD at 1:1 price and USD for EUR also at 1:1, you can create two passive offers so the two offers don’t immediately act on each other.
Once the passive offer is created, you can manage it like any other offer using the manage offer operation - see
ManageOffer
for more details.Parameters: opts (dict) – A dict of options for creating this CreatePassiveOffer
. This class pulls several of the following from opts: ‘source’, ‘selling’, ‘buying’, ‘amount’, ‘price’.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
CreatePassiveOffer
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
CreatePassiveOffer
.
-
classmethod
Set Options¶
-
class
stellar_base.operation.
SetOptions
(opts)[source]¶ The
SetOptions
object, which represents a SetOptions operation on Stellar’s network.This operation sets the options for an account.
For more information on the signing options, please refer to the multi-sig doc.
When updating signers or other thresholds, the threshold of this operation is high.
Threshold: Medium or High
Parameters: opts (dict) – A dict of options for creating this SetOptions
. This class pulls several of the following depending on the option: a ‘source’, ‘inflation_dest’, ‘clear_flags’, ‘set_flags’, ‘master_weight’, ‘low_threshold’, ‘med_threshold’, ‘high_threshold’, ‘home_domain’, ‘signer_address’, ‘signer_type’, ‘signer_weight’ via opts.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
SetOptions
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
SetOptions
.
-
classmethod
Change Trust¶
-
class
stellar_base.operation.
ChangeTrust
(opts)[source]¶ The
ChangeTrust
object, which represents a ChangeTrust operation on Stellar’s network.Creates, updates, or deletes a trustline. For more on trustlines, please refer to the assets documentation <https://www.stellar.org/developers/guides/concepts/assets.html>_.
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this ChangeTrust
. This class pulls a ‘source’, ‘asset’, and optionally a ‘limit’ via opts.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
ChangeTrust
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
ChangeTrust
.
-
classmethod
Allow Trust¶
-
class
stellar_base.operation.
AllowTrust
(opts)[source]¶ The
AllowTrust
object, which represents a AllowTrust operation on Stellar’s network.Updates the authorized flag of an existing trustline. This can only be called by the issuer of a trustline’s asset.
The issuer can only clear the authorized flag if the issuer has the AUTH_REVOCABLE_FLAG set. Otherwise, the issuer can only set the authorized flag.
Threshold: Low
Parameters: opts (dict) – A dict of options for creating this AllowTrust
. This class pulls a ‘source’, ‘trustor’, ‘asset_code’, and ‘authorize’ via opts.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
AllowTrust
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
AllowTrust
.
-
classmethod
Account Merge¶
-
class
stellar_base.operation.
AccountMerge
(opts)[source]¶ The
AccountMerge
object, which represents a AccountMerge operation on Stellar’s network.Transfers the native balance (the amount of XLM an account holds) to another account and removes the source account from the ledger.
Threshold: High
Parameters: opts (dict) – A dict of options for creating this AccountMerge
. This class pulls several of the following from opts: ‘source’, ‘destination’-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
AccountMerge
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
AccountMerge
.
-
classmethod
Inflation¶
-
class
stellar_base.operation.
Inflation
(opts)[source]¶ The
Inflation
object, which represents a Inflation operation on Stellar’s network.This operation runs inflation.
Threshold: Low
Parameters: opts (dict) – A dict of options for creating this Inflation
. This class pulls several of the following from opts: ‘source’.
Manage Data¶
-
class
stellar_base.operation.
ManageData
(opts)[source]¶ The
ManageData
object, which represents a ManageData operation on Stellar’s network.Allows you to set,modify or delete a Data Entry (name/value pair) that is attached to a particular account. An account can have an arbitrary amount of DataEntries attached to it. Each DataEntry increases the minimum balance needed to be held by the account.
DataEntries can be used for application specific things. They are not used by the core Stellar protocol.
Threshold: Medium
Parameters: opts (dict) – A dict of options for creating this ManageData
. This class pulls several of the following from opts: ‘source’, ‘data_name’, ‘data_value’.-
classmethod
from_xdr_object
(op_xdr_object)[source]¶ Creates a
ManageData
object from an XDR Operation object.
-
to_xdr_object
()[source]¶ Creates an XDR Operation object that represents this
ManageData
.
-
classmethod
Federation¶
-
exception
stellar_base.federation.
FederationError
[source]¶ A
FederationError
that represents an issue stemming from Stellar Federation.
-
stellar_base.federation.
federation
(address_or_id, fed_type='name', domain=None, allow_http=False)[source]¶ Send a federation query to a Stellar Federation service.
For more info, see the complete guide on Stellar Federation..
Parameters: - address_or_id (str) – The address which you expect te retrieve federation information about.
- fed_type (str) – The type of federation query that you are making. Must be ‘name’, ‘id’, ‘forward’, or ‘txid’.
- domain (str) – The domain that corresponds to the address or ID; this is where the stellar.toml file lives (which ultimately points to the URL of the federation service).
- allow_http (bool) – Whether to allow for requests over plain HTTP over HTTPS. Note - you should always use HTTPS outside of testing.
Return dict: The federation query response decoded from JSON as a dict.
-
stellar_base.federation.
get_auth_server
(domain, allow_http=False)[source]¶ Retrieve the AUTH_SERVER config from a domain’s stellar.toml.
Parameters: Return str: The AUTH_SERVER url.
-
stellar_base.federation.
get_federation_service
(domain, allow_http=False)[source]¶ Retrieve the FEDERATION_SERVER config from a domain’s stellar.toml.
Parameters: Return str: The FEDERATION_SERVER url.
Horizon¶
-
class
stellar_base.horizon.
Horizon
(horizon=None, sse=False, timeout=20)[source]¶ -
account
(address, **kwargs)[source]¶ Returns information and links relating to a single account.
Parameters: address (str) – The account ID to retrieve details about Returns: The account details in a JSON response Return type: dict
-
account_data
(account_id, data_key, **kwargs)[source]¶ This endpoint represents a single data associated with a given account.
GET /accounts/{account}/data/{key}
Parameters: Returns: The value of the data field for the given account and data key
Return type:
-
account_effects
(address, params=None, sse=None, **kwargs)[source]¶ This endpoint represents all effects that changed a given account.
GET /accounts/{account}/effects{?cursor,limit,order}
Parameters: Returns: The list of effects in a JSON response.
Return type:
-
account_offers
(address, params=None, **kwargs)[source]¶ This endpoint represents all the offers a particular account makes.
GET /accounts/{account}/offers{?cursor,limit,order}
Parameters: Returns: The list of offers for an account in a JSON response.
Return type:
-
account_operations
(address, params=None, sse=None, **kwargs)[source]¶ This endpoint represents all operations that were included in valid transactions that affected a particular account.
GET /accounts/{account}/operations{?cursor,limit,order}
Parameters: Returns: The list of operations for an account in a JSON response.
Return type:
-
account_payments
(address, params=None, sse=None, **kwargs)[source]¶ This endpoint responds with a collection of Payment operations where the given account was either the sender or receiver.
GET /accounts/{id}/payments{?cursor,limit,order}
Parameters: Returns: The list of payments for an account in a JSON response.
Return type:
-
account_transactions
(address, params=None, sse=None, **kwargs)[source]¶ This endpoint represents all transactions that affected a given account.
GET /accounts/{account_id}/transactions{?cursor,limit,order}
Parameters: Returns: The list of transactions for an account in a JSON response.
Return type:
-
assets
(params=None, **kwargs)[source]¶ This endpoint represents all assets. It will give you all the assets in the system along with various statistics about each.
See the documentation below for details on query parameters that are available.
GET /assets{?asset_code,asset_issuer,cursor,limit,order}
Parameters: params (dict) – The query parameters to pass to this request, such as cursor, order, and limit. Returns: A list of all valid payment operations Return type: dict
-
effects
(params=None, sse=None, **kwargs)[source]¶ This endpoint represents all effects.
GET /effects{?cursor,limit,order}
Parameters: Returns: A list of all effects
Return type:
-
ledger
(ledger_id, **kwargs)[source]¶ The ledger details endpoint provides information on a single ledger.
Parameters: ledger_id (int) – The id of the ledger to look up Returns: The details of a single ledger Return type: dict
-
ledger_effects
(ledger_id, params=None, **kwargs)[source]¶ This endpoint represents all effects that occurred in the given ledger.
GET /ledgers/{id}/effects{?cursor,limit,order}
Parameters: Returns: The effects for a single ledger
Return type:
-
ledger_operations
(ledger_id, params=None, **kwargs)[source]¶ This endpoint returns all operations that occurred in a given ledger.
GET /ledgers/{id}/operations{?cursor,limit,order}
Parameters: Returns: The operations contained in a single ledger
Return type:
-
ledger_payments
(ledger_id, params=None, **kwargs)[source]¶ This endpoint represents all payment operations that are part of a valid transactions in a given ledger.
GET /ledgers/{id}/payments{?cursor,limit,order}
Parameters: Returns: The payments contained in a single ledger
Return type:
-
ledger_transactions
(ledger_id, params=None, **kwargs)[source]¶ This endpoint represents all transactions in a given ledger.
GET /ledgers/{id}/transactions{?cursor,limit,order}
Parameters: Returns: The transactions contained in a single ledger
Return type:
-
ledgers
(params=None, sse=None, **kwargs)[source]¶ This endpoint represents all ledgers.
GET /ledgers{?cursor,limit,order}
Parameters: params (dict) – The query parameters to pass to this request, such as cursor, order, and limit. Returns: All ledgers on the network. Return type: dict
-
operation
(op_id, **kwargs)[source]¶ The operation details endpoint provides information on a single operation.
Parameters: op_id (id) – The operation ID to get details on. Returns: Details on a single operation Return type: dict
-
operation_effects
(op_id, params=None, **kwargs)[source]¶ This endpoint represents all effects that occurred as a result of a given operation.
GET /operations/{id}/effects{?cursor,limit,order}
Parameters: Returns: A list of effects on the given operation
Return type:
-
operations
(params=None, sse=None, **kwargs)[source]¶ This endpoint represents all operations that are part of validated transactions.
GET /operations{?cursor,limit,order}
Parameters: Returns: A list of all operations
Return type:
-
order_book
(params=None, **kwargs)[source]¶ Return, for each orderbook, a summary of the orderbook and the bids and asks associated with that orderbook.
See the external docs below for information on the arguments required.
Parameters: params (dict) – The query parameters to pass to this request. Returns: A list of orderbook summaries as a JSON object. Return type: dict
-
paths
(params=None, **kwargs)[source]¶ Load a list of assets available to the source account id and find any payment paths from those source assets to the desired destination asset.
See the below docs for more information on required and optional parameters for further specifying your search.
Parameters: params (dict) – The query parameters to pass to this request, such as source_account, destination_account, destination_asset_type, etc. Returns: A list of paths that can be used to complete a payment based on a given query. Return type: dict
-
payments
(params=None, sse=None, **kwargs)[source]¶ This endpoint represents all payment operations that are part of validated transactions.
GET /payments{?cursor,limit,order}
Parameters: Returns: A list of all valid payment operations
Return type:
-
submit
(te, **kwargs)[source]¶ Submit a transaction to Horizon.
Uses form-encoded data to send over to Horizon.
Parameters: te (bytes) – The transaction envelope to submit Returns: The JSON response indicating the success/failure of the submitted transaction. Return type: dict
-
trade_aggregations
(params=None, **kwargs)[source]¶ Load a list of aggregated historical trade data, optionally filtered by an orderbook.
Parameters: params (dict) – The query parameters to pass to this request, such as start_time, end_time, base_asset_type, counter_asset_type, order, limit, etc. Returns: A list of collected trade aggregations Return type: dict
-
trades
(params=None, **kwargs)[source]¶ Load a list of trades, optionally filtered by an orderbook.
See the below docs for more information on required and optional parameters for further specifying your search.
Parameters: params (dict) – The query parameters to pass to this request, such as base_asset_type, counter_asset_type, cursor, order, limit, etc. Returns: A list of trades filtered by a given query Return type: dict
-
transaction
(tx_hash, **kwargs)[source]¶ The transaction details endpoint provides information on a single transaction.
Parameters: tx_hash (str) – The hex-encoded transaction hash Returns: A single transaction’s details Return type: dict
-
transaction_effects
(tx_hash, params=None, **kwargs)[source]¶ This endpoint represents all effects that occurred as a result of a given transaction.
GET /transactions/{hash}/effects{?cursor,limit,order}
Parameters: Returns: A single transaction’s effects
Return type:
-
transaction_operations
(tx_hash, params=None, **kwargs)[source]¶ This endpoint represents all operations that are part of a given transaction.
GET /transactions/{hash}/operations{?cursor,limit,order}
Parameters: Returns: A single transaction’s operations
Return type:
-
transaction_payments
(tx_hash, params=None, **kwargs)[source]¶ This endpoint represents all payment operations that are part of a given transaction.
GET /transactions/{hash}/payments{?cursor,limit,order}
Parameters: Returns: A single transaction’s payment operations
Return type:
-
transactions
(params=None, sse=None, **kwargs)[source]¶ This endpoint represents all validated transactions.
GET /transactions{?cursor,limit,order}
Parameters: Returns: The list of all transactions
Return type:
-