Network Clients¶

Synchronous network clients for interacting with the XRPL.

class xrpl.clients.JsonRpcClient(url: str)¶

A sync client for interacting with the rippled JSON RPC.

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.clients.WebsocketClient(url: str, timeout: int | float | None = None)¶

A sync client for interacting with the rippled WebSocket API.

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

with WebsocketClient(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.clients import WebsocketClient
from xrpl.ledger import get_fee
from xrpl.models import Fee


with WebsocketClient(url) as client:
    # using helper functions
    print(get_fee(client))

    # using raw requests yourself
    print(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:

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

NOTE: doing the above will cause the client to listen for messages indefinitely. For this reason, WebsocketClient takes an optional timeout parameter which will stop iterating on messages if none are received in that timeframe. Generally, if you have complex needs with python, xrpl, and websockets, you should consider using the asyncio support provided by this library and the xrpl.asyncio.clients.AsyncWebsocketClient instead.

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.

open() → None¶: Connects the client to the Web Socket API at the given URL.

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.

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 WebsocketClient is not open.

exception xrpl.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.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.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.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.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.