Last updated

Get Started Using HTTP / WebSocket APIs

If you don't have or don't want to use a client library in your preferred programming language, you can access the XRP Ledger directly through the APIs of its core server software, rippled. The server provides APIs over JSON-RPC and WebSocket protocols. If you don't run your own instance of rippled you can still use a public server.

Tip: You can dive right into the API with the WebSocket API Tool, or use the XRP Ledger Explorer to watch the progress of the ledger live.

Differences Between JSON-RPC and WebSocket

Both JSON-RPC and WebSocket are HTTP-based protocols, and for the most part the data provided over both protocols is the same. The major differences are as follows:

  • JSON-RPC uses individual HTTP requests and responses for each call, similar to a RESTful API. You can use any common HTTP client such as curl, Postman, or Requests to access this API.
  • WebSocket uses a persistent connection that allows the server to push data to the client. Functions that require push messages, like event subscriptions, are only available using WebSocket.

Both APIs can be served unencrypted (http:// and ws://) or encrypted using TLS (https:// and wss://). Unencrypted connections should not be served over open networks, but can be used when the client is on the same machine as the server.

Admin Access

The API methods are divided into Public Methods and Admin Methods so that organizations can offer public servers for the benefit of the community. To access admin methods, or admin functionality of public methods, you must connect to the API on a port and IP address marked as admin in the server's config file.

The example config file listens for connections on the local loopback network (127.0.0.1), with JSON-RPC (HTTP) on port 5005 and WebSocket (WS) on port 6006, and treats all connected clients as admin.

WebSocket API

If you are looking to try out some methods on the XRP Ledger, you can skip writing your own WebSocket code and go straight to using the API at the WebSocket API Tool. Later on, when you want to connect to your own rippled server, you can build your own client or use a client library with WebSocket support.

Example WebSocket API request:

{
  "id": "my_first_request",
  "command": "server_info",
  "api_version": 1
}

The response shows you the current status of the server.

Read more: Request Formatting > Response Formatting > About the server_info method >

JSON-RPC

You can use any HTTP client (like RESTED for Firefox, Postman for Chrome or Online HTTP client ExtendsClass) to make JSON-RPC calls a rippled server. Most programming languages have a library for making HTTP requests built in.

Example JSON-RPC request:

POST http://s1.ripple.com:51234/
Content-Type: application/json

{
    "method": "server_info",
    "params": [
        {
            "api_version": 1
        }
    ]
}

The response shows you the current status of the server.

Read more: Request Formatting > Response Formatting > About the server_info method >

Commandline

The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. By default, the commandline connects to a rippled server running on the same machine.

Example commandline request:

rippled --conf=/etc/opt/ripple/rippled.cfg server_info

Read more: Commandline Usage Reference >

Caution: The commandline interface is intended for administrative purposes only and is not a supported API. New versions of rippled may introduce breaking changes to the commandline API without warning!

Available Methods

For a full list of API methods, see:

See Also