Ripple-REST API

The Ripple-REST API provides a simplified, easy-to-use interface to the Ripple Network via a RESTful API. This page explains how to use the API to send and receive payments on Ripple.

We recommend Ripple-REST for users just getting started with Ripple, since it provides high-level abstractions and convenient simplifications in the data format. If you prefer to access a rippled server directly, you can use rippled's WebSocket or JSON-RPC APIs instead, which provide the full power of Ripple at the cost of more complexity.

Available API Routes

Accounts

• Generate Wallet - GET /v1/wallet/new
• Get Account Balances - GET /v1/accounts/{:address}/balances
• Get Account Settings - GET /v1/accounts/{:address}/settings
• Update Account Settings - POST /v1/accounts/{:address}/settings

Payments

• Prepare Payment - GET /v1/accounts/{:source_address}/payments/paths/{:destination_address}/{:amount}
• Submit Payment - POST /v1/accounts/{:source_address}/payments
• Confirm Payment - GET /v1/accounts/{:address}/payments/{:id}
• Get Payment History - GET /v1/accounts/{:address}/payments

Orders

• Place Order - POST /v1/accounts/{:address}/orders
• Cancel Order - DELETE /v1/accounts/{:address}/orders/{:sequence}
• Get Account Orders - GET /v1/accounts/{:address}/orders
• Get Order Book - GET /v1/accounts/{:address}/order_book/{:base}/{:counter}
• Get Order Transaction - GET /v1/accounts{:address}/orders/{:hash}

Trustlines

• Get Trustlines - GET /v1/accounts/{:address}/trustlines
• Grant Trustline - POST /v1/accounts/{:address}/trustlines

Notifications

• Check Notifications - GET /v1/accounts/{:address}/notifications/{:id}

Status

• Check Connection - GET /v1/server/connected
• Get Server Status - GET /v1/server

Utilities

• Retrieve Ripple Transaction - GET /v1/transactions/{:id}
• Retrieve Transaction Fee - GET /v1/transaction-fee
• Generate UUID - GET /v1/uuid

API Overview

Ripple Concepts

Ripple is a system for making financial transactions. You can use Ripple to send money anywhere in the world, in any currency, instantly and for free.

In the Ripple world, each account is identified by a Ripple Address. A Ripple address is a string that uniquely identifies an account, for example: rNsJKf3kaxvFvR8RrDi9P3LBk2Zp6VL8mp

A Ripple payment can be sent using Ripple's native currency, XRP, directly from one account to another. Payments can also be sent in other currencies, for example US dollars, Euros, Pounds or Bitcoins, though the process is slightly more complicated.

Payments are made between two accounts, by specifying the source and destination address for those accounts. A payment also involves an amount, which includes both the numeric amount and the currency, for example: 100+XRP.

When you make a payment in a currency other than XRP, you also need to include the Ripple address of the counterparty. The counterparty is the gateway or other entity who holds the funds on your behalf. For non-XRP payments, the amount looks something like this: 100+USD+rNsJKf3kaxvFvR8RrDi9P3LBk2Zp6VL8mp.

Although the Ripple-REST API provides a high-level interface to Ripple, there are also API methods for checking the status of the rippled server and retrieving a Ripple transaction in its native format.

Sending Payments

Sending a payment involves three steps:

1. Generate the payment object with the Prepare Payment method. If the payment is not a direct send of XRP from one account to another, the Ripple system identifies the chain of trust, or path, that connects the source and destination accounts, and includes it in the payment object.
2. Modify the payment object if desired, and then submit it to the API for processing. Caution: Making many changes to the payment object increases the chances of causing an error.
3. Finally, confirm that the payment has completed, using the Confirm Payment method. Payment submission is an asynchronous process, so payments can fail even after they have been submitted successfully.

When you submit a payment for processing, you assign a unique client resource identifier to that payment. This is a string which uniquely identifies the payment, and ensures that you do not accidentally submit the same payment twice. You can also use the client_resource_id to retrieve a payment once it has been submitted.

Transaction Types

The Ripple protocol supports multiple types of transactions, not just payments. Transactions are considered to be any changes to the database made on behalf of a Ripple Address. Transactions are first constructed and then submitted to the network. After transaction processing, meta data is associated with the transaction which itemizes the resulting changes to the ledger.

• Payment: A Payment transaction is an authorized transfer of balance from one address to another. (This maps to rippled's Payment transaction type)
• Trustline: A Trustline transaction is an authorized grant of trust between two addresses. (This maps to rippled's TrustSet transaction type)
• Setting: A Setting transaction is an authorized update of account flags under a Ripple Account. (This maps to rippled's AccountSet transaction type)

Client Resource IDs

All Ripple transactions are identified by a unique hash, which is generated with the fields of the transaction. Ripple-REST uses an additional type of identifier, called a Client Resource ID, which is an arbitrary string provided at the time a transaction is submitted.

A client resource ID generally maps to one Ripple transaction. However, if Ripple-REST re-submits a failed transaction, the client resource ID can become associated with the new transaction, which may have slightly different properties (such as the deadline for it to succeed) and therefore a different transaction hash.

You can create client resource IDs using any method you like, so long as you follow some simple rules:

• Do not reuse identifiers.
• A client resource ID cannot be a 256-bit hex string, because that is ambiguous with Ripple transaction hashes.
• Client resource IDs must be properly encoded when provided as part of a URL.

You can use the Create Client Resource ID method in order to generate new Client Resource IDs.

Using Ripple-REST

You don't need to do any setup to retrieve information from a public Ripple-REST server. Ripple Labs hosts a public Ripple-REST server here:

https://api.ripple.com

If you want to run your own Ripple-REST server, see the installation instructions.

In order to submit payments or other transactions, you need an activated Ripple account. See the online support for how you can create an account using the Ripple Trade client.

Make sure you know both the account address and the account secret for your account:

• The address can be found by clicking the Show Address button in the Fund tab of Ripple Trade
• The secret is provided when you first create your account. WARNING: If you submit your secret to a server you do not control, your account can be stolen, along with all the money in it. We recommend using a test account with very limited funds on the public Ripple-REST server.

As a programmer, you will also need to have a suitable HTTP client that allows you to make secure HTTP (HTTPS) GET and POST requests. For testing, there are lots of options, including:

• The curl commandline utility
• The Poster Firefox extension
• The Postman Chrome extension

You can also use the REST API Tool here on the Dev Portal to try out the API.

Try it! >

Exploring the API

A REST API makes resources available via HTTP, the same protocol used by your browser to access the web. This means you can even use your browser to get a response from the API. Try visiting the following URL:

https://api.ripple.com/v1/server

The response should be a page with content similar to the following:

{
  "rippled_server_url": "wss://s-west.ripple.com:443",
  "rippled_server_status": {
    "build_version": "0.23.0",
    "complete_ledgers": "5526705-6142138",
    "fetch_pack": 2004,
    "hostid": "NEAT",
    "last_close": {
      "converge_time_s": 2.005,
      "proposers": 5
    },
    "load_factor": 1,
    "peers": 55,
    "pubkey_node": "n9KmrBnGoyVf89WYdiAnvGnKFaVqjLdAYjKrBuvg2r8pMxGPp6MF",
    "server_state": "full",
    "validated_ledger": {
      "age": 1,
      "base_fee_xrp": 0.00001,
      "hash": "BADDAB671EF21E8ED56B21253123D2C74139FE34E12DBE4B1F5527772EC88494",
      "reserve_base_xrp": 20,
      "reserve_inc_xrp": 5,
      "seq": 6142138
    },
    "validation_quorum": 3
  },
  "success": true,
  "api_documentation_url": "https://github.com/ripple/ripple-rest"
}

If you want to connect to your own server, just replace the hostname and port with the location of your instance. For example, if you are running Ripple-REST locally on port 5990, you can access the same information at the following URL:

http://localhost:5990/v1/server

Since the hostname depends on where your chosen Ripple-REST instance is, the methods in this document are identified using only the part of the path that comes after the hostname.

Running Ripple-REST

Quick Start

Ripple-REST requires Node.js and sqlite 3. Before starting, you should make sure that you have both installed.

Following that, use these instructions to get Ripple-REST installed and running:

1. Clone the Ripple-REST repository with git: git clone https://github.com/ripple/ripple-rest.git
2. Switch to the ripple-rest directory: cd ripple-rest
3. Use npm to install additional dependencies: npm install
4. Copy the example config file to config.json: cp config-example.json config.json
5. Start the server: npm start
6. Visit http://localhost:5990 in a browser to view available endpoints and get started

Configuring ripple-rest

The Ripple-REST server uses nconf to load configuration options from several sources. Settings from sources earlier in the following hierarchy override settings from the later levels:

1. Command line arguments
2. Environment variables
3. The config.json file

The path to the config.json file can be specified as a command line argument (node server.js --config /path/to/config.json). If no path is specified, the default location for that file is Ripple-REST's root directory.

Available configuration options are outlined in the Server Configuration document. The config-example.json file in the root directory contains a sample configuration.

Debug mode

The server can be run in Debug Mode by running node server.js --debug.

Running Ripple-REST securely over SSL

We highly recommend running Ripple-REST securely over SSL. Doing so requires a certificate. For development and internal-only deployments, you can use a self-signed certificate. For production servers that are accessed over untrusted network connections, you should purchase a cert from a proper authority.

You can perform the following steps to generate a self-signed cert with OpenSSL and configure Ripple-REST to use it:

1. Generate the SSL certificate:

openssl genrsa -out /etc/ssl/private/server.key 2048
openssl req -utf8 -new -key /etc/ssl/private/server.key -out /etc/ssl/server.csr -sha512
-batch
openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/server.key
-out /etc/ssl/certs/server.crt -sha512

1. Modify the config.json to enable SSL and specify the paths to the certificate and key files

  "ssl_enabled": true,
  "ssl": {
    "key_path": "./certs/server.key",
    "cert_path": "./certs/server.crt"
  },

Deployment Tips

Keeping the service running

Monitor ripple-rest using monit. On Ubuntu you can install monit using sudo apt-get install monit.

Here is an example of a monit script that will restart the server if:

• memory usage surpasses 25% of the server's available memory
• the server fails responding to server status

set httpd port 2812 and allow localhost

check process ripple-rest with pidfile /var/run/ripple-rest/ripple-rest.pid
    start program = "/etc/init.d/ripple-rest start"
    stop program = "/etc/init.d/ripple-rest stop"
    if memory > 25% then restart
    if failed port 5990 protocol HTTP
        and request "/v1/server"
    then restart

Formatting Conventions

The ripple-rest API conforms to the following general behavior for RESTful API:

• You make HTTP (or HTTPS) requests to the API endpoint, indicating the desired resources within the URL itself. (The public server, for the sake of security, only accepts HTTPS requests.)
• The HTTP method identifies what you are trying to do. Generally, HTTP GET requests are used to retrieve information, while HTTP POST requests are used to make changes or submit information.
• If more complicated information needs to be sent, it will be included as JSON-formatted data within the body of the HTTP POST request.
  • This means that you must set Content-Type: application/json in the headers when sending POST requests with a body.
• Upon successful completion, the server returns an HTTP status code of 200 OK, and a Content-Type value of application/json. The body of the response will be a JSON-formatted object containing the information returned by the endpoint.

As an additional convention, all responses from Ripple-REST contain a "success" field with a boolean value indicating whether or not the success

Errors

When errors occur, the server returns an HTTP status code in the 400-599 range, depending on the type of error. The body of the response contains more detailed information on the cause of the problem.

In general, the HTTP status code is indicative of where the problem occurred:

• Codes in the 200-299 range indicate success. (Note: This behavior is new in Ripple-REST v1.3.0. Previous versions sometimes return 200 OK for some types of errors.)
  • Unless otherwise specified, methods are expected to return 200 OK on success.
• Codes in the 400-499 range indicate that the request was invalid or incorrect somehow. For example:
  • 400 Bad Request occurs if the JSON body is malformed. This includes syntax errors as well as when invalid or mutually-exclusive options are selected.
  • 404 Not Found occurs if the path specified does not exist, or does not support that method (for example, trying to POST to a URL that only serves GET requests)
• Codes in the 500-599 range indicate that the server experienced a problem. This could be due to a network outage or a bug in the software somewhere. For example:
  • 500 Internal Server Error occurs when the server does not catch an error. This is always a bug. If you can reproduce the error, file it at our bug tracker.
  • 502 Bad Gateway occurs if Ripple-REST could not contact its rippled server at all.
  • 504 Gateway Timeout occurs if the rippled server took too long to respond to the Ripple-REST server.

When possible, the server provides a JSON response body with more information about the error. These responses contain the following fields:

Example error:

{
    "success": false,
    "error_type": "invalid_request",
    "error": "Invalid parameter: destination_amount",
    "message": "Non-XRP payment must have an issuer"
}

Quoted Numbers

In any case where a large number should be specified, Ripple-REST uses a string instead of the native JSON number type. This avoids problems with JSON libraries which might automatically convert numbers into native types with differing range and precision.

You should parse these numbers into a numeric data type with adequate precision. If it is not clear how much precision you need, we recommend using an arbitrary-precision data type.

Currency Amounts

There are two kinds of currency on the Ripple network: XRP, and issuances. XRP is the native cryptocurrency that only exists in the network, and can be held by accounts and sent directly to other accounts with no trust necessary.

All other currencies take the form of issuances, which are held in the trust lines that link accounts. Issuances are identified by a counterparty on the other end of the trust line. Sending and trading issuances actually means debiting the balance of a trust line and crediting the balance of another trust line linked to the same account. Ripple ensures this operation happens atomically.

Issuances are typically created by Gateway accounts in exchange for assets in the outside world. In most cases, the counterparty of a currency refers to the gateway that created the issuances. XRP never has a counterparty.

You can read more about XRP and Gateways in the Knowledge Center.

Amounts in JSON

When an amount of currency is specified as part of a JSON body, it is encoded as an object with three fields:

Example Amount Object:

{
  "value": "1.0",
  "currency": "USD",
  "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
}

or for XRP:

{
  "value": "1.0",
  "currency": "XRP",
  "counterparty": ""
}

The value field can get very large or very small. See the Currency Format for the exact limits of Ripple's precision.

Amounts in URLs

When an amount of currency has to be specified in a URL, you use the same fields as the JSON object -- value, currency, and counterparty -- but concatenate them with + symbols in that order.

Example Amount:

1.0+USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q

When specifying an amount of XRP, you must omit the counterparty entirely. For example:

1.0+XRP

Counterparties in Payments

Most of the time, the counterparty field of a non-XRP currency indicates the account of the gateway that issues that currency. However, when describing payments, there are a few nuances that are important:

• There is only ever one balance for the same currency between two accounts. This means that, sometimes, the counterparty field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.
• You can omit the counterparty from the destination_amount of a payment to mean "any counterparty that the destination accepts". This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines.
  • For compatibility with rippled, setting the counterparty of the destination_amount to be the destination account's address means the same thing.
• You can omit the counterparty from the source_amount of a payment to mean "any counterparty the source can use". This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.
  • Similarly, setting the counterparty of the source_amount to be the source account's address means the same thing.

Payment Objects

The Payment object is a simplified version of the standard Ripple transaction format.

This Payment format is intended to be straightforward to create and parse, from strongly or loosely typed programming languages. Once a transaction is processed and validated it also includes information about the final details of the payment.

An example Payment object looks like this:

{
 
    "source_address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
    "source_tag": "",
    "source_amount": {
        "value": "0.001",
        "currency": "XRP",
        "issuer": ""
    },
    "source_slippage": "0",
    "destination_address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
    "destination_tag": "",
    "destination_amount": {
        "value": "0.001",
        "currency": "XRP",
        "issuer": ""
    },
    "invoice_id": "",
    "paths": "[]",
    "flag_no_direct_ripple": false,
    "flag_partial_payment": false
}

The fields of a Payment object are defined as follows:

Submitted transactions can have additional fields reflecting the current status and outcome of the transaction, including:

[Source]

Memo Objects

(New in Ripple-REST v1.3.0)

Memo objects represent arbitrary data that can be included in a transaction. The overall size of the memos field cannot exceed 1KB after serialization.

Each Memo object must have at least one of the following fields:

The MemoType field is intended to support URIs, so the contents of that field should only contain characters that are valid in URIs. In other words, MemoType should only consist of the following characters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%

Example of the memos field:

    "memos": [
      {
        "MemoType": "unformatted_memo",
        "MemoData": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum是指一篇常用於排版設計領域的拉丁文文章，主要的目的為測試文章或文字在不同字型、版型下看起來的效果。Lorem ipsum es el texto que se usa habitualmente en diseño gráfico en demostraciones de tipografías o de borradores de diseño para probar el diseño visual antes de insertar el texto final."
      },
      {
        "MemoData": "Fusce est est, malesuada in tincidunt mattis, auctor eu magna."
      }
    ]

Order Objects

(New in Ripple-REST 1.4.0)

An order object describes an offer to exchange two currencies. Order objects are used when creating or looking up individual orders.

Order Change Objects

An order change object describes the changes to to a Ripple account's open order due to a transaction.

Bid Objects

An bid object describes an offer to exchange two currencies, including the current funding status of the offer. Bid objects are used to describe bids and asks when retrieving an order book.

Trustline Objects

A trustline object describes a link between two accounts that allows one to hold the other's issuances. A trustline can also be two-way, meaning that each can hold balances issued by the other, but that case is less common. In other words, a trustline tracks money owed.

A trustline with a positive limit indicates an account accepts issuances from the other account (typically an issuing gateway) as payment, up to the limit. An account cannot receive a payment that increases its balance over that trust limit. It is possible, however, to go over a limit by either by trading currencies or by decreasing the limit while already holding a balance.

From the perspective of an account on one side of the trustline, the trustline has the following fields:

The read-only fields indicate portions of the trustline that pertain to the counterparty, and can only be changed by that account. (The counterparty field is technically part of the identity of the trustline. If you "change" it, that just means that you are referring to a different trustline object.)

A trust line with a limit and a balance of 0 is equivalent to no trust line.

ACCOUNTS

Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account’s secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The account reserve increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.

Generate Wallet

(New in Ripple-REST v1.3.0)

Randomly generate keys for a potential new Ripple account.

GET /v1/wallet/new

Try it! >

There are two steps to making a new account on the Ripple network: randomly creating the keys for that account, and sending it enough XRP to meet the account reserve.

Generating the keys can be done offline, since it does not affect the network at all. To make it easy, Ripple-REST can generate account keys for you.

Caution: Ripple account keys are very sensitive, since they give full control over that account's money on the Ripple network. Do not transmit them to untrusted servers, or unencrypted over the internet (for example, through HTTP instead of HTTPS). There are bad actors who are sniffing around for account keys so they can steal your money!

Response

The response is an object with the address and the secret for a potential new account:

{
    "success": true,
    "account": {
        "address": "raqFu9wswvHYS4q5hZqZxVSYei73DQnKL8",
        "secret": "shUzHiYxoXX2FgA54j42cXCZ9dTVT"
    }
}

The second step is making a payment of XRP to the new account address. (Ripple lets you send XRP to any mathematically possible account address, which creates the account if necessary.) The generated account does not exist in the ledger until it receives enough XRP to meet the account reserve.

Get Account Balances

[Source]

Retrieve the current balances for the given Ripple account.

GET /v1/accounts/{:address}/balances

Try it! >

The following URL parameters are required by this API endpoint:

Optionally, you can also include any of the following query parameters:

Note: Pagination using limit and marker requires a consistent ledger version, so you must also provide the ledger hash or sequence query parameter to use pagination.

Caution: When an account holds balances on a very large number of trust lines, specifying limit=all may take a long time or even time out. If you experience timeouts, try again later, or specify a smaller limit.

Response

{
  "success": true,
  "marker": "0C812C919D343EAE789B29E8027C62C5792C22172D37EA2B2C0121D2381F80E1",
  "limit": 200,
  "ledger": 10478339,
  "validated": true,
  "balances": [
    {
      "currency": "XRP",
      "amount": "1046.29877312",
      "counterparty": ""
    },
    {
      "currency": "USD",
      "amount": "512.79",
      "counterparty": "r...",
    }
    ...
  ]
}

Note: marker will be present in the response when there are additional pages to page through.

There is one entry in the balances array for the account's XRP balance, and additional entries for each combination of currency code and counterparty.

Get Account Settings

[Source]

Retrieve the current settings for a given account.

GET /v1/accounts/{:address}/settings

Try it! >

The following URL parameters are required by this API endpoint:

Response

{
  "success": true,
  "settings": {
    "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "transfer_rate": "",
    "password_spent": false,
    "require_destination_tag": false,
    "require_authorization": false,
    "disallow_xrp": false,
    "disable_master": false,
    "transaction_sequence": "36",
    "email_hash": "",
    "wallet_locator": "",
    "wallet_size": "",
    "message_key": "0000000000000000000000070000000300",
    "domain": "mduo13.com",
    "signers": ""
  }
}

The response contains a settings object, with the following fields:

Update Account Settings

[Source]

Modify the existing settings for an account.

POST /v1/accounts/{:address}/settings?validated=true

{
  "secret": "sssssssssssssssssssssssssssss",
  "settings": {
    "transfer_rate": 1.02,
    "require_destination_tag": false,
    "require_authorization": false,
    "disallow_xrp": false,
    "disable_master": false,
    "default_ripple": false
    "transaction_sequence": 22,
  }
}

Try it! >

The following URL parameters are required by this API endpoint:

The request body must be a JSON object with the following fields:

Optionally, you can include the following as a URL query parameter:

DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts.

The settings object can contain any of the following fields (any omitted fields are left unchanged):

Note: Some of the account setting fields cannot be modified by this method. For example, the password_spent flag is only enabled when the account uses a free SetRegularKey transaction, and only disabled when the account receives a transmission of XRP.

Response

{
  "success": true,
  "settings": {
    "require_destination_tag": false,
    "require_authorization": false,
    "disallow_xrp": false,
    "email_hash": "98b4375e1d753e5b91627516f6d70977",
    "state": "pending",
    "ledger": "9248628",
    "hash": "81FA244915767DAF65B0ACF262C88ABC60E9437A4A1B728F7A9F932E727B82C6"
  }
}

The response is a JSON object containing the following fields:

PAYMENTS

ripple-rest provides access to ripple-lib's robust transaction submission processes. This means that it will set the fee, manage the transaction sequence numbers, sign the transaction with your secret, and resubmit the transaction up to 10 times if rippled reports an initial error that can be solved automatically.

Prepare Payment

[Source]

Get quotes for possible ways to make a particular payment.

GET /v1/accounts/{:source_address}/payments/paths/{:destination_address}/{:amount}

Try it! >

The following URL parameters are required by this API endpoint:

Optionally, you can also include the following as a query parameter:

Before you make a payment, it is necessary to figure out the possible ways in which that payment can be made. This method gets a list possible ways to make a payment, but it does not affect the network. This method effectively performs a ripple_path_find and constructs payment objects for the paths it finds.

You can then choose one of the returned payment objects, modify it as desired (for example, to set slippage values or tags), and then submit the payment for processing.

Response

{
  "success": true,
  "payments": [
    {
      "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
      "source_tag": "",
      "source_amount": {
        "value": "1.008413509923106",
        "currency": "USD",
        "issuer": ""
      },
      "source_slippage": "0",
      "destination_account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
      "destination_tag": "",
      "destination_amount": {
        "value": "1",
        "currency": "USD",
        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
      },
      "invoice_id": "",
      "paths": "[[{\"account\":\"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"currency\":\"USD\",\"issuer\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}],[{\"account\":\"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"currency\":\"XRP\",\"type\":16,\"type_hex\":\"0000000000000010\"},{\"currency\":\"USD\",\"issuer\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}]]",
      "partial_payment": false,
      "no_direct_ripple": false
    },
    {
      "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
      "source_tag": "",
      "source_amount": {
        "value": "61.06103",
        "currency": "XRP",
        "issuer": ""
      },
      "source_slippage": "0",
      "destination_account": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH",
      "destination_tag": "",
      "destination_amount": {
        "value": "1",
        "currency": "USD",
        "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
      },
      "invoice_id": "",
      "paths": "[[{\"currency\":\"USD\",\"issuer\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}],[{\"currency\":\"USD\",\"issuer\":\"rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rHAwwozJw6FHfnJfRQaFXrkGHocGoaNYSy\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}],[{\"currency\":\"USD\",\"issuer\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rEtr3Kzh5MmhPbeNu6PDtQZsKBpgFEEEo5\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}],[{\"currency\":\"USD\",\"issuer\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\",\"type\":48,\"type_hex\":\"0000000000000030\"},{\"account\":\"rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rKvPTQrD8ap1Y8TSmKjcK6G7q7Kvx7RAqQ\",\"type\":1,\"type_hex\":\"0000000000000001\"},{\"account\":\"rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q\",\"type\":1,\"type_hex\":\"0000000000000001\"}]]",
      "partial_payment": false,
      "no_direct_ripple": false
    }
  ]
}

You can then select the desired payment, modify it if necessary, and submit the payment object to the POST /v1/accounts/{address}/payments endpoint for processing.

NOTE: This command may be quite slow. If the command times out, please try it again.

Submit Payment

[Source]

Submit a payment object to be processed and executed.

POST /v1/accounts/{address}/payments?validated=true

{
  "secret": "s...",
  "client_resource_id": "123",
  "last_ledger_sequence": "1...",
  "max_fee": "0.1",
  "fixed_fee": "0.01",
  "payment": {
    "source_account": "rBEXjfD3MuXKATePRwrk4AqgqzuD9JjQqv",
    "source_tag": "",
    "source_amount": {
      "value": "5.01",
      "currency": "USD",
      "issuer": ""
    },
    "source_slippage": "0",
    "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
    "destination_tag": "",
    "destination_amount": {
      "value": "5",
      "currency": "USD",
      "issuer": ""
    },
    "invoice_id": "",
    "paths": "[[{\"account\":\"rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B\",\"type\":1,\"type_hex\":\"0000000000000001\"}]]",
    "partial_payment": false,
    "no_direct_ripple": false
  }
}

Try it! >

The JSON body of the request includes the following parameters:

DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts.

Note: The transaction fee is determined as follows:

1. If fixed_fee is included, that exact value is used for the transaction fee. Otherwise, the transaction fee is set dynamically based on the server's current fee.
2. If max_fee is included and the transaction fee is higher than max_fee, then the transaction is rejected without being submitted. This is true regardless of whether the fee was fixed or dynamically set. Otherwise, the transaction is submitted to the rippled server with the specified fee.
3. If the transaction succeeds, the sending account loses the whole amount of the transaction fee, even if it was higher than the server's current fee.
4. If the transaction fails because the fee was not high enough, Ripple-REST automatically resubmits it later. In this case, return to step 1.

Consequently, you can use max_fee as a "set-it-and-forget-it" safeguard on the fees you are willing to pay.

Optionally, you can include the following as a URL query parameter:

Response

The response can take two formats, depending on the validated query parameter:

• If validated is set to true, then the response matches the format from Confirm Payment.
• If validated is omitted or set to false, then the response is a JSON object as follows:

{
  "success": true,
  "client_resource_id": "123",
  "status_url": ".../v1/accounts/r1.../payments/123"
}

Confirm Payment

[Source]

Retrieve the details of a payment, including the current state of the transaction and the result of transaction processing.

GET /v1/accounts/{:address}/payments/{:id}

Try it! >

The following URL parameters are required by this API endpoint:

Response

{
  "success": true,
  "payment": {
    "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "source_tag": "",
    "source_amount": {
      "value": "0.00001",
      "currency": "XRP",
      "issuer": ""
    },
    "source_slippage": "0",
    "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
    "destination_tag": "",
    "destination_amount": {
      "value": "0.00000005080000000000001",
      "currency": "USD",
      "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
    },
    "invoice_id": "",
    "paths": "[]",
    "no_direct_ripple": false,
    "partial_payment": true,
    "direction": "outgoing",
    "result": "tesSUCCESS",
    "timestamp": "2014-09-17T21:47:00.000Z",
    "fee": "0.00001",
    "balance_changes": [{
      "currency": "XRP",
      "value": "-0.00002",
      "counterparty": ""
    }],
    "source_balance_changes": [{
      "currency": "XRP",
      "value": "-0.00002",
      "counterparty": ""
    }],
    "destination_balance_changes": [{
      "currency": "USD",
      "value": "5.08e-8",
      "counterparty": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
    }],
    "order_changes": [],
    "destination_amount_submitted": {
      "value": "0.01",
      "currency": "USD",
      "counterparty": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
    },
    "source_amount_submitted": {
      "value": "0.00001",
      "currency": "XRP",
      "counterparty": ""
    }
  },
  "client_resource_id": "",
  "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
  "ledger": "8924146",
  "state": "validated"
}

New in v1.4.0 - The hash, ledger, and state fields have been moved to the top level. Previously, they were included as part of the Payment object.

If the state field has the value validated, then the payment has been finalized, and is included in the shared global ledger. However, this does not necessarily mean that it succeeded. Check the result field of the Payment for a value of "tesSUCCESS" to see if the payment was successfully executed. If the payment.partial_payment flag is true, then you should also consult the payment.destination_balance_changes array to see how much currency was actually delivered to the destination account.

Processing a payment can take several seconds to complete, depending on the consensus process. If the payment does not exist yet, or has not been validated, you should wait a few seconds before checking again.

Get Payment History

[Source]

Retrieve a selection of payments that affected the specified account.

GET /v1/accounts/{:address}/payments

Try it! >

The following URL parameters are required by this API endpoint:

Optionally, you can also include the following query parameters:

Response

{
  "success": true,
  "payments": [{
    "payment": {
      "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
      "source_tag": "",
      "source_amount": {
        "value": "20",
        "currency": "XRP",
        "issuer": ""
      },
      "source_slippage": "0",
      "destination_account": "raKEEVSGnKSD9Zyvxu4z6Pqpm4ABH8FS6n",
      "destination_tag": "",
      "destination_amount": {
        "value": "20",
        "currency": "XRP",
        "issuer": ""
      },
      "invoice_id": "",
      "paths": "[]",
      "no_direct_ripple": false,
      "partial_payment": false,
      "direction": "outgoing",
      "result": "tesSUCCESS",
      "timestamp": "2015-02-09T23:31:40.000Z",
      "fee": "0.012",
      "balance_changes": [{
        "currency": "XRP",
        "value": "-20.012",
        "counterparty": ""
      }],
      "source_balance_changes": [{
        "currency": "XRP",
        "value": "-20.012",
        "counterparty": ""
      }],
      "destination_balance_changes": [{
        "currency": "XRP",
        "value": "20",
        "counterparty": ""
      }],
      "order_changes": []
    },
    "client_resource_id": "",
    "hash": "1D381C0FCA00E8C34A6D4D3A91DAC9F3697B4E66BC49ED3D9B2D6F57D7F15E2E",
    "ledger": "11620700",
    "state": "validated"
  }
]

If the length of the payments array is equal to results_per_page, then there may be more results. To get them, increment the page query paramter and run the request again.

Note: It is not more efficient to specify more filter values, because Ripple-REST has to retrieve the full list of payments from the rippled before it can filter them.

ORDERS

Place Order

[Source]

(New in Ripple-REST v1.3.2)

Places an order to exchange currencies.

POST /v1/accounts/{:address}/orders?validated=true
{
    "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
    "order": {
        "type": "sell",
        "taker_pays": {
            "currency": "JPY",
            "counterparty": "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6",
            "value": "4000"
        },
        "taker_gets": {
            "currency": "USD",
            "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
            "value": ".25"
        }
    }
}

Try it! >

The following URL parameters are required by this API endpoint:

The following parameters are required in the JSON body of the request:

Optionally, you can include the following as a URL query parameter:

DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts.

Response

{
  "success": true,
  "order": {
    "hash": "71AE74B03DE3B9A06C559AD4D173A362D96B7D2A5AA35F56B9EF21543D627F34",
    "ledger": "9592219",
    "state": "validated",
    "account": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
    "taker_pays": {
      "currency": "JPY",
      "counterparty": "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6",
      "value": "4000"
    },
    "taker_gets": {
      "currency": "USD",
      "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
      "value": ".25"
    },
    "fee": "0.012",
    "type": "sell",
    "sequence": 99
  }
}

Cancel Order

[Source]

Deletes a previous order to exchange currencies.

DELETE /v1/accounts/{:address}/orders/{:order}?validated=true
{
    "secret": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9"
}

Try it! >

The following URL parameters are required by this API endpoint:

The following parameters are required in the JSON body of the request:

Note: Some older client libraries do not support a body for the DELETE method. If this is a problem for you, please file an issue in Ripple Labs' bug tracker.

Optionally, you can include the following as a URL query parameter:

DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts.

Response

{
  "success": true,
  "order": {
    "hash": "71AE74B03DE3B9A06C559AD4D173A362D96B7D2A5AA35F56B9EF21543D627F34",
    "ledger": "9592219",
    "state": "validated",
    "account": "sn3nxiW7v8KXzPzAqzyHXbSSKNuN9",
    "fee": "0.012",
    "offer_sequence": 99,
    "sequence": 100
  }
}

Get Account Orders

[Source]

Retrieves all open currency-exchange orders associated with the Ripple address.

GET /v1/accounts/{:address}/orders

Try it! >

The following URL parameters are required by this API endpoint:

Optionally, you can also include the following query parameters:

Note: Pagination using limit and marker requires a consistent ledger version, so you must also provide the ledger query parameter to use pagination. marker will be present in the response when there are additional pages to page through.

Response

The response is an object with a orders array, where each member is a order object.

{
  "success": true,
  "ledger": 11561783,
  "validated": true,
  "orders": [
    {
      "type": "buy",
      "taker_gets": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "11205.2494363431"
      },
      "taker_pays": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "9933.731769807718"
      },
      "sequence": 11,
      "passive": false
    },
    {
      "type": "sell",
      "taker_gets": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "9229.29"
      },
      "taker_pays": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "10447.55628"
      },
      "sequence": 12,
      "passive": false
    },
    {
      "type": "buy",
      "taker_gets": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "5600"
      },
      "taker_pays": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "5000"
      },
      "sequence": 13,
      "passive": false
    },
    {
      "type": "buy",
      "taker_gets": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "4.7"
      },
      "taker_pays": {
        "currency": "XRP",
        "counterparty": "",
        "value": "997.876857"
      },
      "sequence": 14,
      "passive": false
    },
    {
      "type": "sell",
      "taker_gets": {
        "currency": "XRP",
        "counterparty": "",
        "value": "999"
      },
      "taker_pays": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "4.74525"
      },
      "sequence": 15,
      "passive": false
    },
    {
      "type": "buy",
      "taker_gets": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "5.35"
      },
      "taker_pays": {
        "currency": "XRP",
        "counterparty": "",
        "value": "998.134328"
      },
      "sequence": 16,
      "passive": false
    },
    {
      "type": "sell",
      "taker_gets": {
        "currency": "XRP",
        "counterparty": "",
        "value": "999"
      },
      "taker_pays": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "5.96403"
      },
      "sequence": 17,
      "passive": false
    },
    {
      "type": "buy",
      "taker_gets": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "1103.64"
      },
      "taker_pays": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "976.6725663716827"
      },
      "sequence": 18,
      "passive": false
    },
    {
      "type": "sell",
      "taker_gets": {
        "currency": "USD",
        "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By",
        "value": "986.89"
      },
      "taker_pays": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "1116.17259"
      },
      "sequence": 19,
      "passive": false
    },
    {
      "type": "sell",
      "taker_gets": {
        "currency": "USD",
        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
        "value": "2"
      },
      "taker_pays": {
        "currency": "CAD",
        "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc",
        "value": "2"
      },
      "sequence": 21,
      "passive": false
    }
  ]
}