Async Network Clients

Asynchronous network clients for interacting with the XRPL.

class xrpl.asyncio.clients.AsyncJsonRpcClient(url: str)

An async client for interacting with the rippled JSON RPC.

async request(request: Request) → Response

Makes a request with this client and returns the response.

Parameters:

request – The Request to send.

Returns:

The Response for the given Request.

class xrpl.asyncio.clients.AsyncWebsocketClient(url: str)

An async client for interacting with the rippled WebSocket API.

Instead of calling open and close yourself, you can use a context like so:

async with AsyncWebsocketClient(url) as client:
    # inside the context the client is open
# after exiting the context, the client is closed

Doing this will open and close the client for you and is preferred.

NOTE: if you are not using subscriptions or other WebSocket-only features of rippled, you may not need to do anything other than open the client and make requests:

from xrpl.asyncio.clients import AsyncWebsocketClient
from xrpl.asyncio.ledger import get_fee
from xrpl.models import Fee


async with AsyncWebsocketClient(url) as client:
    # using helper functions
    print(await get_fee(client))

    # using raw requests yourself
    print(await client.request(Fee())

However, if you are using some functionality that makes use of subscriptions or other “websocket-y” things, you can iterate over the client like so to read incoming messages:

async with AsyncWebsocketClient(url) as client:
    # inside the context the client is open
    async for message in client:
        # do something with a message
# after exiting the context, the client is closed

The recommended way to use this client is to set up a Task using the asyncio library to listen to incoming messages and do something with them, but the above will work fine if you want to listen indefinitely. This is how you can use a Task to listen to messages without blocking. Note this example can be copied directly into a file and run with no changes:

import asyncio

from xrpl.asyncio.clients import AsyncWebsocketClient
from xrpl.models import Subscribe, Unsubscribe, StreamParameter

URL = "wss://s.altnet.rippletest.net:51233"


def on_open():
    print("I have opened a connection!")


async def on_message(client):
    async for message in client:
        # do something with a message - we'll just print
        print(message)


def on_close():
    print("I have closed a connection cleanly!")


def on_error():
    print("An error occurred!")


async def main():
    # we'll use this to determine if the websocket closed cleanly or
    # not
    error_happened = False

    async with AsyncWebsocketClient(URL) as client:
        try:
            # here you'll run any code that should happen immediately
            # after the connection is made. this is equivalent to the
            # javascript 'open' event
            on_open()

            # set up the `on_message` function as a Task
            # so that it doesn't wait for a response, but
            # will "awaken" whenever the `asyncio` event
            # loop toggles to it. this is equivalent to the javascript
            # 'message' event
            asyncio.create_task(on_message(client))

            # now, the `on_message` function will run as if
            # it were "in the background", doing whatever you
            # want as soon as it has a message.

            # now let's subscribe to something. in this case,
            # we can just use `send` instead of `request`
            # because we don't really care about the response
            # since the `on_message` handler will also get it.
            await client.send(Subscribe(
                streams=[StreamParameter.LEDGER],
            ))
            print("Subscribed to the ledger!")

            # in the meantime, you can continue to do whatever
            # you want and the python `asyncio` event loop
            # will toggle between your code and the listener
            # as messages are ready. let's just sleep. note,
            # you need to use `asyncio.sleep` within
            # async code instead of `time.sleep`, otherwise
            # you will block all the waiting tasks instead of
            # just this code path.
            await asyncio.sleep(50)

            # now that we're done, we can unsubscribe if
            # we like
            await client.send(Unsubscribe(
                streams=[StreamParameter.LEDGER],
            ))
            print("Unsubscribed from the ledger!")
        except:
            # if you wish you perform some logic when the websocket
            # connection closes due to error, you can catch and run
            # whatever you need to here. this is equivalent to the
            # javascript 'error' event
            error_happened = True
            on_error()
    # now, outside of the context, the client is closed.
    # the `on_message` task will now never receive a new message. you
    # can now run any code you need to run after the connection is
    # closed. this is equivalent to the javascript 'close' event
    if not error_happened:
        on_close()


if __name__ == "__main__":
    # remember to run your entire program within a
    # `asyncio.run` call.
    asyncio.run(main())

If you need to ensure that you reconnect your websockets whenever they disconnect, you can create a supervisor like the example below. Note this example can be copied and run directly with no changes:

import asyncio

from xrpl.asyncio.clients import AsyncWebsocketClient
from xrpl.models import Subscribe, StreamParameter

URL = "wss://s.altnet.rippletest.net:51233"


async def websocket_supervisor():
    # whenever the websocket disconnects, for any reason, the loop
    # will restart, reconnect, and set everything up again.
    while True:
        try:
            await long_websocket_task()
        except:
            print("Lost connection! Reconnecting")


async def on_message(client):
    async for message in client:
        print(message)


async def long_websocket_task():
    async with AsyncWebsocketClient(URL) as client:
        # set up a listener task
        listener = asyncio.create_task(on_message(client))

        # subscribe to the ledger
        await client.send(Subscribe(
            streams=[StreamParameter.LEDGER],
        ))

        # sleep infinitely until the connection closes on us
        while client.is_open():
            await asyncio.sleep(0)
        listener.cancel()


async def main():
    await websocket_supervisor()


if __name__ == "__main__":
    asyncio.run(main())

async close() → None

Closes the connection.

is_open() → bool

Returns whether the client is currently open.

Returns:

True if the client is currently open, False otherwise.

async open() → None

Connects the client to the Web Socket API at the given URL.

async request(request: Request) → Response

Makes a request with this client and returns the response.

Parameters:

request – The Request to send.

Returns:

The Response for the given Request.

async send(request: Request) → None

Submit the request represented by the request to the rippled node specified by this client’s URL. Unlike request, send does not wait for this request’s response. In many cases it may be more convenient to use request.

Parameters:

request – A Request object representing information about a rippled request.

Raises:

XRPLWebsocketException – If there is already an open request by the request’s ID, or if this WebsocketBase is not open.

exception xrpl.asyncio.clients.XRPLRequestFailureException(result: Dict[str, Any])

XRPL Request Exception, when the request fails.

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

xrpl.asyncio.clients.json_to_response(json: Dict[str, Any]) → Response

Converts a JSON response from the rippled server into a Response object.

Parameters:

json – A dictionary representing the contents of the json response from the rippled server.

Returns:

A Response object containing the information in the rippled server’s response.

xrpl.asyncio.clients.request_to_json_rpc(request_object: Request) → Dict[str, Any]

Converts a request model object to the appropriate JSON format for interacting with the rippled API.

Parameters:

request_object – A Request object representing the parameters of a request to the rippled JSON RPC.

Returns:

A dictionary containing the attributes of this Request object formatted for submission to the rippled JSON RPC.

xrpl.asyncio.clients.request_to_websocket(request_object: Request) → Dict[str, Any]

Converts a request model object to the appropriate format for interacting with the rippled API via the WebSocket API.

Parameters:

request_object – A Request object representing the parameters of a request to the rippled JSON RPC.

Returns:

A dictionary containing the attributes of this Request object formatted for submission to the rippled WebSocket API.

xrpl.asyncio.clients.websocket_to_response(response_dict: Dict[str, Any]) → Response

Converts a WebSocket API response from the rippled server into a Response object.

Parameters:

response_dict – A dictionary representing the contents of the WebSocket API response from the rippled server.

Returns:

A Response object containing the information in the rippled server’s response.