Server

Server

Server handles the network connection to a Horizon instance and exposes an interface for requests to that instance.

Constructor

new Server(serverURL, optsopt)

Source:
Parameters:
Name Type Attributes Description
serverURL string

Horizon Server URL (ex. https://horizon-testnet.stellar.org).

opts object <optional>

Options object

Name Type Attributes Description
allowHttp boolean <optional>

Allow connecting to http servers, default: false. This must be set to false in production deployments! You can also use Config class to set this globally.

Methods

accounts() → {AccountCallBuilder}

Source:
Returns:
Type:
AccountCallBuilder

New AccountCallBuilder object configured by a current Horizon server configuration.

assets() → {AssetsCallBuilder}

Get a new AssetsCallBuilder instance configured with the current Horizon server configuration.

Source:
Returns:
Type:
AssetsCallBuilder

New AssetsCallBuilder instance

effects() → {EffectCallBuilder}

Source:
Returns:
Type:
EffectCallBuilder

New EffectCallBuilder instance configured with the current Horizon server configuration

fetchBaseFee() → {Promise.<number>}

Fetch the base fee. Since this hits the server, if the server call fails, you might get an error. You should be prepared to use a default value if that happens!

Source:
Returns:
Type:
Promise.<number>

Promise that resolves to the base fee.

fetchTimebounds(seconds, _isRetryopt) → {Promise.<number>}

Get timebounds for N seconds from now, when you're creating a transaction with TransactionBuilder.

By default, TransactionBuilder uses the current local time, but your machine's local time could be different from Horizon's. This gives you more assurance that your timebounds will reflect what you want.

Note that this will generate your timebounds when you init the transaction, not when you build or submit the transaction! So give yourself enough time to get the transaction built and signed before submitting.

Example:

const transaction = new StellarSdk.TransactionBuilder(accountId, {
 fee: await StellarSdk.Server.fetchBaseFee(),
 timebounds: await StellarSdk.Server.fetchTimebounds(100)
})
 .addOperation(operation)
 // normally we would need to call setTimeout here, but setting timebounds
 // earlier does the trick!
 .build();
Source:
Parameters:
Name Type Attributes Default Description
seconds number

Number of seconds past the current time to wait.

_isRetry bool <optional>
false

True if this is a retry. Only set this internally! This is to avoid a scenario where Horizon is horking up the wrong date.

Returns:
Type:
Promise.<number>

Promise that resolves a timebounds object (with the shape { minTime: 0, maxTime: N }) that you can set the timebounds option to.

ledgers() → {LedgerCallBuilder}

Source:
Returns:
Type:
LedgerCallBuilder

New LedgerCallBuilder object configured by a current Horizon server configuration.

loadAccount(accountId) → {Promise}

Fetches an account's most current state in the ledger and then creates and returns an Account object.

Source:
Parameters:
Name Type Description
accountId string

The account to load.

Returns:
Type:
Promise

Returns a promise to the AccountResponse object with populated sequence number.

offers(resource, …resourceParams) → {OfferCallBuilder}

People on the Stellar network can make offers to buy or sell assets. This endpoint represents all the offers a particular account makes. Currently this method only supports querying offers for account and should be used like this:

server.offers('accounts', accountId).call()
 .then(function(offers) {
   console.log(offers);
 });
Source:
Parameters:
Name Type Attributes Description
resource string

Resource to query offers

resourceParams string <repeatable>

Parameters for selected resource

Returns:
Type:
OfferCallBuilder

New OfferCallBuilder object

operationFeeStats() → {Promise}

Fetch the operation fee stats endpoint.

Source:
See:
Returns:
Type:
Promise

Promise that resolves to the fee stats returned by Horizon.

operations() → {OperationCallBuilder}

Source:
Returns:
Type:
OperationCallBuilder

New OperationCallBuilder object configured by a current Horizon server configuration.

orderbook(selling, buying) → {OrderbookCallBuilder}

Source:
Parameters:
Name Type Description
selling Asset

Asset being sold

buying Asset

Asset being bought

Returns:
Type:
OrderbookCallBuilder

New OrderbookCallBuilder object configured by a current Horizon server configuration.

paths(source, destination, destinationAsset, destinationAmount) → {PathCallBuilder}

The Stellar Network allows payments to be made between assets through path payments. A path payment specifies a series of assets to route a payment through, from source asset (the asset debited from the payer) to destination asset (the asset credited to the payee).

A path search is specified using:

  • The destination address
  • The source address
  • The asset and amount that the destination account should receive

As part of the search, horizon will load a list of assets available to the source address and will find any payment paths from those source assets to the desired destination asset. The search's amount parameter will be used to determine if there a given path can satisfy a payment of the desired amount.

Source:
Parameters:
Name Type Description
source string

The sender's account ID. Any returned path will use a source that the sender can hold.

destination string

The destination account ID that any returned path should use.

destinationAsset Asset

The destination asset.

destinationAmount string

The amount, denominated in the destination asset, that any returned path should be able to satisfy.

Returns:
Type:
PathCallBuilder

New PathCallBuilder object configured with the current Horizon server configuration.

payments() → {PaymentCallBuilder}

Source:
Returns:
Type:
PaymentCallBuilder

New PaymentCallBuilder instance configured with the current Horizon server configuration.

submitTransaction(transaction) → {Promise}

Submits a transaction to the network.

If you submit any number of manageOffer operations, this will add an attribute to the response that will help you analyze what happened with your offers.

Ex:

const res = {
  ...response,
  offerResults: [
    {
      // Exact ordered list of offers that executed, with the exception
      // that the last one may not have executed entirely.
      offersClaimed: [
        sellerId: String,
        offerId: String,
        assetSold: {
          type: 'native|credit_alphanum4|credit_alphanum12',

          // these are only present if the asset is not native
          assetCode: String,
          issuer: String,
        },

        // same shape as assetSold
        assetBought: {}
      ],

      // What effect your manageOffer op had
      effect: "manageOfferCreated|manageOfferUpdated|manageOfferDeleted",

      // Whether your offer immediately got matched and filled
      wasImmediatelyFilled: Boolean,

      // Whether your offer immediately got deleted, if for example the order was too small
      wasImmediatelyDeleted: Boolean,

      // Whether the offer was partially, but not completely, filled
      wasPartiallyFilled: Boolean,

      // The full requested amount of the offer is open for matching
      isFullyOpen: Boolean,

      // The total amount of tokens bought / sold during transaction execution
      amountBought: Number,
      amountSold: Number,

      // if the offer was created, updated, or partially filled, this is
      // the outstanding offer
      currentOffer: {
        offerId: String,
        amount: String,
        price: {
          n: String,
          d: String,
        },

        selling: {
          type: 'native|credit_alphanum4|credit_alphanum12',

          // these are only present if the asset is not native
          assetCode: String,
          issuer: String,
        },

        // same as `selling`
        buying: {},
      },

      // the index of this particular operation in the op stack
      operationIndex: Number
    }
  ]
}

For example, you'll want to examine offerResults to add affordances like these to your app:

  • If wasImmediatelyFilled is true, then no offer was created. So if you normally watch the Server.offers endpoint for offer updates, you instead need to check Server.trades to find the result of this filled offer.
  • If wasImmediatelyDeleted is true, then the offer you submitted was deleted without reaching the orderbook or being matched (possibly because your amounts were rounded down to zero). So treat the just-submitted offer request as if it never happened.
  • If wasPartiallyFilled is true, you can tell the user that amountBought or amountSold have already been transferred.
Source:
See:
Parameters:
Name Type Description
transaction Transaction

The transaction to submit.

Returns:
Type:
Promise

Promise that resolves or rejects with response from horizon.

tradeAggregation(base, counter, start_time, end_time, resolution, offset) → {TradeAggregationCallBuilder}

Source:
Parameters:
Name Type Description
base Asset

base asset

counter Asset

counter asset

start_time long

lower time boundary represented as millis since epoch

end_time long

upper time boundary represented as millis since epoch

resolution long

segment duration as millis since epoch. *Supported values are 5 minutes (300000), 15 minutes (900000), 1 hour (3600000), 1 day (86400000) and 1 week (604800000).

offset long

segments can be offset using this parameter. Expressed in milliseconds. *Can only be used if the resolution is greater than 1 hour. Value must be in whole hours, less than the provided resolution, and less than 24 hours. Returns new TradeAggregationCallBuilder object configured with the current Horizon server configuration.

Returns:
Type:
TradeAggregationCallBuilder

New TradeAggregationCallBuilder instance

trades() → {TradesCallBuilder}

Returns

Source:
Returns:
Type:
TradesCallBuilder

New TradesCallBuilder object configured by a current Horizon server configuration.

transactions() → {TransactionCallBuilder}

Source:
Returns:
Type:
TransactionCallBuilder

New TransactionCallBuilder object configured by a current Horizon server configuration.