Horizon is the client facing API server for the Stellar ecosystem. See an overview of the Stellar ecosystem for more details.
Horizon provides three significant portions of functionality: The Transactions API, the History API, and the Trading API.
Transactions API
The Transactions API exists to help you make transactions against the Stellar network. It provides ways to help you create valid transactions, such as providing an account’s sequence number or latest known balances.
In addition to the read endpoints, the Transactions API also provides the endpoint to submit transactions.
Important Endpoints
History API
The History API provides endpoints for retrieving data about what has happened in the past on the Stellar network. It provides (or will provide) endpoints that let you:
- Retrieve transaction details
- Load transactions that effect a given account
- Load payment history for an account
- Load trade history for a given order book
Important Endpoints
Trading API
The Trading API provides endpoints for retrieving data about the distributed
currency exchange within stellar. It provides data regarding open offers to
exchange currency (often called an order book) and also provides data about
trades that were executed within the exchange.
Important Endpoints
Rather than using a fully custom way of representing the resources we expose in
Horizon, we use HAL. HAL is a
hypermedia format in JSON that remains simple while giving us a couple of
benefits such as simpler client integration for several languages. See this
wiki page for a
list of libraries.
Attributes, Links, Embedded Resources
At its simplest, a HAL response is just a JSON object with a couple of reserved
property names: _links is used for expressing links and _embedded is used
for bundling other HAL objects with the response. Other than links and embedded
objects, HAL is just JSON.
Links
HAL is a hypermedia format, like HTML, in that it has a mechanism to express
links between documents. Let’s look at a simple example:
{
"_links": {
"self": {
"href": "/ledgers/1"
},
"transactions": {
"href": "/ledgers/1/transactions{?cursor}{?limit}{?order}",
"templated": true
}
},
"id": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637",
"hash": "43cf4db3741a7d6c2322e7b646320ce9d7b099a0b3501734dcf70e74a8a4e637",
"prev_hash": "",
"sequence": 1,
"transaction_count": 0,
"operation_count": 0,
"closed_at": "0001-01-01T00:00:00Z"
}
The above response is for the genesis ledger of the Stellar test network, and
the links in the _links attribute provide links to other relavant resources in
Horizon. Notice the object beneath the transactions key. The key of each
link specifies that links relation to the current resource, and in this case
transactions means “Transactions that occurred in this ledger”. Logically,
you should expect that resource to respond with a collection of transactions
with all of the results having a ledger_sequence attribute equal to 1.
The transactions link is also templated, which means that the href
attribute of the link is actually a URI template, as specified by RFC
6570. We use URI templates to show you
what parameters a give resource can take. You must evaluate the template to a
valid URI before navigating to it.
Pages
TODO
Streaming via Server-Sent Events
TODO
In the event that an error occurs while processing a request to horizon, a
problem response will be returned to the client. This problem response will
contain information detailing why the request couldn’t complete successfully.
Like HAL for successful responses, horizon uses a standard to specify how we
communicate errors to the client. Specifically, horizon uses the Problem
Details for HTTP APIs draft specification. The specification is short, so we recommend
you read it. In summary, when a problem occurs on the server we respond with a
json document with the following attributes:
| name |
type |
description |
| type |
url |
The identifier for the problem, expressed as a url. Visiting the url in a web browser will redirect you to the additional documentation for the problem. |
| title |
string |
A short title describing the problem. |
| status |
number |
An HTTP status code that maps to the problem. A problem that is triggered due to client input will be in the 400-499 range of status code, for exmaple. |
| detail |
string |
A longer description of the problem meant the further explain to problem to developers. |
| instance |
string |
A token that uniquely identifies this request. Allows server administrators to correlate a client report with server log files |
|
|
|
Standard Problems
There are a set of problems that can occur in any request to horizon which we
call standard problems. These problems are:
XDR, also known as External Data Representation, is used extensively in
the Stellar Network, especially the core. The ledger, transactions, results,
history, and even the messages passed between computers running stellar-core
are encoded using XDR.
XDR is specified in RFC 4506.
Since XDR is a binary format, not known as widely as JSON for example, we try
to hide most of it from Horizon. Instead, we opt to interpret the XDR for you
and present the values as JSON attributes. That said, we also expose the XDR
to your so you can get access to the raw, canonical data.
NOTE: While Horizon is in development, you can get the most complete access
access to data by reading XDR.
In general, horizon will render the xdr structures encoded in base64 so that it
is capable to transmit within a json body. You should decode the base64 string
into a byte stream, then decode the XDR into in memory data structures.
.X files
Data structures in XDR are specified in an interface definition file (IDL).
The IDL files used for the Stellar Network are available
on github.
Transaction resources are the basic unit of change in the Stellar Network.
A transaction is a grouping of operations.
Attributes
| Attribute |
Type |
|
| id |
string |
The canonical id of this transaction, suitable for use as the :id parameter for url templates that require a transaction’s ID. |
| paging_token |
string |
A paging token suitable for use as the cursor parameter to transaction collection resources. |
| hash |
string |
A hex-encoded SHA-256 hash of the transaction’s XDR-encoded form. |
| ledger |
number |
Sequence number of the ledger in which this transaction was applied. null if the transaction is failed or unvalidated. |
| account |
string |
|
| account_sequence |
number |
|
| max_fee |
number |
The maximum fee willing to be paid by the transaction creator, expressed in a native currency amount. |
| fee_paid |
number |
The fee paid by the source account of this transaction when the transaction was applied to the ledger. |
| operation_count |
number |
The number of operations that are contained within this transaction. |
| result_code |
number |
The numeric result code for this transaction |
| result_code_s |
string |
|
| envelope_xdr |
string |
A base64 encoded string of the raw TransactionEnvelope xdr struct for this transaction |
| result_xdr |
string |
A base64 encoded string of the raw TransactionResultPair xdr struct for this transaction |
| result_meta_xdr |
string |
A base64 encoded string of the raw TransactionMeta xdr struct for this transaction |
Links
| rel |
Example |
Relation |
| self |
/transactions/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a |
|
| account |
/accounts/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC |
The source account for this transaction. |
| ledger |
/ledgers/3 |
The ledger in which this transaction was applied. |
| operations |
/transactions/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a/operations |
|
| effects |
/transactions/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a/effects |
|
| precedes |
/transactions?cursor=12884905984&order=asc |
A collection of transactions that occure after this transaction. |
| succeeds |
/transactions?cursor=12884905984&order=desc |
A collection of transactions that occur before this transaction. |
Example
//TODO
Endpoints
Pages are objects that represent a subset of objects from a larger collection.
As an example, it would be unfeasible to provide the
All Transactions endpoint without paging; Over time there
will be millions of transactions in the Stellar network’s ledger and returning
them all over a single request would be unfeasible.
Attributes
A page itself exposes no attributes. It is merely a container for embedded
records and some links to aid in iterating the entire collection the page is
part of.
Embedded Resources
A page contains an embedded set of records, regardless of the contained
resource.
Links
A page provides a couple of links to ease in iteration.
|
Example |
Relation |
| self |
/transactions |
|
| prev |
/transactions?cursor=12884905984&order=desc&limit=10 |
The previous page of results |
| next |
/transactions?cursor=12884905984&order=asc&limit=10 |
The next page of results |
Example
{
"_embedded": {
"records": [
{
"_links": {
"self": {
"href": "/operations/12884905984"
},
"transaction": {
"href": "/transaction/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a"
},
"precedes": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=asc{?limit}",
"templated": true
},
"succeeds": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=desc{?limit}",
"templated": true
}
},
"id": 12884905984,
"paging_token": "12884905984",
"type": 0,
"type_s": "payment",
"sender": "gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC",
"receiver": "gsKuurNYgtBhTSFfsCaWqNb3Ze5Je9csKTSLfjo8Ko2b1f66ayZ",
"currency": {
"code": "XLM"
},
"amount": 1000000000,
"amount_f": 100.00
}
]
},
"_links": {
"next": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=asc&limit=100"
},
"prev": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=desc&limit=100"
},
"self": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?limit=100"
}
}
}
Endpoints
Any endpoint that provides a collection of resources should represent them as
pages.
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.
An operation is one of six types: Payment, Create Offer, Set Options, Change
Trust, Allow Trust, Account Merge, and Inflation. See the section “Operation
Types” below.
Every operation type share a set of common attributes and links, but contain
additional attributes and links specific to its types.
Common Attributes
|
Type |
|
| id |
number |
The canonical id of this operation, suitable for use as the :id parameter for url templates that require an operation’s ID |
| paging_token |
any |
|
| type |
number |
Specifies the type of operation, See “Types” section below for reference. |
| type_s |
string |
A string representation of the type of operation |
Common Links
|
Example |
Relation |
| self |
|
|
| succeeds |
|
|
| precedes |
|
|
| transaction |
|
The transaction this operation is part of |
Operation Types
There are sevent different operation types:
| type_s |
type |
| payment |
0 |
| create_offer |
1 |
| set_options |
2 |
| change_trust |
3 |
| allow_trust |
4 |
| account_merge |
5 |
| inflation |
6 |
Each operation type will have a different set of attributes, in addition to the
common attributes listed above.
Payment
A payment operation represents a payment from one account to another. This payment
can be either a simple native currency payment or a fiat currency payment.
Attributes
|
Type |
|
| sender |
string |
address of sender |
| receiver |
string |
|
| currency |
object |
|
| currency.code |
string |
|
| currency.issuer |
string |
|
| amount |
number |
|
| amount_f |
number |
|
| path |
array |
|
Links
|
Example |
Relation |
| sender |
/accounts/gT9jHoPKoErFwXavCrDYLkSVcVd9oyVv94ydrq6FnPMXpKHPTA |
Sending account |
| receiver |
/accounts/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC |
Receiving account |
Example
{
"_links": {
"self": {
"href": "/operations/12884905984"
},
"transaction": {
"href": "/transaction/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a"
},
"precedes": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=asc{?limit}",
"templated": true
},
"succeeds": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=desc{?limit}",
"templated": true
}
},
"id": 12884905984,
"paging_token": "12884905984",
"type": 0,
"type_s": "payment",
"sender": "gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC",
"receiver": "gsKuurNYgtBhTSFfsCaWqNb3Ze5Je9csKTSLfjo8Ko2b1f66ayZ",
"currency": {
"code": "XLM"
},
"amount": 1000000000,
"amount_f": 100.00
}
Create Offer
A “Create Offer” operation represents the desire of an account to trade
currencies. It specifies an order book, a price and amount of currency to
buy or sell.
When this operation is applied to the ledger, trades will be executed by
matching this operation with crossing offers, executing trades in an attempt to
completely will this offer.
In the event that there are not enough crossing orders to fill the order completely
a new “Offer” object will be created in the ledger. As other accounts make
offers or payments, this offer will be filled when possible.
Attributes
Links
|
Example |
Relation |
| orderbook |
|
The orderbook the offer was posted to |
|
|
|
Set Options
TODO
Change Trust
TODO
Allow Trust
TODO
Account Merge
TODO
Inflation
TODO
Endpoints
This endpoint responds with a collection of Payment operations
resources for the account specified in the arguments. Specifically, any payment
in which the specified account participates, either as sender or receiver.
This endpoint is particularly useful for following along with payments made by
an account. A client can retrieve quick notification about payments made to a
specific account by using response streaming.
Request
GET /accounts/{id}/payments{?cursor}{?limit}{?order}
Arguments
| name |
loc |
notes |
example |
description |
| id |
path |
required, string |
gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC |
The address of the account used to constrain results. |
| cursor |
query |
optional,
default "" |
8589934592 |
A payment paging token specifying from where to begin results. |
| limit |
query |
optional, number,
default 10 |
500 |
Specifies the count of records at most to return. |
| order |
query |
optional, string,
default "asc" |
desc |
Specifies order of returned results. "asc" means older payments first, "desc" mean newer payments first. |
Example
# retrieve the first 25 payment for account
curl https://horizon-testnet.stellar.org/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?limit=25
Response
This endpoint responds with a page of payment operations.
Example
{
"_embedded": {
"records": [
{
"_links": {
"self": {
"href": "/operations/12884905984"
},
"transaction": {
"href": "/transaction/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a"
},
"precedes": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=asc{?limit}",
"templated": true
},
"succeeds": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=desc{?limit}",
"templated": true
}
},
"id": 12884905984,
"paging_token": "12884905984",
"type": 0,
"type_s": "payment",
"sender": "gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC",
"receiver": "gsKuurNYgtBhTSFfsCaWqNb3Ze5Je9csKTSLfjo8Ko2b1f66ayZ",
"currency": {
"code": "XLM"
},
"amount": 1000000000,
"amount_f": 100.00
}
]
},
"_links": {
"next": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments?cursor=12884905984&order=asc{?limit}",
"templated": true
},
"self": {
"href": "/account/gspbxqXqEUZkiCCEFFCN9Vu4FLucdjLLdLcsV6E82Qc1T7ehsTC/payments"
}
}
}
Problems
This endpoint should only respond with standard errors.
Tutorials
Posts a new transaction to the Stellar Network. Note that creating a valid
transactions and signing it properly should be the responsibility of your
client library.
Also note, this endpoint is presently a very thin wrapper around the raw
transaction submission endpoint in stellar-core. This endpoint will probably
change quite soon to reflect more of the design choices made by the rest of
horizon
Request
POST /transactions
Arguments
| name |
loc |
notes |
example |
description |
tx |
body |
required |
899b2840ed5636c56ddc5f14b23975f79f1ba2388d2694e4c56ecdddc960e5ef
0000000a000000000000000100000000ffffffff000000010000000000000000
500e14fe9d7dc549e30244da424cfbcabe2166a55237897473d3f7358a086b48
00000000000009184e72a000000000000000000000000000000009184e72a000
00000001899b28402e992cc5fc6d7e0f888b7afa173a35d3ce87526bc37d8171
e2d9ee7f2715d1d4146a9026b13396ab8e7392f947caba1b00d398801b4644ae
5238f96f96ec7605 |
|
Example
curl https://horizon-testnet.stellar.org/transactions \
-X POST \
-F "tx=899b2840ed5636c56ddc5f14b23975f79f1ba2388d2694e4c56ecdddc960e5ef0000000a000000000000000100000000ffffffff000000010000000000000000500e14fe9d7dc549e30244da424cfbcabe2166a55237897473d3f7358a086b4800000000000009184e72a000000000000000000000000000000009184e72a00000000001899b28402e992cc5fc6d7e0f888b7afa173a35d3ce87526bc37d8171e2d9ee7f2715d1d4146a9026b13396ab8e7392f947caba1b00d398801b4644ae5238f96f96ec7605"
Response
This endpoint returns a resource that represents the result of initial
submission of the provided transaction to stellar-core.
Attributes
| Name |
Type |
|
hash |
string |
A hex-encoded hash of the submitted transaction. |
result |
string |
Distilled summary of the result. See “Result” section below. |
submission_result |
string |
A hex-encoded TransactionResult XDR object. |
Result
The result attribute of a response from this endpoint can be one of the following values:
result |
|
| malformed |
The transaction was suffiently malformed that we could not interpet it. |
| already_finished |
The hash for this transaction hash is either in the history database or is in the stellar core database. |
| received |
The transaction was submitted and received by stellar core, and will be included in consideration for a validared ledger |
| failed |
The submission to stellar core failed, and was not recieved by the network. Refer to the submission_result for details. |
| connection_failed |
Horizon could not connect to stellar core. |
Example
{
"hash": "802da5683737972e5a0a6d8d4960bb43a7be64a1dbc00549eeb31729f94c75f2",
"result": "failed",
"submission_result": "0000000000000000fffffffb"
}
Problems
This endpoint should only respond with [standard errors][se].
The transaction details endpoint provides information on a single transaction
within the ledger. The transaction hash provided in the hash argument specifies
which transaction to load
Request
GET /transactions/{hash}
Arguments
| name |
type |
description |
example |
hash |
string |
A transaction hash, hex-encoded |
6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a |
Example
curl https://horizon-testnet.stellar.org/transactions/6391dd190f15f7d1665ba53c63842e368f485651a53d8d852ed442a446d1c69a
Response
This endpoint responds with a single Transaction. See transaction resource for reference.
Example
TODO
Problems
- The standard errors.
- not_found: A
not_found problem will be returned if there is no transaction in the ledger whose hash matches the hash argument.
A not_found problem is returned from horizon when the resource a client is
requesting is not found. This is similar to a “404 Not Found” error response
you get from HTTP.
Example
{
"type": "https://www.stellar.org/docs/horizon/problems/not_found",
"title": "Resource Missing",
"status": 404,
"details": "The resource .... not found.",
"instance": "d3465740-ec3a-4a0b-9d4a-c9ea734ce58a"
}
Tips for resolution
Ensure that the URL is correct, pay special attention to any path parameters,
as this is usually where something is wrong. Additionally, you should be
never see this error message when navigating from a link read from a response.
Ensure the data exists. For example, if you are requesting the details of a
transaction, you will receive a not_found error in the event that the
transaction you are requesting failed.
A server_error problem is returned from horizon when an error occurs within
the code for horizon. This error code is a catchall, and it could reflect any
number of errors in the server: A configuration mistake, a database connection
error, a bug, etc.
NOTE: Even though Horizon is an open source project, we do not directly expose error information such as stack traces or raw error messages, as they may exposes sensitive configuration data such as secret keys.
Example
{
"type": "https://www.stellar.org/docs/horizon/problems/server_error",
"title": "Internal Server Error",
"status": 500,
"details": "...",
"instance": "d3465740-ec3a-4a0b-9d4a-c9ea734ce58a"
}
Tips for resolution
If you are encountering this problem on a server you control, please check the
horizon log files for more details. The logs should contain stack traces and
more detailed information to help you discover the root issue.
If encountering this problem on the public stellar infrastructure, report an
issue on horizon’s issue tracker. Please include at a minimum the
instance attribute from the problem response, but additional information
such as the original request that triggered the problem is always welcome and
speeds our ability to identify the problem.