# Elixir Stellar SDK
[](https://coveralls.io/github/kommitters/stellar_sdk)
[](https://hexdocs.pm/stellar_sdk)
[](https://github.com/kommitters/stellar_sdk/blob/main/LICENSE.md)
[](https://bestpractices.coreinfrastructure.org/projects/6367)
[](https://api.securityscorecards.dev/projects/github.com/kommitters/stellar_sdk)
The **Stellar SDK** enables the construction, signing and encoding of Stellar [transactions][stellar-docs-tx] and [operations][stellar-docs-list-operations] in **Elixir**, as well as provides a client for interfacing with [Horizon][horizon-api] server REST endpoints to retrieve ledger information, and to submit transactions.
This library is aimed at developers building Elixir applications that interact with the [**Stellar network**][stellar].
> [!NOTE]
> If you are a smart contract developer building on Soroban, we recommend using [Soroban.ex][soroban.ex], a library built on top of Stellar SDK which offers a developer-friendly interface for interacting with Soroban smart contracts and Soroban-RPC server.
#### Protocol Version Support
| Protocol | Version |
| -------- | ---------- |
| 18 | >= v0.8 |
| 19 | >= v0.9 |
| 20 | >= v0.20 |
| 21 | >= v0.21.2 |
## Documentation
The **Stellar SDK** is composed of two complementary components: **`TxBuild`** + **`Horizon`**.
* **`TxBuild`** - used for [**building transactions.**](#building-transactions)
* **`Horizon`** - used for [**querying Horizon.**](#querying-horizon)
* [**Examples.**](/docs/README.md)
## Installation
[**Available in Hex**][hex], add `stellar_sdk` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:stellar_sdk, "~> 0.22.0"}
]
end
```
## Configuration
The default HTTP Client is `:hackney`. Options to `:hackney` can be passed through configuration params.
```elixir
config :stellar_sdk, hackney_opts: [{:connect_timeout, 1000}, {:recv_timeout, 5000}]
```
### Custom HTTP Client
Stellar allows you to use your HTTP client of choice. Specification in [**Stellar.Horizon.Client.Spec**][http_client_spec]
```elixir
config :stellar_sdk, :http_client_impl, YourApp.CustomClientImpl
```
## Building transactions
### Accounts
Accounts are the central data structure in Stellar. They hold balances, sign transactions, and issue assets. All entries that persist on the ledger are owned by a particular account.
```elixir
# initialize an account
account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
```
### Muxed accounts
A **muxed** (or **multiplexed**) account is an account that exists “virtually” under a traditional Stellar account address. It combines the familiar `GABC...` address with a `64-bit` integer `ID` and can be used to distinguish multiple “virtual” accounts that share an underlying “real” account. More details in [**CAP-27**][stellar-cap-27].
```elixir
# initialize an account with a muxed address
account = Stellar.TxBuild.Account.new("MBXV5U2D67J7HUW42JKBGD4WNZON4SOPXXDFTYQ7BCOG5VCARGCRMAAAAAAAAAAAARKPQ")
account.account_id
# GBXV5U2D67J7HUW42JKBGD4WNZON4SOPXXDFTYQ7BCOG5VCARGCRMQQH
account.muxed_id
# 4
```
#### Create a muxed account
```elixir
# create a muxed account
account = Stellar.TxBuild.Account.create_muxed("GBXV5U2D67J7HUW42JKBGD4WNZON4SOPXXDFTYQ7BCOG5VCARGCRMQQH", 4)
account.address
# MBXV5U2D67J7HUW42JKBGD4WNZON4SOPXXDFTYQ7BCOG5VCARGCRMAAAAAAAAAAAARKPQ
```
### KeyPairs
Stellar relies on public key cryptography to ensure that transactions are secure: every account requires a valid keypair consisting of a public key and a private key.
```elixir
# generate a random key pair
{public_key, secret_seed} = Stellar.KeyPair.random()
# derive a key pair from a secret seed
{public_key, secret_seed} = Stellar.KeyPair.from_secret_seed("SA33J3ACZZCV35FNSS655WXLIPTQOJS6WPQCKKYJSREDQY7KRLECEZSZ")
```
### Transactions
[Transactions][stellar-docs-tx] are commands that modify the ledger state. They consist of a list of operations (up to 100) used to send payments, enter orders into the decentralized exchange, change settings on accounts, and authorize accounts to hold assets.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# initialize a transaction
Stellar.TxBuild.new(source_account) # network_passphrase defaults to Stellar.Network.testnet_passphrase()
# initialize a transaction with options
# allowed options: network_passphrase, memo, sequence_number, base_fee, preconditions
Stellar.TxBuild.new(source_account, network_passphrase: Stellar.Network.public_passphrase(), memo: memo, sequence_number: sequence_number)
```
#### Memos
A [memo][stellar-docs-memo] contains optional extra information for the transaction. Memos can be one of the following types:
* **`MEMO_TEXT`** : A string encoded using either ASCII or UTF-8, up to 28-bytes long.
* **`MEMO_ID`** A 64 bit unsigned integer.
* **`MEMO_HASH`** : A 32 byte hash.
* **`MEMO_RETURN`** : A 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# build a memo
memo = Stellar.TxBuild.Memo.new(:none)
memo = Stellar.TxBuild.Memo.new(text: "MEMO")
memo = Stellar.TxBuild.Memo.new(id: 123_4565)
memo = Stellar.TxBuild.Memo.new(hash: "0859239b58d3f32972fc9124559cea7251225f2dbc6f0d83f67dc041e6608510")
memo = Stellar.TxBuild.Memo.new(return: "d83f67dc041e66085100859239b58d3f32924559cea72512272fc915f2dbc6f0")
# add a memo for the transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_memo(memo)
```
#### Sequence number
Each transaction has a [sequence number][stellar-docs-sequence-number] associated with the source account. Transactions follow a strict ordering rule when it comes to processing transactions per account in order to prevent double-spending.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# fetch next account's sequence number from Horizon
{:ok, seq_num} =
Stellar.Horizon.Accounts.fetch_next_sequence_number(
Stellar.Horizon.Server.testnet(),
"GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW"
)
# set the sequence number
sequence_number = Stellar.TxBuild.SequenceNumber.new(seq_num)
# set the sequence number for the transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.set_sequence_number(sequence_number)
```
#### Base fee
Each transaction incurs a [fee][stellar-docs-fee], which is paid by the source account. When you submit a transaction, you set the maximum that you are willing to pay per operation, but you’re charged the minimum fee possible based on network activity.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# build a fee
base_fee = Stellar.TxBuild.BaseFee.new(1_000)
# set a fee for the transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.set_base_fee(base_fee)
```
#### Preconditions
Proposed on the [Stellar protocol-19][stellar-protocol-19] implementation, [Preconditions][stellar-docs-preconditions] are conditions that determines if a transaction is valid or not, and implements the following conditions:
- **Time bounds**: [TimeBounds][stellar-docs-time-bounds] are optional UNIX timestamps (in seconds), determined by ledger time. A lower and upper bound of when this transaction will be valid.
- **Ledger bounds**: [LedgerBounds][stellar-docs-ledger-bounds] are like Time Bounds, except they apply to ledger numbers. With them set, a transaction will only be valid for ledger numbers that fall into the range you set.
- **Minimum Sequence Number**: [Minimum sequence number][stellar-docs-min-seq-num] if is set, the transaction will only be valid when `S` (the minimum sequence number) satisfies `minSeqNum <= S < tx.seqNum`. If is not set, the default behavior applies (the transaction’s sequence number must be exactly one greater than the account’s sequence number)
- **Minimum Sequence Age**: [Minimum sequence age][stellar-docs-min-seq-age] is based on the account's [sequence number age][stellar-docs-account-seq-num-age]. When is set, the transaction is only valid after a particular duration (in seconds) elapses since the account’s sequence number age.
- **Minimum Sequence Ledger Gap**: [Minimum sequence ledger gap][stellar-docs-min-seq-ledger-gap] is based on the account's [sequence number age][stellar-docs-account-seq-num-age], this is similar to the minimum sequence age, except it’s expressed as a number of ledgers rather than a duration of time.
- **Extra Signers**: A transaction can specify up to two [Extra signers][stellar-docs-extra-signers] (of any type) even if those signatures would not otherwise be required to authorize the transaction.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# TimeBounds ---------------------------------------------------------------------------
# no time bounds for a transaction
time_bounds = Stellar.TxBuild.TimeBounds.new(:none)
# time bounds using UNIX timestamps
time_bounds = Stellar.TxBuild.TimeBounds.new(
min_time: 1_643_558_792,
max_time: 1_643_990_815
)
# time bounds using DateTime
time_bounds = Stellar.TxBuild.TimeBounds.new(
min_time: ~U[2022-01-30 16:06:32.963238Z],
max_time: ~U[2022-02-04 16:06:55.734317Z]
)
# timeout
time_bounds = Stellar.TxBuild.TimeBounds.set_timeout(1_643_990_815)
# LedgerBounds -------------------------------------------------------------------------
# no ledger bounds for a transaction
ledger_bounds = Stellar.TxBuild.LedgerBounds.new(:none)
# ledger bounds with ledger numbers
ledger_bounds = Stellar.TxBuild.LedgerBounds.new(min_ledger: 0, max_ledger: 1_234_567_890)
# SequenceNumber -----------------------------------------------------------------------
# minimum sequence number for a transaction with value 0
min_seq_num = Stellar.TxBuild.SequenceNumber.new()
# minimum sequence number
min_seq_num = Stellar.TxBuild.SequenceNumber.new(1_000_000)
# ExtraSigners
extra_signers = ["GA2YG3YULNTUEMMLN4HUQVL7B37GJTYSRZYH6HZUFLXFDCCGKLXIXMDT"]
# Preconditions ------------------------------------------------------------------------
preconditions =
Stellar.TxBuild.Preconditions.new(
time_bounds: time_bounds,
ledger_bounds: ledger_bounds,
min_seq_num: min_seq_num,
min_seq_age: 30,
min_seq_ledger_gap: 5,
extra_signers: extra_signers
)
# set the preconditions for the transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.set_preconditions(preconditions)
```
#### Operations
[Operations][stellar-docs-list-operations] represent a desired change to the ledger: payments, offers to exchange currency, changes made to account options, etc. Operations are submitted to the Stellar network grouped in a Transaction. Single transactions may have up to 100 operations.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# build a create_account operation
# the destination account does not exist in the ledger
create_account_op = Stellar.TxBuild.CreateAccount.new(
destination: "GDWD36NCYNN4UFX63F2235QGA2XVGTXG7NQW6MN754SHTQM4XSLTXLYK",
starting_balance: 2
)
# build a payment operation
# the destination account should exist in the ledger
payment_op = Stellar.TxBuild.Payment.new(
destination: "GDWD36NCYNN4UFX63F2235QGA2XVGTXG7NQW6MN754SHTQM4XSLTXLYK",
asset: :native,
amount: 5
)
# add a single operation to a transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_operation(create_account_op)
# add multiple operations to a transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_operations([create_account_op, payment_op])
```
#### Signing and multi-sig
Stellar uses [signatures][stellar-docs-tx-signatures] as authorization. Transactions always need authorization from at least one public key in order to be considered valid.
It is possible to use different signature types settled by the `SetOptions` operation into the network.
```elixir
# ed25519
# ed25519 keypair or ed25519 secret key.
signer_key_pair = Stellar.KeyPair.from_secret_seed("SBJJSBBXGKNXALBZ3F3UTHAPKJSESACSKPLW2ZEMM5E5WPVNNKTW55XN")
signature = Stellar.TxBuild.Signature.new(signer_key_pair)
signature = Stellar.TxBuild.Signature.new(ed25519: "SC7SEV3LXAIA727BI3QY67YMHXXNWATIZEW7GY4DUSR6KDVGMF546W7T")
# hash_x
# signatures of type hash(x) require the preimage (x) in hex generated by a 256-bit random value.
signature = Stellar.TxBuild.Signature.new(hash_x: "dea550a5e5897ef98a37a828e183d8d313486159329df646c1137147e766282c")
# signed_payload - {payload, ed25519}
# payload is a hex string, maximum 32 bytes.
# ed25519 is a ed25519 secret key.
signature =
Stellar.TxBuild.Signature.new(
signed_payload: [
payload: "01020304",
ed25519: "SACHJRYLY43MUXRRCRFA6CZ5ZW5JVPPR4CWYWIX6BWRAOHOFVPVYDO5Z"
]
)
```
In some cases, a transaction may need more than one signature. If the transaction has operations with multiple source accounts, it requires the source account signature for each operation. Additional signatures are required if the account associated with the transaction has multiple public keys.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# build an operation
# the destination account should exist in the ledger
operation = Stellar.TxBuild.Payment.new(
destination: "GDWD36NCYNN4UFX63F2235QGA2XVGTXG7NQW6MN754SHTQM4XSLTXLYK",
asset: :native,
amount: 5
)
# build transaction signatures
# signer accounts should exist in the ledger
signature1 = Stellar.TxBuild.Signature.new(ed25519: "SBJJSBBXGKNXALBZ3F3UTHAPKJSESACSKPLW2ZEMM5E5WPVNNKTW55XN")
signature2 = Stellar.TxBuild.Signature.new(ed25519: "SA2NWVOPQMQYAU5RATOE7HJLMPLQZRNPGSOQGGEG6P2ZSYTWFORY5AV5")
# add a single signature to a transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_operation(operation)
|> Stellar.TxBuild.sign(signature1)
# add multiple signatures to a transaction
{:ok, tx_build} =
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_operation(operation)
|> Stellar.TxBuild.sign([signature1, signature2])
```
#### Transaction envelope
Once a transaction has been filled out, it is wrapped in a [Transaction envelope][stellar-docs-tx-envelope] containing the transaction as well as a set of signatures.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# build an operation
# the destination account should exist in the ledger
operation = Stellar.TxBuild.Payment.new(
destination: "GDWD36NCYNN4UFX63F2235QGA2XVGTXG7NQW6MN754SHTQM4XSLTXLYK",
asset: :native,
amount: 5
)
# build the transaction signatures
# signer account should exist in the ledger
signature = Stellar.TxBuild.Signature.new(ed25519: "SBJJSBBXGKNXALBZ3F3UTHAPKJSESACSKPLW2ZEMM5E5WPVNNKTW55XN")
# build a base64 transaction envelope
source_account
|> Stellar.TxBuild.new()
|> Stellar.TxBuild.add_operation(operation)
|> Stellar.TxBuild.sign(signature)
|> Stellar.TxBuild.envelope()
{:ok, "AAAAAgAAAACuy1AULv6LOdXRYjVYl9u0g62aLg/LPRx+KKAgsCUp2wAAAGQAAA+pAAAAFAAAAAAAAAAAAAAAAQAAAAAAAAABAAAAAL5xix0HYeCnnvADhMs2eqCLBfE+WT3Kh7axgdzPzWX0AAAAAAAAAAAC+vCAAAAAAAAAAAKwJSnbAAAAQMhnGfygZvau5bXFHnJ1rCLIiqiZiI+C4Xf4bWCrxTERPOM/nJKuDottj48bep8NlI42WIUgqZVeQAKykWE74AXPzWX0AAAAQHp0wWKyv80frbOkX3QgOFtflxExX9H46b8ws8fMznSt6/9Le567cqoPxLb/SYvw3Wh6j3B5Vl04CBWyKnLYUwg="}
```
#### Submitting a transaction
The transaction can now be submitted to the Stellar network.
```elixir
# set the source account (this account should exist in the ledger)
source_account = Stellar.TxBuild.Account.new("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# fetch next account's sequence number from Horizon
{:ok, seq_num} = Stellar.Horizon.Accounts.fetch_next_sequence_number("GDC3W2X5KUTZRTQIKXM5D2I5WG5JYSEJQWEELVPQ5YMWZR6CA2JJ35RW")
# set the sequence number
sequence_number = Stellar.TxBuild.SequenceNumber.new(seq_num)
# set a memo
memo = Stellar.TxBuild.Memo.new(text: "MEMO")
# build an operation
# the destination account should exist in the ledger
operation = Stellar.TxBuild.Payment.new(
destination: "GDWD36NCYNN4UFX63F2235QGA2XVGTXG7NQW6MN754SHTQM4XSLTXLYK",
asset: :native,
amount: 5
)
# build the transaction signatures
# signer account should exist in the ledger
signature = Stellar.TxBuild.Signature.new(ed25519: "SBJJSBBXGKNXALBZ3F3UTHAPKJSESACSKPLW2ZEMM5E5WPVNNKTW55XN")
# build a base64 transaction envelope
{:ok, base64_envelope} =
source_account
|> Stellar.TxBuild.new(sequence_number: sequence_number)
|> Stellar.TxBuild.add_memo(memo)
|> Stellar.TxBuild.add_operation(operation)
|> Stellar.TxBuild.sign(signature)
|> Stellar.TxBuild.envelope()
# submit transaction to Horizon
{:ok, submitted_tx} = Stellar.Horizon.Transactions.create(base64_envelope)
```
More examples can be found in the [**tests**][sdk-tests].
## Querying Horizon
Horizon is an API for interacting with the Stellar network.
To query Horizon, you need to specify the Horizon server to use.
```elixir
# public horizon server
Stellar.Horizon.Server.public()
# testnet horizon server
Stellar.Horizon.Server.testnet()
# futurenet horizon server
Stellar.Horizon.Server.futurenet()
# local horizon server
Stellar.Horizon.Server.local()
# custom horizon server
Stellar.Horizon.Server.new("https://horizon-standalone.com")
```
See [**Stellar.Horizon.Server**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Server.html) for more details.
To make it possible to explore the millions of records for resources like transactions and operations, this library paginates the data it returns for collection-based resources. Each individual transaction, operation, ledger, etc. is returned as a record.
```elixir
{:ok,
%Ledger{
base_fee_in_stroops: 100,
closed_at: ~U[2015-09-30 17:16:29Z],
failed_transaction_count: 0,
fee_pool: 3.0e-5,
...
}} = Ledgers.retrieve(Stellar.Horizon.Server.testnet(), 1234)
```
A group of records is called a **collection**, records are returned as a list in the [**Stellar.Horizon.Collection**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Collection.html#content) structure. To move between pages of a collection of records, use the `next` and `prev` attributes.
```elixir
{:ok,
%Stellar.Horizon.Collection{
next: #Function<1.1390483/0 in Stellar.Horizon.Collection.paginate/1>,
prev: #Function<1.1390483/0 in Stellar.Horizon.Collection.paginate/1>,
records: [
%Stellar.Horizon.Ledger{...},
%Stellar.Horizon.Ledger{...},
%Stellar.Horizon.Ledger{...}
]
}} = Stellar.Horizon.Ledgers.all(Stellar.Horizon.Server.testnet())
```
### Pagination
The [HAL format links](https://developers.stellar.org/api/introduction/response-format/) returned with the Horizon response are converted into functions you can call on the returned structure. This allows you to simply use `next.()` and `prev.()` to page through results.
```elixir
{:ok,
%Stellar.Horizon.Collection{
next: paginate_next_fn,
prev: paginate_prev_fn,
records: [...]
}} = Stellar.Horizon.Transactions.all(Stellar.Horizon.Server.testnet())
# next page records for the collection
paginate_next_fn.()
{:ok,
%Stellar.Horizon.Collection{
next: paginate_next_fn,
prev: paginate_prev_fn,
records: [...]
}}
# prev page records for the collection
paginate_prev_fn.()
{:ok,
%Stellar.Horizon.Collection{
next: paginate_next_fn,
prev: paginate_prev_fn,
records: []
}}
```
### Accounts
```elixir
# retrieve an account
Stellar.Horizon.Accounts.retrieve(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
# fetch the ledger's sequence number for the account
Stellar.Horizon.Accounts.fetch_next_sequence_number(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
# list accounts
Stellar.Horizon.Accounts.all(
Stellar.Horizon.Server.testnet(),
limit: 10,
order: :asc
)
# list accounts by sponsor
Stellar.Horizon.Accounts.all(
Stellar.Horizon.Server.testnet(),
sponsor: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
# list accounts by signer
Stellar.Horizon.Accounts.all(
Stellar.Horizon.Server.testnet(),
signer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
order: :desc
)
# list accounts by canonical asset address
Stellar.Horizon.Accounts.all(
Stellar.Horizon.Server.testnet(),
asset: "TEST:GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
limit: 20
)
# list account's transactions
Stellar.Horizon.Accounts.list_transactions(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
limit: 20
)
# list account's payments
Stellar.Horizon.Accounts.list_payments(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
limit: 20
)
```
See [**Stellar.Horizon.Accounts**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Accounts.html#content) for more details.
### Transactions
```elixir
# submit a transaction
Stellar.Horizon.Transactions.create(Stellar.Horizon.Server.testnet(), base64_tx_envelope)
# submit a transaction asynchronously
Stellar.Horizon.Transactions.create_async(Stellar.Horizon.Server.testnet(), base64_tx_envelope)
# retrieve a transaction
Stellar.Horizon.Transactions.retrieve(Stellar.Horizon.Server.testnet(), "5ebd5c0af4385500b53dd63b0ef5f6e8feef1a7e1c86989be3cdcce825f3c0cc")
# list transactions
Stellar.Horizon.Transactions.all(Stellar.Horizon.Server.testnet(), limit: 10, order: :asc)
# include failed transactions
Stellar.Horizon.Transactions.all(Stellar.Horizon.Server.testnet(), limit: 10, include_failed: true)
# list transaction's effects
Stellar.Horizon.Transactions.list_effects(
Stellar.Horizon.Server.testnet(),
"6b983a4e0dc3c04f4bd6b9037c55f70a09c434dfd01492be1077cf7ea68c2e4a",
limit: 20
)
# list transaction's operations
Stellar.Horizon.Transactions.list_operations(
Stellar.Horizon.Server.testnet(),
"6b983a4e0dc3c04f4bd6b9037c55f70a09c434dfd01492be1077cf7ea68c2e4a",
limit: 20
)
# join transactions in the operations response
Stellar.Horizon.Transactions.list_operations(
Stellar.Horizon.Server.testnet(),
"6b983a4e0dc3c04f4bd6b9037c55f70a09c434dfd01492be1077cf7ea68c2e4a",
join: "transactions"
)
```
See [**Stellar.Horizon.Transactions**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Transactions.html#content) for more details.
### Operations
```elixir
# retrieve an operation
Stellar.Horizon.Operations.retrieve(Stellar.Horizon.Server.testnet(), 121693057904021505)
# list operations
Stellar.Horizon.Operations.all(Stellar.Horizon.Server.testnet(), limit: 10, order: :asc)
# include failed operations
Stellar.Horizon.Operations.all(Stellar.Horizon.Server.testnet(), limit: 10, include_failed: true)
# include operation's transactions
Stellar.Horizon.Operations.all(Stellar.Horizon.Server.testnet(), limit: 10, join: "transactions")
# list operation's payments
Stellar.Horizon.Operations.list_payments(Stellar.Horizon.Server.testnet(), limit: 20)
# list operation's effects
Stellar.Horizon.Operations.list_effects(Stellar.Horizon.Server.testnet(), 121693057904021505, limit: 20)
```
See [**Stellar.Horizon.Operations**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Operations.html#content) for more details.
### Assets
```elixir
# list ledger's assets
Stellar.Horizon.Assets.all(Stellar.Horizon.Server.testnet(), limit: 20, order: :desc)
# list assets by asset issuer
Stellar.Horizon.Assets.all(Stellar.Horizon.Server.testnet(), asset_issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD")
# list assets by asset code
Stellar.Horizon.Assets.list_by_asset_code(Stellar.Horizon.Server.testnet(), "TEST")
Stellar.Horizon.Assets.all(Stellar.Horizon.Server.testnet(), asset_code: "TEST")
# list assets by asset issuer
Stellar.Horizon.Assets.all(
Stellar.Horizon.Server.testnet(),
asset_issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
Stellar.Horizon.Assets.list_by_asset_issuer(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
```
See [**Stellar.Horizon.Assets**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Assets.html#content) for more details.
### Ledgers
```elixir
# retrieve a ledger
Stellar.Horizon.Ledgers.retrieve(Stellar.Horizon.Server.testnet(), 27147222)
# list ledgers
Stellar.Horizon.Ledgers.all(Stellar.Horizon.Server.testnet(), limit: 10, order: :asc)
# list ledger's transactions
Stellar.Horizon.Ledgers.list_transactions(Stellar.Horizon.Server.testnet(), 27147222, limit: 20)
# list ledger's operations
Stellar.Horizon.Ledgers.list_operations(Stellar.Horizon.Server.testnet(), 27147222, join: "transactions")
# list ledger's payments including failed transactions
Stellar.Horizon.Ledgers.list_payments(Stellar.Horizon.Server.testnet(), 27147222, include_failed: true)
# list ledger's effects
Stellar.Horizon.Ledgers.list_effects(Stellar.Horizon.Server.testnet(), 27147222, limit: 20)
```
See [**Stellar.Horizon.Ledgers**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Ledgers.html#content) for more details.
### Offers
```elixir
# list offers
Stellar.Horizon.Offers.all(Stellar.Horizon.Server.testnet(), limit: 20, order: :asc)
# list offers by sponsor
Stellar.Horizon.Offers.all(
Stellar.Horizon.Server.testnet(),
sponsor: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
# list offers by seller
Stellar.Horizon.Offers.all(
Stellar.Horizon.Server.testnet(),
seller: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
order: :desc
)
# list offers by selling_asset
Stellar.Horizon.Offers.all(
Stellar.Horizon.Server.testnet(),
selling_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
]
)
# list offers by buying_asset
Stellar.Horizon.Offers.all(
Stellar.Horizon.Server.testnet(),
buying_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
]
)
# list offers by selling_asset and buying_asset
Stellar.Horizon.Trades.all(
Stellar.Horizon.Server.testnet(),
selling_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
],
buying_asset: [
code: "TOKEN",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
]
)
Stellar.Horizon.Offers.all(
Stellar.Horizon.Server.testnet(),
selling_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
],
buying_asset: :native
)
# list offer's trades
Stellar.Horizon.Offers.list_trades(Stellar.Horizon.Server.testnet(), 165563085, limit: 20)
```
See [**Stellar.Horizon.Offers**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Offers.html#content) for more details.
### Trades
```elixir
# list tardes
Stellar.Horizon.Trades.all(Stellar.Horizon.Server.testnet(), limit: 20, order: :asc)
# list trades by offer_id
Stellar.Horizon.Trades.all(Stellar.Horizon.Server.testnet(), offer_id: 165563085)
# list trades by specific orderbook
Stellar.Horizon.Trades.all(
Stellar.Horizon.Server.testnet(),
base_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
],
counter_asset: [
code: "TOKEN",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
]
)
Stellar.Horizon.Trades.all(
Stellar.Horizon.Server.testnet(),
base_asset: [
code: "TEST",
issuer: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
],
counter_asset: :native
)
# list trades by trade_type
Stellar.Horizon.Trades.all(Stellar.Horizon.Server.testnet(), trade_type: "liquidity_pools", limit: 20)
```
See [**Stellar.Horizon.Trades**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Trades.html#content) for more details.
### ClaimableBalances
```elixir
# retrieve a claimable balance
Stellar.Horizon.ClaimableBalances.retrieve(
Stellar.Horizon.Server.testnet(),
"00000000ca6aba5fb0993844e0076f75bee53f2b8014be29cd8f2e6ae19fb0a17fc68695"
)
# list claimable balances
Stellar.Horizon.ClaimableBalances.all(Stellar.Horizon.Server.testnet(), limit: 2, order: :asc)
# list claimable balances by sponsor
Stellar.Horizon.ClaimableBalances.list_by_sponsor(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
Stellar.Horizon.ClaimableBalances.all(
Stellar.Horizon.Server.testnet(),
sponsor: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
# list claimable balances by claimant
Stellar.Horizon.ClaimableBalances.list_by_claimant(
Stellar.Horizon.Server.testnet(),
"GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
Stellar.Horizon.ClaimableBalances.all(
Stellar.Horizon.Server.testnet(),
claimant: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
order: :desc
)
# list claimable balances by canonical asset address
Stellar.Horizon.ClaimableBalances.list_by_asset(
Stellar.Horizon.Server.testnet(),
"TEST:GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD"
)
Stellar.Horizon.ClaimableBalances.all(
Stellar.Horizon.Server.testnet(),
asset: "TEST:GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
limit: 20
)
# list claimable balance's transactions
Stellar.Horizon.ClaimableBalances.list_transactions(
Stellar.Horizon.Server.testnet(),
"00000000ca6aba5fb0993844e0076f75bee53f2b8014be29cd8f2e6ae19fb0a17fc68695",
limit: 20
)
# list claimable balance's operations
Stellar.Horizon.ClaimableBalances.list_operations(
Stellar.Horizon.Server.testnet(),
"00000000ca6aba5fb0993844e0076f75bee53f2b8014be29cd8f2e6ae19fb0a17fc68695",
limit: 20
)
# join transactions in the operations response
Stellar.Horizon.ClaimableBalances.list_operations(
Stellar.Horizon.Server.testnet(),
"00000000ca6aba5fb0993844e0076f75bee53f2b8014be29cd8f2e6ae19fb0a17fc68695",
join: "transactions"
)
```
See [**Stellar.Horizon.Balances**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.ClaimableBalances.html#content) for more details.
### LiquidityPools
```elixir
# retrieve a liquidity pool
Stellar.Horizon.LiquidityPools.retrieve(
Stellar.Horizon.Server.testnet(),
"001365fc79ca661f31ba3ee0849ae4ba36f5c377243242d37fad5b1bb8912dbc"
)
# list liquidity pools
Stellar.Horizon.LiquidityPools.all(Stellar.Horizon.Server.testnet(), limit: 2, order: :asc)
# list liquidity pools by reserves
Stellar.Horizon.LiquidityPools.all(
Stellar.Horizon.Server.testnet(),
reserves: "TEST:GCXMW..., TEST2:GCXMW..."
)
# list liquidity pools by account
Stellar.Horizon.LiquidityPools.all(
Stellar.Horizon.Server.testnet(),
account: "GCXMWUAUF37IWOOV2FRDKWEX3O2IHLM2FYH4WPI4PYUKAIFQEUU5X3TD",
order: :desc
)
# list liquidity pool's effects
Stellar.Horizon.LiquidityPools.list_effects(
Stellar.Horizon.Server.testnet(),
"001365fc79ca661f31ba3ee0849ae4ba36f5c377243242d37fad5b1bb8912dbc",
limit: 20
)
# list liquidity pool's trades
Stellar.Horizon.LiquidityPools.list_trades(
Stellar.Horizon.Server.testnet(),
"001365fc79ca661f31ba3ee0849ae4ba36f5c377243242d37fad5b1bb8912dbc",
limit: 20
)
# list liquidity pool's transactions
Stellar.Horizon.LiquidityPools.list_transactions(
Stellar.Horizon.Server.testnet(),
"001365fc79ca661f31ba3ee0849ae4ba36f5c377243242d37fad5b1bb8912dbc",
limit: 20
)
# list liquidity pool's operations
Stellar.Horizon.LiquidityPools.list_operations(
Stellar.Horizon.Server.testnet(),
"001365fc79ca661f31ba3ee0849ae4ba36f5c377243242d37fad5b1bb8912dbc",
limit: 20
)
```
See [**Stellar.Horizon.Pools**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.LiquidityPools.html#content) for more details.
### Effects
```elixir
# list effects
Stellar.Horizon.Effects.all(
Stellar.Horizon.Server.testnet(),
limit: 10,
order: :asc
)
```
See [**Stellar.Horizon.Effects**](https://hexdocs.pm/stellar_sdk/Stellar.Horizon.Effects.html#content) for more details.
### FeeStats
```elixir
# retrieve fee stats
Stellar.Horizon.FeeStats.retrieve(Stellar.Horizon.Server.testnet())
```
See [**Stellar.Horizon.FeeStats**](https://developers.stellar.org/api/aggregations/fee-stats/single/) for more details.
### Paths
#### List paths
This will return information about potential path payments:
- [Required] source_account. The Stellar address of the sender.
- [Required] destination_asset. **:native** or **[code: "DESTINATION_ASSET_CODE", issuer: "DESTINATION_ASSET_ISSUER"]**.
- [Required] destination_amount. The destination amount specified in the search that found this path.
- [Optional] destination_account. The Stellar address of the reciever.
```elixir
Stellar.Horizon.PaymentPaths.list_paths(
Stellar.Horizon.Server.testnet(),
source_account: "GBRSLTT74SKP62KJ7ENTMP5V4R7UGB6E5UQESNIIRWUNRCCUO4ZMFM4C",
destination_asset: :native,
destination_amount: 5
)
```
#### List strict receive payment paths
- [Required] destination_asset. **:native** or **[code: "DESTINATION_ASSET_CODE", issuer: "DESTINATION_ASSET_ISSUER"]**.
- [Required] destination_amount. The amount of the destination asset that should be received.
- [Optional] source_account. The Stellar address of the sender.
- [Optional] source_assets. A comma-separated list of assets available to the sender.
```elixir
Stellar.Horizon.PaymentPaths.list_receive_paths(
Stellar.Horizon.Server.testnet(),
destination_asset: :native,
destination_amount: 5,
source_account: "GBTKSXOTFMC5HR25SNL76MOVQW7GA3F6CQEY622ASLUV4VMLITI6TCOO"
)
```
#### List strict send payment paths
- [Required] source_asset. **:native** or **[code: "SOURCE_ASSET_CODE", issuer: "SOURCE_ASSET_ISSUER"]**.
- [Required] source_amount. The amount of the source asset that should be sent.
- [Optional] destination_account. The Stellar address of the reciever.
- [Optional] destination_assets. A comma-separated list of assets that the recipient can receive.
```elixir
Stellar.Horizon.PaymentPaths.list_send_paths(
Stellar.Horizon.Server.testnet(),
source_asset: :native,
source_amount: 5,
destination_assets: "TEST:GA654JC6QLA3ZH4O5V7X5NPM7KEWHKRG5GJA4PETK4SOFBUJLCCN74KQ"
)
```
See [**Stellar.Horizon.Paths**](https://developers.stellar.org/api/aggregations/paths/) for more details.
### Order Books
#### Retrieve order Books
Provides an order book’s bids and asks:
- [Required] selling_asset. **:native** or **[code: "SELLING_ASSET_CODE", issuer: "SELLING_ASSET_ISSUER"]**.
- [Required] buying_asset. **:native** or **[code: "BUYING_ASSET_CODE", issuer: "BUYING_ASSET_ISSUER"]**.
- [Optional] limit. The maximum number of records returned
```elixir
Stellar.Horizon.OrderBooks.retrieve(
Stellar.Horizon.Server.testnet(),
selling_asset: :native,
buying_asset: :native
)
Stellar.Horizon.OrderBooks.retrieve(
Stellar.Horizon.Server.testnet(),
selling_asset: :native,
buying_asset: [
code: "BB1",
issuer: "GD5J6HLF5666X4AZLTFTXLY46J5SW7EXRKBLEYPJP33S33MXZGV6CWFN"
],
limit: 2
)
```
See [**Stellar.Horizon.OrderBooks**](https://developers.stellar.org/api/aggregations/order-books/) for more details.
### Trade Aggregations
#### List trade aggregations
Displays trade data based on filters set in the arguments:
- [Required] base_asset. **:native** or **[code: "BASE_ASSET_CODE", issuer: "BASE_ASSET_ISSUER"]**.
- [Required] counter_asset. **:native** or **[code: "COUNTER_ASSET_CODE", issuer: "COUNTER_ASSET_ISSUER"]**.
- [Required] resolution. The segment duration represented as milliseconds.
- [Optional] start_time. The lower time boundary represented as milliseconds since epoch.
- [Optional] end_time. The upper time boundary represented as milliseconds since epoch.
- [Optional] offset. Segments can be offset using this parameter. Expressed in milliseconds.
- [Optional] order. A designation of the order in which records should appear.
- [Optional] limit. The maximum number of records returned.
```elixir
Stellar.Horizon.TradeAggregations.list_trade_aggregations(
Stellar.Horizon.Server.testnet(),
base_asset: :native,
counter_asset: :native,
resolution: "60000"
)
Stellar.Horizon.TradeAggregations.list_trade_aggregations(
Stellar.Horizon.Server.testnet(),
base_asset: :native,
counter_asset: [
code: "EURT",
issuer: "GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S"
],
resolution: "3600000",
start_time: "1582156800000",
end_time: "1582178400000"
)
```
See [**Stellar.Horizon.TradeAggregations**](https://developers.stellar.org/api/aggregations/trade-aggregations/) for more details.
---
## Development
* Install any Elixir version above 1.12.
* Compile dependencies: `mix deps.get`.
* Run tests: `mix test`.
## Code of conduct
We welcome everyone to contribute. Make sure you have read the [CODE_OF_CONDUCT][coc] before.
## Contributing
For information on how to contribute, please refer to our [CONTRIBUTING][contributing] guide.
## Changelog
Features and bug fixes are listed in the [CHANGELOG][changelog] file.
## License
This library is licensed under an MIT license. See [LICENSE][license] for details.
## Acknowledgements
Made with 💙 by [kommitters Open Source](https://kommit.co)
[license]: https://github.com/kommitters/stellar_sdk/blob/main/LICENSE.md
[coc]: https://github.com/kommitters/stellar_sdk/blob/main/CODE_OF_CONDUCT.md
[changelog]: https://github.com/kommitters/stellar_sdk/blob/main/CHANGELOG.md
[contributing]: https://github.com/kommitters/stellar_sdk/blob/main/CONTRIBUTING.md
[base]: https://github.com/kommitters/stellar_base
[sdk]: https://github.com/kommitters/stellar_sdk
[sdk-tests]: https://github.com/kommitters/stellar_sdk/blob/main/test/tx_build
[hex]: https://hex.pm/packages/stellar_sdk
[stellar]: https://www.stellar.org/
[horizon-api]: https://developers.stellar.org/api/introduction
[http_client_spec]: https://github.com/kommitters/stellar_sdk/blob/main/lib/horizon/client/spec.ex
[stellar-docs-tx]: https://developers.stellar.org/docs/glossary/transactions
[stellar-docs-sequence-number]: https://developers.stellar.org/docs/glossary/transactions/#sequence-number
[stellar-docs-fee]: https://developers.stellar.org/docs/glossary/transactions/#fee
[stellar-docs-memo]: https://developers.stellar.org/docs/glossary/transactions/#memo
[stellar-docs-preconditions]: https://developers.stellar.org/docs/glossary/transactions/#validity-conditions
[stellar-docs-time-bounds]: https://developers.stellar.org/docs/glossary/transactions/#time-bounds
[stellar-docs-ledger-bounds]: https://developers.stellar.org/docs/glossary/transactions/#ledger-bounds
[stellar-docs-min-seq-num]: https://developers.stellar.org/docs/glossary/transactions/#minimum-sequence-number
[stellar-docs-min-seq-age]: https://developers.stellar.org/docs/glossary/transactions/#minimum-sequence-age
[stellar-docs-min-seq-ledger-gap]: https://developers.stellar.org/docs/glossary/transactions/#minimum-sequence-ledger-gap
[stellar-docs-extra-signers]: https://developers.stellar.org/docs/glossary/transactions/#extra-signers
[stellar-docs-tx-envelope]: https://developers.stellar.org/docs/glossary/transactions/#transaction-envelopes
[stellar-docs-list-operations]: https://developers.stellar.org/docs/start/list-of-operations
[stellar-docs-tx-signatures]: https://developers.stellar.org/docs/encyclopedia/signatures-multisig
[stellar-cap-27]: https://stellar.org/protocol/cap-27
[stellar-protocol-19]: https://stellar.org/blog/announcing-protocol-19
[stellar-docs-account-seq-num-age]: https://developers.stellar.org/docs/glossary/accounts/#sequence-time-and-ledger
[soroban.ex]: https://github.com/kommitters/soroban.ex
