Get Started with the rippled API

Before you can run any commands against a rippled server, you must know which server you are connecting to. Most servers are configured not to accept API requests directly from the outside network.

Alternatively, you can run your own local copy of rippled. This is required if you want to access any of the Admin Methods. In this case, you should use whatever IP and port you configured the server to bind. (For example, 127.0.0.1:54321) Additionally, to access admin functionality, you must connect from a port/IP address marked as admin in the 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 Ripple WebSocket API Tool. Later on, when you want to connect to your own rippled server, you can build your own client in the browser or in Node.js.

Request Formatting

After you open a WebSocket to the rippled server, you can send commands as a JSON object, with the following attributes:

  • Put command name in top-level "command" field
  • All the relevant parameters for the command are also in the top level
  • Optionally include an "id" field with an arbitrary value. The response to this request uses the same "id" field. This way, even if responses arrive out of order, you know which request prompted which response.

The response comes as a JSON object.

Public Servers

Currently Ripple (the company) maintains a set of public WebSocket servers at:

Domain Port Notes
s1.ripple.com 443 wss:// only; general purpose server
s2.ripple.com 443 wss:// only; full-history server

These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own rippled server or contract someone you trust to do so.

JSON-RPC

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

Request Formatting

To make a JSON-RPC request, send an HTTP POST request to the root path (/) on the port and IP where the rippled server is listening for JSON-RPC connections. You can use HTTP/1.0 or HTTP/1.1. If you use HTTPS, you should use TLS v1.2. For security reasons, rippled does not support SSL v3 or earlier.

Always include a Content-Type header with the value application/json.

If you plan on making multiple requests, use Keep-Alives so that you do not have to close and re-open the connection in between requests.

Send request body as a JSON object with the following attributes:

  • Put the command in the top-level "method" field
  • Include a top-level "params" field. The contents of this field should be a one-item array containing only a nested JSON object with all the parameters for the command.

The response is also a JSON object.

Public Servers

Currently, Ripple (the company) maintains a set of public JSON-RPC servers at:

Domain Port Notes
s1.ripple.com 51234 General purpose server
s2.ripple.com 51234 Full-history server

These public servers are not for sustained or business use, and they may become unavailable at any time. For regular use, you should run your own rippled server or contract someone you trust to do so.

Commandline

The commandline interface connects to the same service as the JSON-RPC one, so the public servers and server configuration are the same. As a commandline client, rippled connects to the local instance. For example:

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

Note: The commandline interface is intended for administrative purposes only and is not a supported API.

Request Formatting

The commandline puts the command after any normal (dash-prefaced) commandline options, followed by a limited set of parameters, separated by spaces. For any parameter values that might contain spaces or other unusual characters, use single-quotes to encapsulate them.

Example Request

{
  "id": 2,
  "command": "account_info",
  "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
  "strict": true,
  "ledger_index": "validated"
}
POST http://s1.ripple.com:51234/
{
    "method": "account_info",
    "params": [
        {
            "account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
            "strict": true,
            "ledger_index": "validated"
        }
    ]
}
rippled account_info r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59 validated true

Response Formatting

Example Successful Response

{
  "id": 2,
  "status": "success",
  "type": "response",
  "result": {
    "account_data": {
      "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
      "Balance": "27389517749",
      "Flags": 0,
      "LedgerEntryType": "AccountRoot",
      "OwnerCount": 18,
      "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
      "PreviousTxnLgrSeq": 6592159,
      "Sequence": 1400,
      "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
    },
    "ledger_index": 6760970
  }
}
HTTP Status: 200 OK
{
    "result": {
        "account_data": {
            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
            "Balance": "27389517749",
            "Flags": 0,
            "LedgerEntryType": "AccountRoot",
            "OwnerCount": 18,
            "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
            "PreviousTxnLgrSeq": 6592159,
            "Sequence": 1400,
            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
        },
        "ledger_index": 6761012,
        "status": "success"
    }
}
{
    "result": {
        "account_data": {
            "Account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
            "Balance": "27389517749",
            "Flags": 0,
            "LedgerEntryType": "AccountRoot",
            "OwnerCount": 18,
            "PreviousTxnID": "B6B410172C0B65575D89E464AF5B99937CC568822929ABF87DA75CBD11911932",
            "PreviousTxnLgrSeq": 6592159,
            "Sequence": 1400,
            "index": "4F83A2CF7E70F77F79A307E6A472BFC2585B806A70833CCD1C26105BAE0D6E05"
        },
        "ledger_index": 6761012,
        "status": "success"
    }
}

The fields of a successful response include:

Field Type Description
id (Varies) (WebSocket only) ID provided in the request that prompted this response
status String (WebSocket only) The value success indicates the request was successfully received and understood by the server.
result.status String (JSON-RPC and Commandline) The value success indicates the request was successfully received and understood by the server.
type String (WebSocket only) The value response indicates a successful response to a command. Asynchronous notifications use a different value such as ledgerClosed or transaction.
result Object The result of the query; contents vary depending on the command.

Commandline

The response format for commandline methods is the same as JSON-RPC responses, because they use the same interface.