Get Started with XRP Ledger APIs

The XRP Ledger's core server software is rippled. You can jump straight into developing on the XRP Ledger by accessing the API of a rippled server.

The quickest way to dive into the API is with the WebSocket API Tool, or use the XRP Ledger Explorer to see watch the progress of the ledger live.

You can also run your own instance of rippled or use a public server.

Public Servers

Ripple provides several public servers for the benefit of the XRP Ledger community:

Operator Network JSON-RPC URL WebSocket URL Notes
Ripple Mainnet https://s1.ripple.com:51234/ wss://s1.ripple.com/ General purpose server cluster
Ripple Mainnet https://s2.ripple.com:51234/ wss://s2.ripple.com/ Full-history server cluster
Ripple Testnet https://s.altnet.rippletest.net:51234/ wss://s.altnet.rippletest.net/ Testnet public server
Ripple Devnet https://s.devnet.rippletest.net:51234/ wss://s.devnet.rippletest.net/ Devnet public 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.

Admin Access

To use a rippled server's 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.

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.

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.

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.

See Also