Subscribe

The subscribe method requests periodic notifications from the server when certain events happen.

Request Format

wss://xrp.nownodes.io/wss/{{API-KEY}

An example of the messages:

• Subscribe to accounts

{
  "id": "Example watch Bitstamp's hot wallet",
  "command": "subscribe",
  "accounts": ["rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1"]
}

• Subscribe to order book

{
    "id": "Example subscribe to XRP/GateHub USD order book",
    "command": "subscribe",
    "books": [
        {
            "taker_pays": {
                "currency": "XRP"
            },
            "taker_gets": {
                "currency": "USD",
                "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq"
            },
            "snapshot": true
        }
    ]
}

• Subscribe to ledger stream

{
  "id": "Example watch for new validated ledgers",
  "command": "subscribe",
  "streams": ["ledger"]
}

The request includes the following parameters:

Field	Type	Required?	Description
streams	Array	No	Streams to subscribe to, as explained below. Each member of the array must be the string name of a stream.
accounts	Array	No	Array with the unique [addresses][Address] of accounts to monitor for validated transactions. The server sends a transaction type message whenever a transaction affects at least one of these accounts.
accounts_proposed	Array	No	Like accounts, but include transactions that are not yet finalized.
books	Array	No	Order books to monitor for updates. Each member of the array must be a book object, as defined below. The server sends a transaction type message whenever a transaction affects this account.
url	String	Optional for Websocket; Required for JSON-RPC	(Admin only) URL where the server sends JSON-RPC callbacks for each event.
url_username	String	No	Username to provide for basic authentication at the callback URL.
url_password	String	No	Password to provide for basic authentication at the callback URL.

The following parameters are deprecated and may be removed without further notice: user, password, rt_accounts.

The streams parameter provides access to the following default streams of information:

Stream Name	Message Type	Description
book_changes	bookChanges	Sends order book changes whenever the consensus process declares a new validated ledger.
consensus	consensusPhase	Sends a message whenever the server changes phase in the consensus cycle.
ledger	ledgerClosed	Sends a message whenever the consensus process declares a new validated ledger.
manifests	manifestReceived	Sends a message whenever the server receives an update to a validator's ephemeral signing key.
peer_status	peerStatusChange	(Admin only) Information about connected peer rippled servers, especially with regards to the consensus process.
transactions	transaction	Sends a message whenever a transaction is included in a closed ledger.
transactions_proposed	transaction	Sends a message whenever a transaction is included in a closed ledger, as well as some transactions that have not yet been included in a validated ledger and may never be. Not all proposed transactions appear before validation.

Response Format

An example of a successful response:

{
  "id": "Example watch Bitstamp's hot wallet",
  "status": "success",
  "type": "response",
  "result": {}
}

The fields contained in the response vary depending on what subscriptions were included in the request.

• accounts and accounts_proposed - No fields returned.

• Stream: server - Information about the server status, such as load_base (the current load level of the server), random (a randomly-generated value), and others, subject to change.

• Stream: transactions, Stream: transactions_proposed, Stream: validations, and Stream: consensus - No fields returned.

• Stream: ledger - Information about the ledgers on hand and current fee schedule. This includes the same fields as a ledger stream message, except that it omits the type and txn_count fields.

• books - No fields returned by default. If "snapshot": true is set in the request, returns offers (an array of offer definition objects defining the order book).

Possible Errors

• Any of the universal error types.

• invalidParams - One or more fields are specified incorrectly, or one or more required fields are missing.

• noPermission - The request included the url field, but you are not connected as an admin.

• unknownStream - One or more the members of the streams field of the request is not a valid stream name.

• malformedStream - The streams field of the request is not formatted properly.

• malformedAccount - One of the addresses in the accounts or accounts_proposed fields of the request is not a properly-formatted XRP Ledger address. (Note:: You can subscribe to the stream of an address that does not yet have an entry in the global ledger to get a message when that address becomes funded.)

• srcCurMalformed - One or more taker_pays sub-fields of the books field in the request is not formatted properly.

• dstAmtMalformed - One or more taker_gets sub-fields of the books field in the request is not formatted properly.

• srcIsrMalformed - The issuer field of one or more taker_pays sub-fields of the books field in the request is not valid.

• dstIsrMalformed - The issuer field of one or more taker_gets sub-fields of the books field in the request is not valid.

• badMarket - One or more desired order books in the books field does not exist; for example, offers to exchange a currency for itself.