Skip to content

These new docs are in beta. Please submit bugs to GitHub issues.


Horizon API Reference

Horizon is an API for interacting with the Stellar network.

This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.

Horizon is a RESTful API and can be accessed via cURL, a browser, or one of the Stellar SDKs. To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls.

The Stellar Development Foundation (SDF) runs two instances of Horizon:


Response Format

Horizon delivers responses as JSON objects formatted according to HAL. The HAL format makes Horizon more explorable, paginates responses, and connects parent and child resources. Consuming this format is simple using one of the many open source libraries available for most major programming languages.

HAL is just JSON with two reserved attribute names:

  • _links
  • _embedded

If a response is a single record, the _links section will provide links to any parent or child records, and there will be no _embedded property.

If a response is a collection, the _links section will provide pagination links, and the response’s list of records will be nested underneath the _embedded property.

  • ATTRIBUTESDATA TYPE

    DESCRIPTION

  • _linksarray

    Provides links for navigating to other pages or to parents and children.

  • _embeddedarray

    Present when querying an endpoint that responds with a collection of records.


Streaming

Horizon provides a streaming mechanism for receiving events in near real time. Instead of repeatedly sending requests to Horizon for batch updates, a connection is established between a client and Horizon with updates to an endpoint response streaming as new ledgers close and updates occur.

This reduces requests that return no data and allows near instantaneous updates client-side.

All attributes for the endpoints that allow streaming are the same as regular responses. A caller can initiate streaming by setting ‘Accept: text/event-stream’ in the HTTP header when making the request. Study an example of using streaming in the Follow Received Payments tutorial.


Rate Limiting

Horizon rate limits on a per-IP-address basis. By default, a client is limited to 3600 requests per hour - one request per second on average.

While streaming, each update of the stream counts as a request and against a client’s allotted rate limit.


XDR

In the Stellar network, transactions are encoded using a standardized protocol called External Data Representation (XDR).

In Horizon, you will only encounter XDR when posting and getting transactions and in the ledger header.

When you post a transaction, a client will encode the transaction as XDR before submitting it to Horizon.

When you request a transaction, Horizon returns some data about the transaction in human-readable JSON. The full canonical data about the transaction is encoded in machine-readable XDR, available in XDR attributes at the end of the response.

You can decode this XDR in the Stellar Laboratory’s XDR Viewer.

  • ATTRIBUTETYPE

    DESCRIPTION

  • envelope_xdrstring

    The XDR encoded transaction as stellar-core sees it.

  • result_xdrstring

    The effects of a transaction encoded in XDR.

  • result_meta_xdrstring

    The details about the effects of a transaction encoded in XDR.

  • fee_meta_xdrstring

    The fees associated with the transaction encoded in XDR.


Pagination

To make it possible to explore the millions of records for resources like transactions and operations, Horizon paginates the data it returns for collection-based endpoints.

Each individual transaction, operation, ledger, etc. is returned as a record, and a group of records is called a collection. Records are returned as an array under the _embedded attribute.

To move between pages of a collection of records, use the links in the next and prev attributes nested under the top-level _links attribute.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • _linksarray

    Provides links for navigating to other pages.

  • _embeddedarray

    An href key with a link to the next page for this endpoint as the value.


Page Arguments

GET/{endpoint}?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED?

    DESCRIPTION

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


The Ledger Object

When Horizon returns information about a ledger, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this ledger.

  • paging_tokennumber

    A cursor value for use in pagination.

  • hashstring

    A hex-encoded SHA-256 hash of this ledger’s XDR-encoded form.

  • prev_hashstring

    The hash of the ledger immediately preceding this ledger.

  • sequencenumber

    The sequence number of this ledger, and the parameter used in Horizon calls that require a ledger number.

  • successful_transaction_countnumber

    The number of successful transactions in this ledger.

  • failed_transaction_countnumber

    The number of failed transactions in this ledger.

  • operation_countnumber

    The number of operations applied in this ledger.

  • closed_atstring

    An ISO 8601 formatted string of when this ledger was closed.

  • total_coinsstring

    The total number of lumens in circulation.

  • fee_poolstring

    The sum of all transaction fees.

  • base_fee_in_stroopsnumber

    The fee the network charges per operation in a transaction.

  • base_reserve_in_stroopsnumber

    The reserve the network uses when calculating an account’s minimum balance.

  • max_tx_set_sizenumber

    The maximum number of transactions validators have agreed to process in a given ledger.

  • protocol_versionnumber

    The protocol version that the Stellar network was running when this ledger was committed.

  • header_xdrstring

    A base64 encoded string of the raw LedgerHeader xdr struct for this ledger.


Retrieve a Ledger

The single ledger endpoint provides information on a specific ledger.

GET/ledgers/:ledger_sequence
  • ARGUMENTREQUIRED

    DESCRIPTION

  • sequencerequired

    The sequence number of a specific ledger.


Retrieve a Ledger's Transactions

This endpoint represents successful transactions in a given ledger.

GET/ledgers/:ledger_sequence/transactions?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • sequencerequired

    The sequence number of a specific ledger.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed transactions in results. Options include true and false.


Retrieve a Ledger's Operations

This endpoint returns successful operations in a specific ledger.

GET/ledgers/:ledger_sequence/operations?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}&join={transactions}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • ledger_sequencerequired

    The sequence number of a specific ledger.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Retrieve a Ledger's Payments

This endpoint returns all payment-related operations in a specific ledger.

Operation types that can be returned by this endpoint include:

  • create_account
  • payment
  • path_payment
  • account_merge
GET/ledgers/:ledger_sequence/payments?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}&join={transactions}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • ledger_sequencerequired

    The sequence number of a specific ledger.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed payments in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the payments in the response.


Retrieve a Ledgers's Effects

This endpoint returns the effects of a specific ledger.

GET/ledgers/:ledger_sequence/effects?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • ledger_sequencerequired

    The sequence number of a specific ledger.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


The Transaction Object

When Horizon returns information about a transaction, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this transaction.

  • paging_tokennumber

    A cursor value for use in pagination.

  • successfulboolean

    Indicates if this transaction was successful or not.

  • hashstring

    A hex-encoded SHA-256 hash of this transaction’s XDR-encoded form.

  • ledgernumber

    The sequence number of the ledger that this transaction was included in.

  • created_atISO8601 string

    The date this transaction was created.

  • source_accountstring

    The account that originates the transaction.

  • source_account_sequencestring

    The source account’s sequence number that this transaction consumed.

  • fee_chargednumber

    The fee (in stroops) paid by the source account to apply this transaction to the ledger.

  • max_feenumber

    The maximum fee (in stroops) that the source account was willing to pay.

  • operation_countnumber

    The number of operations contained within this transaction.

  • envelope_xdrstring

    A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction.

  • result_xdrstring

    A base64 encoded string of the raw TransactionResult XDR struct for this transaction.

  • result_meta_xdrstring

    A base64 encoded string of the raw TransactionMeta XDR struct for this transaction

  • fee_meta_xdrstring

    A base64 encoded string of the raw LedgerEntryChanges XDR struct produced by taking fees for this transaction.

  • memostring

    The optional memo attached to a transaction.

  • memo_typestring

    The type of memo. Potential values include MEMO_TEXT, MEMO_ID, MEMO_HASH, MEMO_RETURN.

  • signaturesstring

    An array of signatures used to sign this transaction.

  • valid_afterRFC3339 date-time string

    The date after which a transaction is valid.

  • valid_beforeRFC3339 date-time string

    The date before which a transaction is valid.


Retrieve a Transaction

The single transaction endpoint provides information on a specific transaction.

GET/transactions/:transaction_id
  • ARGUMENTREQUIRED

    DESCRIPTION

  • hashrequired

    A hex-encoded SHA-256 hash of this transaction’s XDR-encoded form.


Retrieve a Transaction's Operations

This endpoint returns successful operations for a specific transaction.

GET/transactions/:transaction_hash/operations?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}&join={transactions}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • transaction_hashrequired

    A hex-encoded SHA-256 hash of this transaction’s XDR-encoded form.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Retrieve a Transaction's Effects

This endpoint returns the effects of a specific transaction.

GET/transactions/:transaction_hash/effects?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • transaction_hashrequired

    A hex-encoded SHA-256 hash of this transaction’s XDR-encoded form.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


List All Transactions

This endpoint lists all successful transactions and can be used in streaming mode. Streaming mode allows you to listen for new transactions as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known transaction unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream transactions created since your request time.

GET/transactions?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.


Operations

Operations are objects that 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.

Each of Stellar’s operations have a unique operation object.


The Operation Object

Each of Stellar’s operations have unique response shapes. Below are the attributes that are common across individual operation objects.

See the generic Operation errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idnumber

    The operation’s ID number.

  • paging_tokenstring

    A cursor value for use in pagination.

  • type_inumber

    A number indicating the operation type.

  • typestring

    The name of the operation type.

  • transaction_hashstring

    A unique identifier for the transaction this operation belongs to.

  • transaction_successfulboolean

    Indicates if this operation was part of a successful transaction.

  • source_accountstring

    The account that originates the operation.

  • created_atstring

    The date this operation was created.


Create Account Object

Creates and funds a new account with the specified starting balance.

See the Create Account errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • starting_balancestring

    The amount of XLM to send the newly created account.

  • funderstring

    The account that funds the new account.

  • accountstring

    A new account that is funded.


Payment Object

Sends an amount in a specific asset to a destination account.

See the Payment errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    The type of asset being sent. Either native, credit_alphanum4, or credit_alphanum12.

  • asset_codestring

    The code for the asset being sent. Appears if the asset_type is not native.

  • asset_issuerstring

    The Stellar address of the issuer of the asset being sent. Appears if the asset_type is not native.

  • fromstring

    The payment sender’s public key.

  • tostring

    The payment recipient’s public key.

  • amountstring

    Amount sent.


Path Payment Strict Receive Object

Sends a payment from one account to another in a path through the order books, starting as one asset and ending as another. Path payments that are Strict Receive designate the payment amount in the asset received.

See the Path Payment Strict Receive errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    The type of asset being received. Either native, credit_alphanum4, or credit_alphanum12.

  • asset_codestring

    The code for the asset being received. Appears if the asset_type is not native.

  • asset_issuerstring

    The Stellar address of the issuer of the asset being received. Appears if the asset_type is not native.

  • fromstring

    The payment sender’s public key.

  • tostring

    The payment recipient’s public key.

  • amountstring

    Amount received designated in the destination asset.

  • patharray of objects

    The intermediary assets that this path hops through.

  • source_amountstring

    Amount sent designated in the source asset.

  • source_maxstring

    The maximum amount to be sent designated in the source asset.

  • source_asset_typestring

    The type for the source asset. Either native, credit_alphanum4, or credit_alphanum12.

  • source_asset_codestring

    The code for the source asset.

  • source_asset_issuerstring

    The Stellar address of the source asset’s issuer.


Path Payment Strict Send Object

Sends a payment from one account to another in a path through the order books, starting as one asset and ending as another. Path payments that are Strict Send designate the payment amount in the asset sent.

See the Path Payment Strict Send errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    The type of asset being sent. Either native, credit_alphanum4, or credit_alphanum12.

  • asset_codestring

    The code for the asset being sent. Appears if the asset_type is not native.

  • asset_issuerstring

    The Stellar address of the issuer of the asset being sent. Appears if the asset_type is not native.

  • fromstring

    The payment sender’s public key.

  • tostring

    The payment recipient’s public key.

  • amountstring

    Amount received designated in the source asset.

  • patharray of objects

    The intermediary assets that this path hops through.

  • source_amountstring

    Amount sent designated in the source asset.

  • destination_minstring

    The minimum amount of destination asset expected to be received.

  • source_asset_typestring

    The type for the source asset. Either native, credit_alphanum4, or credit_alphanum12.

  • source_asset_codestring

    The code for the source asset. Appears if the asset_type is not native.

  • source_asset_issuerstring

    The Stellar address of the source asset’s issuer. Appears if the asset_type is not native.


Manage Sell Offer Object

Creates, updates, or deletes a sell offer to trade assets. A sell offer specifies a certain amount of the selling asset that should be sold in exchange for the maximum quantity of the buying asset.

See the Manage Sell Offer errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • amountstring

    The amount of selling_asset that the account making this offer is willing to sell.

  • pricestring

    How many units of selling_asset it takes to get 1 unit of buying_asset. A number representing the decimal form of price_r.

  • price_robject

    A precise representation of the buy and sell price of the assets on offer.

  • buying_asset_typestring

    The type for the buying asset. Either native, credit_alphanum4, or credit_alphanum12.

  • buying_asset_issuerstring

    The Stellar address of the buying asset’s issuer. Appears if the buying_asset_type is not native.

  • buying_asset_codestring

    The code for the buying asset. Appears if the buying_asset_type is not native.

  • selling_asset_typestring

    The type for the selling asset. Either native, credit_alphanum4, or credit_alphanum12.

  • selling_asset_issuerstring

    The Stellar address of the selling asset’s issuer. Appears if the selling_asset_type is not native.

  • selling_asset_codestring

    The code for the selling asset. Appears if the selling_asset_type is not native.

  • offer_idstring

    A unique identifier for this offer.


Manage Buy Offer Object

Creates, updates, or deletes a buy offer to trade assets. A buy offer specifies a certain amount of the buying asset that should be sold in exchange for the minimum quantity of the selling asset.

See the Manage Buy Offer errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • amountstring

    The amount of buying_asset that the account making this offer is willing to buy.

  • pricestring

    How many units of buying_asset it takes to get 1 unit of selling_asset. A number representing the decimal form of price_r.

  • price_robject

    A precise representation of the buy and sell price of the assets on offer.

  • buying_asset_typestring

    The type for the buying asset. Either native, credit_alphanum4, or credit_alphanum12.

  • buying_asset_issuerstring

    The Stellar address of the buying asset’s issuer. Appears if the buying_asset_type is not native.

  • buying_asset_codestring

    The code for the buying asset. Appears if the buying_asset_type is not native.

  • selling_asset_typestring

    The type for the selling asset. Either native, credit_alphanum4, or credit_alphanum12.

  • selling_asset_issuerstring

    The Stellar address of the selling asset’s issuer. Appears if the selling_asset_type is not native.

  • selling_asset_codestring

    The code for the selling asset. Appears if the selling_asset_type is not native.

  • offer_idstring

    A unique identifier for this offer.


Create Passive Sell Offer Object

Creates an offer that will not consume a counter offer that exactly matches this offer. This is useful for offers meant to be 1:1 exchanges for path payments. Use Manage Sell Offer to manage this offer after using this operation to create it.

See the Create Passive Sell Offer errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • amountstring

    The amount of selling_asset that the account making this offer is willing to sell.

  • pricestring

    How many units of selling_asset it takes to get 1 unit of buying_asset. A number representing the decimal form of price_r.

  • price_robject

    A precise representation of the buy and sell price of the assets on offer.

  • buying_asset_typestring

    The type for the buying asset. Either native, credit_alphanum4, or credit_alphanum12.

  • buying_asset_issuerstring

    The Stellar address of the buying asset’s issuer. Appears if the buying_asset_type is not native.

  • buying_asset_codestring

    The code for the buying asset. Appears if the buying_asset_type is not native.

  • selling_asset_typestring

    The type for the selling asset. Either native, credit_alphanum4, or credit_alphanum12.

  • selling_asset_issuerstring

    The Stellar address of the selling asset’s issuer. Appears if the selling_asset_type is not native.

  • selling_asset_codestring

    The code for the selling asset. Appears if the selling_asset_type is not native.

  • offer_idstring

    A unique identifier for this offer.


Set Options Object

Sets an account’s flags, inflation destination, signers, and home domain.

See the Set Options errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • signer_keystring

    The public key of the new signer.

  • signer_weightnumber

    The weight of the new signer. Can range from 1 to 255.

  • master_key_weightnumber

    The weight of the master key. Can range from 1 to 255.

  • low_thresholdnumber

    The sum weight for the low threshold.

  • med_thresholdnumber

    The sum weight for the medium threshold.

  • high_thresholdnumber

    The sum weight for the high threshold.

  • home_domainstring

    The home domain used for stellar.toml file discovery.

  • set_flagsarray

    The array of numeric values of flags that has been set in this operation. Options include 1 for AUTH_REQUIRED_FLAG, 2 for AUTH_REVOCABLE_FLAG, and 4 for AUTH_IMMUTABLE_FLAG.

  • set_flags_sarray

    The array of string values of flags that has been set in this operation. Options include AUTH_REQUIRED_FLAG, AUTH_REVOCABLE_FLAG, and AUTH_IMMUTABLE_FLAG.

  • clear_flagsarray

    The array of numeric values of flags that has been cleared in this operation. Options include 1 for AUTH_REQUIRED_FLAG, 2 for AUTH_REVOCABLE_FLAG, and 4 for AUTH_IMMUTABLE_FLAG.

  • clear_flags_sarray

    The array of string values of flags that has been cleared in this operation. Options include AUTH_REQUIRED_FLAG, AUTH_REVOCABLE_FLAG, and AUTH_IMMUTABLE_FLAG.


Change Trust Object

Creates, updates, or deletes a trust line from the source account to another account’s issued asset.

See the Change Trust errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    The type of asset being trusted. Either native, credit_alphanum4, or credit_alphanum12.

  • asset_codestring

    The Stellar address of the asset being trusted.

  • asset_issuerstring

    The code for the asset being trusted.

  • limitstring

    Limits the amount of an asset that the source account can hold.

  • trusteestring

    The issuing account.

  • trustorstring

    The source account.


Allow Trust Object

Updates the “authorized” flag of an existing trust line. This must be called by the issuer of the asset.

See the Allow Trust errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    The type of asset. Either native, credit_alphanum4, or credit_alphanum12.

  • asset_codestring

    The Stellar address of the asset.

  • asset_issuerstring

    The code for the asset.

  • authorizeboolean

    Allows or disallows trust.

  • trusteestring

    The issuing account, or source account in this instance.

  • trustorstring

    The trusting account, or the account being authorized or unauthorized.


Account Merge Object

Removes the source account from the Stellar and transfers the source account’s lumens to another account.

See the Account Merge errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • accountstring

    The Stellar address being removed.

  • intostring

    The Stellar address receiving the deleted account’s lumens.


Manage Data Object

Set, modify, or delete a data entry (name/value pair) for an account.

See the Manage Data errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • namestring

    The key for this data entry. It can be 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.

  • valuestring

    If present, then this value will be set in the DataEntry. It can be up to 64 bytes long. If not present, then the existing Name will be deleted.


Bump Sequence Object

Bumps forward the sequence number of the source account, allowing it to invalidate any transactions with a smaller sequence number.

See the Bump Sequence errors.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • bump_tostring

    The new desired value for the source account’s sequence number.


Create Claimable Balance

Creates a new claimable balance.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • assetstring

    The asset available to be claimed in the form asset_code:issuing_address or native (for XLM)

  • amountstring

    The amount available to be claimed.

  • claimantsarray of objects

    The list of entries which could claim the claimable balance.


Claim Claimable Balance

Claims a claimable balance.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • balance_idstring

    The id of the claimable balance.

  • claimantstring

    The id of the account which claimed the balance.


Begin Sponsoring Future Reserves

Initiate a sponsorship.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • sponsored_idstring

    The id of the account which will be sponsored.


End Sponsoring Future Reserves

End a sponsorship.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • begin_sponsorstring

    The id of the account which initiated the sponsorship.


Revoke Sponsorship

Revoke sponsorship of a ledger entry.

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • account_idstring (optional)

    The id of the account which is no longer sponsored.

  • claimable_balance_idstring (optional)

    The id of the claimable balance which is no longer sponsored.

  • data_account_idstring (optional)

    The id of the account whose data entry is no longer sponsored.

  • data_namestring (optional)

    The name of the data entry which is no longer sponsored.

  • offer_idstring (optional)

    The id of the offer which is no longer sponsored.

  • trustline_account_idstring (optional)

    The id of the account whose trustline is no longer sponsored.

  • trustline_assetstring (optional)

    The asset of the trustline which is no longer sponsored.

  • signer_account_idstring (optional)

    The account id of the signer which is no longer sponsored.

  • signer_keystring (optional)

    The type of the signer which is no longer sponsored.


Retrieve an Operation

The single operation endpoint provides information about a specific operation.

GET/operations/:operation_id
  • ARGUMENTREQUIRED

    DESCRIPTION

  • idrequired

    The ID number for this operation.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Retrieve an Operation's Effects

This endpoint returns the effects of a specific operation.

GET/operations/:operation_id/effects?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • idrequired

    The ID number for this operation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


List All Operations

This endpoint lists all successful operations and can be used in streaming mode. Streaming mode allows you to listen for new operations as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known operation unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream operations created since your request time.

GET/operations?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed={true,false}&join={transactions]
  • ARGUMENTREQUIRED

    DESCRIPTION

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The maximum number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


List All Payments

This endpoint lists all successful payment-related operations and can be used in streaming mode. Streaming mode allows you to listen for new payments as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known payment unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream payments created since your request time.

Operations that can be returned by this endpoint include:

  • create_account
  • payment
  • path_payment
  • account_merge
GET/payments?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed={true,false}&join={transactions]
  • ARGUMENTREQUIRED

    DESCRIPTION

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The maximum number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Effects

Effects represent specific changes that occur in the ledger as a result of successful operations, but are not necessarily directly reflected in the ledger or history, as transactions and operations are.

Learn more about effects.


Effect Types

There are eight groups of effect types. Each effect type has its own set of attributes.

Account Effects

  • TYPE

    OPERATION(S)

  • Account Created

    create_account

  • Account Removed

    merge_account

  • Account Credited

    create_account, payment, path_payment, merge_account

  • Account Debited

    create_account, payment, path_payment, merge_account

  • Account Thresholds Updated

    set_options

  • Account Home Domain Updated

    set_options

  • Account Flags Updated

    set_options

  • Account Inflation Destination Updated

    set_options

Signer Effects

  • TYPE

    OPERATION(S)

  • Signer Created

    set_options

  • Signer Removed

    set_options

  • Signer Updated

    set_options

Trustline Effects

  • TYPE

    OPERATION(S)

  • Trustline Created

    change_trust

  • Trustline Removed

    change_trust

  • Trustline Updated

    change_trust, allow_trust

  • Trustline Authorized

    allow_trust

  • Trustline Deauthorized

    allow_trust

Trading Effects

  • TYPE

    OPERATION(S)

  • Offer Created

    manage_buy_offer, manage_sell_offer, create_passive_sell_offer

  • Offer Removed

    manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment

  • Offer Updated

    manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment

  • Trade

    manage_buy_offer, manage_sell_offer, create_passive_sell_offer, path_payment

Data Effects

  • TYPE

    OPERATION(S)

  • Data Created

    manage_data

  • Data Removed

    manage_data

  • Data Updated

    manage_data

Claimable Balance Effects

  • TYPE

    OPERATION(S)

  • Claimable Balance Created

    create_claimable_balance

  • Claimable Balance Claimant Created

    create_claimable_balance

  • Claimable Balance Claimed

    claim_claimable_balance

Sponsorship Effects

  • TYPE

    OPERATION(S)

  • Account Sponsorship Created

    create_account

  • Account Sponsorship Updated

    revoke_sponsorship

  • Account Sponsorship Removed

    revoke_sponsorship

  • Trustline Sponsorship Created

    change_trust

  • Trustline Sponsorship Updated

    revoke_sponsorship

  • Trustline Sponsorship Removed

    revoke_sponsorship

  • Account Data Sponsorship Created

    manage_data

  • Account Data Sponsorship Updated

    revoke_sponsorship

  • Account Data Sponsorship Removed

    revoke_sponsorship

  • Claimable Balance Sponsorship Created

    create_claimable_balance

  • Claimable Balance Sponsorship Updated

    revoke_sponsorship

  • Claimable Balance Sponsorship Removed

    revoke_sponsorship

  • Account Signer Sponsorship Created

    set_options

  • Account Signer Sponsorship Updated

    revoke_sponsorship

  • Account Signer Sponsorship Removed

    revoke_sponsorship

Miscellaneous Effects

  • TYPE

    OPERATION(S)

  • Sequence Bumped

    bump_sequence


List All Effects

This endpoint lists all effects and can be used in streaming mode. Streaming mode allows you to listen for new effects as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known effect unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream effects created since your request time.

GET/effects?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Accounts

Users interact with the Stellar network through accounts. Everything else in the ledger—assets, offers, trustlines, etc.—are owned by accounts, and accounts must authorize all changes to the ledger through signed transactions.

Learn more about accounts.


The Account Object

When Horizon returns information about an account, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this account.

  • account_idstring

    This account’s public key encoded in a base32 string representation.

  • sequencenumber

    This account’s current sequence number. For use when submitting this account’s next transaction.

  • subentry_countnumber

    The number of subentries on this account.

  • home_domainstring

    The domain that hosts this account’s stellar.toml file.

  • last_modified_ledgernumber

    The ID of the last ledger that included changes to this account.

  • num_sponsoringnumber

    The number of reserves sponsored by this account.

  • num_sponsorednumber

    The number of reserves sponsored for this account.

  • sponsorstring (optional)

    The account ID of the sponsor who is paying the reserves for this account.

  • thresholdsobject

    Operations have varying levels of access. This field specifies thresholds for different access levels, as well as the weight of the master key.

  • flagsobject

    Flags denote the enabling/disabling of certain asset issuer privileges.

  • balancesobject

    The assets this account holds.

  • signersarray of objects

    The public keys and associated weights that can be used to authorize transactions for this account. Used for multi-sig.

  • dataobject

    An array of account data fields.


List All Accounts

This endpoint lists accounts by one of three filters: signer, asset, or sponsor.

GET/accounts?sponsor={:sponsor}&asset={:asset}&signer={:signer}&cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • sponsorstring (optional)

    Account ID of the sponsor. Every account in the response will either be sponsored by the given account ID or have a subentry (trustline, offer, or data entry) which is sponsored by the given account ID.

  • assetstring (optional)

    An issued asset represented as “Code:IssuerAccountID”. Every account in the response will have a trustline for the given asset.

  • signerstring (optional)

    Account ID of the signer. Every account in the response will have the given account ID as a signer.

  • cursorstring (optional)

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderstring (optional)

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitinteger (optional)

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Retrieve an Account

The single account endpoint provides information on a specific account.

The balances section in the response will also list all the trustlines this account has established. Note this will only return trustlines that have the necessary authorization to work. If an account A trusts another account B that has the authorization required flag set, the trustline won’t show up until account B allows account A to hold its assets.

GET/accounts/:account_id
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.


Retrieve an Account's Transactions

This endpoint represents successful transactions for a given account and can be used in streaming mode.

Streaming mode allows you to listen for new transactions for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known transaction unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream transactions created since your request time.

GET/accounts/:account_id/transactions?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed transactions in results. Options include true and false.


Retrieve an Account's Operations

This endpoint represents successful operations for a given account and can be used in streaming mode.

Streaming mode allows you to listen for new operations for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known operation unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream operations created since your request time.

GET/accounts/:account_id/operations?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}&join={transactions}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Retrieve an Account's Payments

This endpoint represents successful payments for a given account and can be used in streaming mode.

Streaming mode allows you to listen for new payments for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known payment unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream payments created since your request time.

GET/accounts/:account_id/payments?cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}&join={transactions}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.

  • include_failedoptional

    Set to true to include failed operations in results. Options include true and false.

  • joinoptional

    Set to transactions to include the transactions which created each of the operations in the response.


Retrieve an Account's Effects

This endpoint returns the effects of a specific account and can be used in streaming mode.

Streaming mode allows you to listen for new effects for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known effect unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream effects created since your request time.

GET/accounts/:account_id/effects?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Retrieve an Account's Offers

This endpoint represents all offers a given account has currently open and can be used in streaming mode.

Streaming mode allows you to listen for new offers for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known offer unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream offers created since your request time.

GET/accounts/:account_id/offers?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Retrieve an Account's Trades

This endpoint represents all trades for a given account and can be used in streaming mode.

Streaming mode allows you to listen for trades for this account as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known trade unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream trades created since your request time.

GET/accounts/:account_id/trades?cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Retrieve an Account's Data

This endpoint represents a single data for a given account.

GET/accounts/:account_id/data/:key
  • ARGUMENTREQUIRED

    DESCRIPTION

  • account_idrequired

    This account’s public key encoded in a base32 string representation.

  • keyrequired

    The key name for this data.


Offers

Offers are statements about how much of an asset an account wants to buy or sell.

Learn more about offers.


The Offer Object

When Horizon returns information about an offer, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this offer.

  • paging_tokennumber

    A cursor value for use in pagination.

  • sellerstring

    The account ID of the account making this offer.

  • sellingasset code

    The asset this offer wants to sell.

  • buyingasset code

    The asset this offer wants to buy.

  • amountstring

    The amount of selling that the account making this offer is willing to sell.

  • price_robject

    A precise representation of the buy and sell price of the assets on offer.

  • pricestring

    How many units of buying it takes to get 1 unit of selling. A number representing the decimal form of price_r.

  • last_modified_ledgerinteger

    The sequence number of the last ledger in which this offer was modified.

  • last_modified_timestring

    An ISO 8601 formatted string of last modification time.

  • sponsorstring (optional)

    The account id of the sponsor who is paying the reserves for this offer.


Retrieve an Offer

The single offer endpoint provides information on a specific offer.

GET/offers/:offer_id
  • ARGUMENTREQUIRED

    DESCRIPTION

  • offer_idrequired

    A unique identifier for this offer.


List All Offers

This endpoint lists all currently open offers and can be used in streaming mode.

Streaming mode allows you to listen for new offers as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known offer unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream offers created since your request time.

When filtering by buying or selling arguments, you must use a combination of selling_asset_type, selling_asset_issuer, and selling_asset_code for the selling asset, or a combination of buying_asset_type, buying_asset_issuer, and buying_asset_code for the buying asset.

GET/offers?sponsor={:sponsor}&seller={:account_id}&selling_asset_type={native,credit_alphanum4,credit_alphanum12}&selling_asset_issuer={:account_id}&selling_asset_code{:asset_code}&buying_asset_type={native,credit_alphanum4,credit_alphanum12}&buying_asset_issuer={:account_id}&buying_asset_code{:asset_code}&cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • sponsoroptional

    The account ID of the sponsor who is paying the reserves for all the offers included in the response.

  • selleroptional

    The account ID of the offer creator.

  • selling_asset_typeoptional

    The type for the selling asset. Either native, credit_alphanum4, or credit_alphanum12.

  • selling_asset_issueroptional

    The Stellar address of the selling asset’s issuer.

  • selling_asset_codeoptional

    The code for the selling asset.

  • buying_asset_typeoptional

    The type for the buying asset. Either native, credit_alphanum4, or credit_alphanum12.

  • buying_asset_issueroptional

    The Stellar address of the buying asset’s issuer.

  • buying_asset_codeoptional

    The code for the buying asset.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Trades

When an offer is fully or partially fulfilled, a trade happens. Trades can also be caused by successful path payments, because path payments involve fulfilling offers.

A trade occurs between two parties—base and counter. Which is which is either arbitrary or determined by the calling query.

Learn more about trades.


The Trade Object

When Horizon returns information about a trade, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this trade.

  • paging_tokennumber

    A cursor value for use in pagination.

  • ledger_close_timestring

    An ISO 8601 formatted string of when the ledger with this trade was closed.

  • offer_idstring

    The sell offer ID. DECPRECATED

  • base_accountstring

    The account ID of the base party for this trade.

  • base_offer_idstring

    The base offer ID. If this offer was immediately and fully consumed, this will be a synethic ID.

  • base_amountstring

    The amount of the base asset that was moved from base_account to counter_account.

  • base_asset_typestring

    The type for the base asset. Either native, credit_alphanum4, or credit_alphanum12.

  • base_asset_codestring

    The code for the base asset.

  • base_asset_issuerstring

    The Stellar address of the base asset’s issuer.

  • counter_offer_idstring

    The counter offer ID. If this offer was immediately and fully consumed, this will be a synethic ID.

  • counter_amountstring

    The amount of the counter asset that was moved from counter_account to base_account.

  • counter_asset_typestring

    The type for the counter asset. Either native, credit_alphanum4, or credit_alphanum12.

  • counter_asset_codestring

    The code for the counter asset.

  • counter_asset_issuerstring

    The Stellar address of the counter asset’s issuer.

  • priceobject

    An object of a number numerator and number denominator that represents the original offer price. To derive the price, divide n by d.

  • base_is_sellerboolean

    Indicates with party is the seller.


List All Trades

This endpoint lists all trades and can be used in streaming mode.

Streaming mode allows you to listen for new trades as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known trade unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream trades created since your request time.

When filtering for a specific orderbook, you must use use all six of these arguments: base_asset_type, base_asset_issuer, base_asset_code, counter_asset_type, counter_asset_issuer, and counter_asset_code. If the base or counter asset is XLM, you only need to indicate the asset type as native and do not need to designate the code or the issuer.

GET/trades?offer_id={:offer_id}&base_asset_type={native,credit_alphanum4,credit_alphanum12}&base_asset_issuer={:account_id}&base_asset_code{:asset_code}&counter_asset_type={native,credit_alphanum4,credit_alphanum12}&counter_asset_issuer={:account_id}&counter_asset_code{:asset_code}&cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • offer_idoptional

    The offer ID. Used to filter for trades originating from a specific offer.

  • base_asset_typeoptional

    The type for the base asset. Either native, credit_alphanum4, or credit_alphanum12.

  • base_asset_issueroptional

    The Stellar address of the base asset’s issuer.

  • base_asset_codeoptional

    The code for the base asset.

  • counter_asset_typeoptional

    The type for the counter asset. Either native, credit_alphanum4, or credit_alphanum12.

  • counter_asset_issueroptional

    The Stellar address of the counter asset’s issuer.

  • counter_asset_codeoptional

    The code for the counter asset.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Assets

Assets are representations of value issued on the Stellar network. An asset consists of a type, code, and issuer.

Learn more about assets.


The Asset Object

When Horizon returns information about an asset, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • asset_typestring

    This asset’s type. Either credit_alphanum4 or credit_alphanum12.

  • asset_codestring

    This asset’s code

  • asset_issuerstring

    The Stellar address of this asset’s issuer.

  • amountnumber

    The number of units issued for this asset.

  • num_accountsnumber

    The numnber of accounts that have issued a trustline to this asset. If the auth_required flag for this asset’s issuer is set to true, this number only includes the accounts who have both set up a trustline to the asset and have been authorized to hold the asset.

  • flagsobject

    Flags denote the enabling/disabling of certain asset issuer privileges.

  • paging_tokennumber

    A cursor value for use in pagination.


List All Assets

This endpoint lists all assets.

GET/assets?asset_code{:asset_code}&asset_issuer={:account_id}&cursor={paging_token}&order={asc,desc}&limit={1-200}&include_failed{true,false}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • asset_codeoptional

    The code of the asset you would like to filter by.

  • asset_issueroptional

    The Stellar address of the issuer for the asset you would like to filter by.

  • cursoroptional

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderoptional

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Claimable Balances

A Claimable Balance represents the transfer of ownership of some amount of an asset. Claimable balances provide a mechanism for setting up a payment which can be claimed in the future. This allows you to make payments to accounts which are currently not able to accept them.


The Claimable Balance Object

When Horizon returns information about a claimable balance, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • idstring

    A unique identifier for this claimable balance.

  • paging_tokennumber

    A cursor value for use in pagination.

  • assetstring

    The asset available to be claimed.

  • amountstring

    The amount of asset that can be claimed.

  • sponsorstring (optional)

    The account id of the sponsor who is paying the reserves for this claimable balance.

  • last_modified_ledgerinteger

    The sequence number of the last ledger in which this claimable balance was modified.

  • last_modified_timestring

    An ISO 8601 formatted string of last modification time.

  • claimantsarray of objects

    The list of entries which could claim the claimable balance.


Retrieve a Claimable Balance

The single claimable balance endpoint provides information on a claimable balance.

GET/claimable_balances/:claimable_balance_id
  • ARGUMENTREQUIRED

    DESCRIPTION

  • claimable_balance_idrequired

    A unique identifier for this claimable balance.


List Claimable Balances

This endpoint lists all available claimable balances.

GET/claimable_balances?sponsor={:sponsor}&asset={:asset}&claimant={:claimant}&cursor={paging_token}&order={asc,desc}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • sponsorstring (optional)

    Account ID of the sponsors. Only include claimable balances in the response which are sponsored by the given account ID.

  • assetstring (optional)

    An issued asset represented as “Code:IssuerAccountID”. Only include claimable balances in the response which provide a balance for the given asset.

  • claimantstring (optional)

    Account ID of the destination address. Only include claimable balances which can be claimed by the given account ID.

  • cursorstring (optional)

    A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.

  • orderstring (optional)

    A designation of the order in which records should appear. Options include asc(ascending) or desc (descending). If this argument isn’t set, it defaults to asc.

  • limitinteger (optional)

    The total number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.


Order Books

An order book is a collections of offers for a specific pair of assets.

Learn more about order books.


The Order Book Object

When Horizon returns information about an order book, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • bidsobject

    The prices and amounts for the buyside of the asset pair.

  • asksobject

    The prices and amounts for the sellside of the asset pair.

  • baseobject

    Details about the base asset.

  • counterobject

    Details about the counter asset.


Retrieve an Order Book

The order book endpoint provides an order book’s bids and asks and can be used in streaming mode.

When filtering for a specific order book, you must use use all six of these arguments: base_asset_type, base_asset_issuer, base_asset_code, counter_asset_type, counter_asset_issuer, and counter_asset_code. If the base or counter asset is XLM, you only need to indicate the asset type as native and do not need to designate the code or the issuer.

GET/order_book?selling_asset_type={native,credit_alphanum4,credit_alphanum12}&selling_asset_issuer={:account_id}&selling_asset_code{:asset_code}&buying_asset_type={native,credit_alphanum4,credit_alphanum12}&buying_asset_issuer={:account_id}&buying_asset_code{:asset_code}&limit={1-200}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • selling_asset_typerequired

    The type for the asset being sold (base asset). Either native, credit_alphanum4, or credit_alphanum12.

  • selling_asset_issueroptional

    The Stellar address of the issuer of the asset being sold (base asset). Required if the selling_asset_type is not native.

  • selling_asset_codeoptional

    The code for the asset being sold (base asset). Required if the selling_asset_type is not native.

  • buying_asset_typerequired

    The type for the asset being bought (counter asset). Either native, credit_alphanum4, or credit_alphanum12.

  • buying_asset_issueroptional

    The Stellar address of the issuer of the asset being bought (counter asset). Required if the buying_asset_type is not native.

  • buying_asset_codeoptional

    The code for the asset being bought (counter asset). Required if the buying_asset_type is not native.

  • limitoptional

    The total number of records returned. The limit can range from 1 to 200—an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 20 for order books.


The Path Object

When Horizon returns information about a path, it uses the following format:

  • ATTRIBUTEDATA TYPE

    DESCRIPTION

  • source_asset_typestring

    The type for the source asset. Either native, credit_alphanum4, or credit_alphanum12.

  • source_asset_codestring

    The code for the source asset.

  • source_asset_issuerstring

    The Stellar address of the source asset’s issuer.

  • source_amountstring

    An estimated cost for making a payment of destination_amount on this path. Suitable for use in the sendMax field of a path payment operation.

  • destination_asset_typestring

    The type for the destination asset. Either native, credit_alphanum4, or credit_alphanum12.

  • destination_asset_codestring

    The code for the destination asset.

  • destination_asset_issuerstring

    The Stellar address of the destination asset’s issuer.

  • destination_amountstring

    The destination amount specified in the search that found this path.

  • patharray of objects

    The intermediary assets that this path hops through.


List Strict Receive Payment Paths

The strict receive payment path endpoint lists the paths a payment can take based on the amount of an asset you want the recipient to receive. The destination asset amount stays constant, and the type and amount of an asset sent varies based on offers in the order books.

For this search, Horizon loads a list of assets available to the sender (based on source_account or source_assets) and displays the possible paths from the different source assets to the destination asset. Only paths that satisfy the destination_amount are returned.

GET/paths/strict-receive?source_account={:account_id}&source_assets={:asset_list}&destination_asset_type={native,credit_alphanum4,credit_alphanum12}&destination_asset_code={:asset_code}&destination_asset_issuer={:account_id}&destination_amount={:amount}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • source_accountoptional

    The Stellar address of the sender. Any returned path must start with an asset that the sender holds. Using either source_account or source_assets as an argument is required for strict receive path payments.

  • source_assetsoptional

    A comma-separated list of assets available to the sender. Any returned path must start with an asset in this list. Each asset is formatted as CODE:ISSUER_ACCOUNT. For example: USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX. Using either source_account or source_assets as an argument is required for strict receive path payments.

  • destination_asset_typerequired

    The type for the destination asset. Either native, credit_alphanum4, or credit_alphanum12.

  • destination_asset_issueroptional

    The Stellar address of the issuer of the destination asset. Required if the destination_asset_type is not native.

  • destination_asset_codeoptional

    The code for the destination asset. Required if the destination_asset_type is not native.

  • destination_amountrequired

    The amount of the destination asset that should be received.


List Strict Send Payment Paths

The strict receive payment path endpoint lists the paths a payment can take based on the amount of an asset you want to send. The source asset amount stays constant, and the type and amount of an asset received varies based on offers in the order books.

For this search, Horizon loads a list of assets that the recipient can recieve (based on destination_account or destination_assets) and displays the possible paths from the different source assets to the destination asset. Only paths that satisfy the source_amount are returned.

GET/paths/strict-send?source_asset_type={native,credit_alphanum4,credit_alphanum12}&source_asset_code={:asset_code}&source_asset_issuer={:account_id}&source_amount={:amount}&destination_account={:account_id}&destination_assets={:asset_list}
  • ARGUMENTREQUIRED

    DESCRIPTION

  • source_asset_typerequired

    The type for the source asset. Either native, credit_alphanum4, or credit_alphanum12.

  • source_asset_issueroptional

    The Stellar address of the issuer of the source asset. Required if the source_asset_type is not native.

  • source_asset_codeoptional

    The code for the source asset. Required if the source_asset_type is not native.

  • source_amountrequired

    The amount of the source asset that should be sent.

  • destination_accountoptional

    The Stellar address of the reciever. Any returned path must end with an asset that the recipient can receive. Using either source_account or source_assets as an argument is required for strict send path payments.

  • destination_assetsoptional

    A comma-separated list of assets that the recipient can receive. Any returned path must end with an asset in this list. Each asset is formatted as CODE:ISSUER_ACCOUNT. For example: USD:GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX. Using either source_account or source_assets as an argument is required for strict send path payments.