adammendoza/ripple-rest

A RESTful API for submitting payments and monitoring accounts on the Ripple Network

Ripple-REST API

Overview

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/{:address}/payments/paths
• Submit Payment - POST /v1/accounts/{:address}/payments
• Confirm Payment - GET /v1/accounts/{:address}/payments/{:payment}
• Get Payment History - GET /v1/accounts/{:address}/payments

Trustlines

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

Notifications

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

Status

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

Utilities

• Retrieve Ripple Transaction - GET /v1/transactions/{:transaction-hash}
• 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 issuer. The issuer is the gateway or other entity who holds the foreign-currency funds on your behalf. For foreign-currency payments, the amount will look something like this: 100+USD+rNsJKf3kaxvFvR8RrDi9P3LBk2Zp6VL8mp.

While the ripple-rest API provides a high-level interface for sending and receiving payments, there are other endpoints within the API that you can use to work with generic ripple transactions, and to check the status of the Ripple server.

Sending Payments

Sending a payment involves three steps:

1. You need to generate the payment object by doing using what is called a pathfind(preparing a payment). If the payment is to be made in a currency other than XRP, the Ripple system will identify the chain of trust, or path, that connects the source and destination accounts; when creating the payment, the ripple-rest API will automatically find the set of possible paths for you.

2. You can modify the payment object if necessary, and then submit it to the API for processing. It is recommended to submit the payment object generated directly to prevent any errors from occuring.

3. Finally, you have to confirm that the payment has gone through by checking the payment's status. This is because the payment submission is considered an asynchronous process, payments themselves can still fail even after they have been submitted successfully.

Note that when you submit a payment for processing, you have to 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 other than 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)

Getting Started

Setup

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

However, 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! >

Quick Start

ripple-rest requires Node.js and uses sqlite3 as it's database.

Follow these instructions to get your ripple-rest server installed and running

1. Run git clone https://github.com/ripple/ripple-rest.git in a terminal and switch into the ripple-rest directory
2. Install dependencies needed: npm install
3. Copy the config example to config.json: cp config-example.json config.json
4. Run node server.js to start the server
5. Visit http://localhost:5990 to view available endpoints and to get started

Configuring ripple-rest

The ripple-rest server loads configuration options from the following sources, according to the following hierarchy (where options from 1. override those below it):

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 in ripple-rest's root directory.

Available configuration options are outlined in the Server Configuration document and an example configuration file is provided here.

ripple-rest uses the nconf configuration loader so that any options that can be specified in the config.json file can also be specified as command line arguments or environment variables.

Debug mode

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

Running ripple-rest securely over SSL

1. Create SSL certificate to encrypt traffic to and from the ripple-rest server.

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

2. 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

Run ripple-rest using forever. node and npm are required. Install forever using sudo npm install -g forever.

Example of running ripple-rest using forever:

forever start \
    --pidFile /var/run/ripple-rest/ripple-rest.pid \
    --sourceDir /opt/ripple-rest \
    -a -o /var/log/ripple-rest/ripple-rest.log \
    -e /var/log/ripple-rest/ripple-rest.err \
    -l /var/log/ripple-rest/ripple-rest.for \
    server.js

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

Example of a monit script that will restart the server if:

• memory goes up over 25%
• 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

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.

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:

Field	Type	Description
success	Boolean	false indicates that an error occurred.
error_type	String	A short code identifying a general category for the error that occurred.
error	String	A human-readable summary of the error that occurred.
message	String	(May be omitted) A longer human-readable explanation for the error.

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

All currencies on the Ripple Network have issuers, except for XRP. In the case of XRP, the issuer field may be omitted or set to "". Otherwise, the issuer must be a valid Ripple address of the gateway that issues the currency.

For more information about XRP see the Ripple wiki page on XRP. For more information about using currencies other than XRP on the Ripple Network see the Ripple wiki page for gateways.

Amounts in JSON

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

Field	Type	Description
value	String (Quoted decimal)	The quantity of the currency
currency	String	Three-digit ISO 4217 Currency Code specifying which currency
issuer	String	The Ripple address of the account issuing the currency. This is usually an issuing gateway. Always an empty string for XRP.

Example Amount Object:

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

or for XRP:

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

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 issuer -- but concatenate them with + symbols.

Example Amount:

1.0+USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q

When specifying an amount of XRP, omit the issuer entirely. For example:

1.0+XRP

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:

Field	Type	Description
source_account	String	The Ripple address of the account sending the payment
source_amount	Amount Object	The amount to deduct from the account sending the payment.
destination_account	String	The Ripple address of the account receiving the payment
destination_amount	Amount Object	The amount that should be deposited into the account receiving the payment.
source_tag	String (Quoted unsigned integer)	(Optional) A quoted 32-bit unsigned integer (0-4294967294, inclusive) to indicate a sub-category of the source account. Typically, it identifies a hosted wallet at a gateway as the sender of the payment.
destination_tag	String (Quoted unsigned integer)	(Optional) A quoted 32-bit unsigned integer (0-4294967294, inclusive) to indicate a particular sub-category of the destination account. Typically, it identifies a hosted wallet at a gateway as the recipient of the payment.
source_slippage	String (Quoted decimal)	(Optional) Provides the source_amount a cushion to increase its chance of being processed successfully. This is helpful if the payment path changes slightly between the time when a payment options quote is given and when the payment is submitted. The source_address will never be charged more than source_slippage + the value specified in source_amount.
invoice_id	String	(Optional) Arbitrary 256-bit hash that can be used to link payments to an invoice or bill.
paths	String	A "stringified" version of the Ripple PathSet structure. You can get a path for your payment from the Prepare Payment method.
no_direct_ripple	Boolean	(Optional, defaults to false) true if paths are specified and the sender would like the Ripple Network to disregard any direct paths from the source_address to the destination_address. This may be used to take advantage of an arbitrage opportunity or by gateways wishing to issue balances from a hot wallet to a user who has mistakenly set a trustline directly to the hot wallet. Most users will not need to use this option.
partial_payment	Boolean	(Optional, defaults to false) If set to true, fees will be deducted from the delivered amount instead of the sent amount. (Caution: There is no minimum amount that will actually arrive as a result of using this flag; only a miniscule amount may actually be received.) See Partial Payments
memos	Array	(Optional) Array of memo objects, where each object is an arbitrary note to send with this payment.

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

[Source]

Field	Type	Description
direction	String	The direction of the payment relative to the account from the URL, either "outgoing" (sent by the account in the URL) or "incoming" (received by the account in the URL)
state	String	The current status of the payment in transaction processing. A value of "validated" indicates that the transaction is finalized.
result	String	The Ripple transaction status code for the transaction. A value of "tesSUCCESS" indicates a successful transaction.
ledger	String	The sequence number of the ledger version that includes this transaction.
hash	String	A hash value that uniquely identifies this transaction in the Ripple network.
timestamp	String	The time the ledger containing this transaction was validated, as a ISO8601 extended format string in the form YYYY-MM-DDTHH:mm:ss.sssZ.
fee	String (Quoted decimal)	The amount of XRP charged as a transaction fee.
source_balance_changes	Array	Array of Amount objects indicating changes in balances held by the account sending the transaction as a result of the transaction.
destination_balance_changes	Array	Array of Amount objects indicating changes in balances held by the account receiving the transaction as a result of the transaction.

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:

Field	Type	Description
MemoType	String	Arbitrary string, conventionally a unique relation type (according to RFC 5988) that defines the format of this memo.
MemoData	String	Arbitrary UTF-8 string representing the content of the memo.

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."
      }
    ]

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:

Field	Value	Description
account	String (Address)	This account
counterparty	String (Address)	The account at the other end of the trustline
currency	String	Currency code for the type of currency that is held on this trustline.
limit	String (Quoted decimal)	The maximum amount of currency issued by the counterparty account that this account should hold.
reciprocated_limit	String (Quoted decimal)	(Read-only) The maximum amount of currency issued by this account that the counterparty account should hold.
account_allows_rippling	Boolean	(Also known as NoRipple). Prevents other payments from shifting balances to other trustlines that also have this flag set.
counterparty_allows_rippling	Boolean	(Read-only) Whether the counterparty account has NoRipple set.
account_froze_line	Boolean	Indicates whether this account has frozen the trustline.
counterparty_froze_line	Boolean	(Read-only) Indicates whether the counterparty account has frozen the trustline.

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.

REST

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.

REST

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

Try it! >

The following URL parameters are required by this API endpoint:

Field	Type	Description
address	String	The Ripple account address of the account whose balances to retrieve.

Optionally, you can also include the following query parameters:

Field	Type	Description
currency	String (ISO 4217 Currency Code)	If provided, only include balances in the given currency.
counterparty	String (Address)	If provided, only include balances issued by the provided address (usually a gateway).
marker	String	Start position in response paging.
limit	String (Integer)	Max results per response. Will default to 10 if not set or set below 10.
ledger	String	Ledger to request paged results from. Use the ledger's hash.

Note: In order to use paging, you must provide ledger as a URL query parameter.

Response

{
  "success": true,
  "balances": [
    {
      "currency": "XRP",
      "amount": "1046.29877312",
      "issuer": ""
    },
    {
      "currency": "USD",
      "amount": "512.79",
      "issuer": "r...",
    }
    ...
  ]
}

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

Get Account Settings

[Source]

Retrieve the current settings for a given account.

REST

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

Try it! >

The following URL parameters are required by this API endpoint:

Field	Value	Description
address	String	The Ripple account address of the account whose settings to retrieve.

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:

Field	Value	Description
account	String	The Ripple address of this account
transfer_rate	String (Quoted decimal number)	If set, imposes a fee for transferring balances issued by this account. Must be between 1 and 2, with up to 9 decimal places of precision.
password_spent	Boolean	If false, then this account can submit a special SetRegularKey transaction without a transaction fee.
require_destination_tag	Boolean	If true, require a destination tag to send payments to this account. (This is intended to protect users from accidentally omitting the destination tag in a payment to a gateway's hosted wallet.)
require_authorization	Boolean	If true, require authorization for users to hold balances issued by this account. (This prevents users unknown to a gateway from holding funds issued by that gateway.)
disallow_xrp	Boolean	If true, XRP should not be sent to this account. (Enforced in clients but not in the server, because it could cause accounts to become unusable if all their XRP were spent.)
disable_master	Boolean	If true, the master secret key cannot be used to sign transactions for this account. Can only be set to true if a Regular Key is defined for the account.
transaction_sequence	String (Quoted integer)	The sequence number of the next valid transaction for this account. (Each account starts with Sequence = 1 and increases each time a transaction is made.)
email_hash	String	Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image.
wallet_locator	String	(Not used)
wallet_size	String	(Not used)
message_key	A secp256k1 public key that should be used to encrypt secret messages to this account.
domain	String	The domain that holds this account. Clients can use this to verify the account in the ripple.txt or host-meta of the domain.

Update Account Settings

[Source]

Modify the existing settings for an account.

REST

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,
    "transaction_sequence": 22
  }
}

Try it! >

The following URL parameters are required by this API endpoint:

Field	Value	Description
address	String	The Ripple account address of the account whose settings to retrieve.

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

Field	Value	Description
secret	String	A secret key for your Ripple account. This is either the master secret, or a regular secret, if your account has one configured.
settings	Object	A map of settings to change for this account. Any settings not included are left unchanged.

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

Field	Type	Description
validated	String	true or false. When set to true, will force the request to wait until the account transaction has been successfully validated by the server. A validated transaction will have the state attribute set to "validated" in the response.

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):

Field	Value	Description
transfer_rate	String (Quoted decimal number)	If set, imposes a fee for transferring balances issued by this account. Must be between 1 and 2, with up to 9 decimal places of precision.
require_destination_tag	Boolean	If true, require a destination tag to send payments to this account. (This is intended to protect users from accidentally omitting the destination tag in a payment to a gateway's hosted wallet.)
require_authorization	Boolean	If true, require authorization for users to hold balances issued by this account. (This prevents users unknown to a gateway from holding funds issued by that gateway.)
disallow_xrp	Boolean	If true, XRP should not be sent to this account. (Enforced in clients but not in the server, because it could cause accounts to become unusable if all their XRP were spent.)
disable_master	Boolean	If true, the master secret key cannot be used to sign transactions for this account. Can only be set to true if a Regular Key is defined for the account.
transaction_sequence	String (Quoted integer)	The sequence number of the next valid transaction for this account.
email_hash	String	Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image.
message_key	String	A secp256k1 public key that should be used to encrypt secret messages to this account, as hex.
domain	String	The domain that holds this account, as lowercase ASCII. Clients can use this to verify the account in the ripple.txt or host-meta of the domain.

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:

Field	Value	Description
hash	String	A unique hash that identifies the Ripple transaction to change settings
ledger	String (Quoted integer)	The sequence number of the ledger version where the settings-change transaction was applied.
settings	Object	The settings that were changed, as provided in the request.

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.

REST

GET /v1/accounts/{:address}/payments/paths/{:destination_account}/{:destination_amount}

Try it! >

The following URL parameters are required by this API endpoint:

Field	Type	Description
address	String	The Ripple address for the account that would send the payment.
destination_account	String	The Ripple address for the account that would receive the payment.
destination_amount	String (URL-formatted Amount	The amount that the destination account should receive.

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

Field	Type	Description
source_currencies	Comma-separated list of source currencies. Each should be an ISO 4217 currency code, or a {:currency}+{:issuer} string.	Filters possible payments to include only ones that spend the source account's balances in the specified currencies. If an issuer is not specified, include all issuances of that currency held by the sending account.

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": [
    { /* Payment */ },
    { /* Payment */ },
    ...
  ]
}

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.

REST

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

{
  "secret": "s...",
  "client_resource_id": "123",
  "last_ledger_sequence": "1...",
  "max_fee": "100",
  "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 following parameters are required in the JSON body of the request:

Field	Type	Description
payment	Payment object	The payment to send. You can generate a payment object using the Prepare Payment method.
client_resource_id	String	A unique identifier for this payment. You can generate one using the GET /v1/uuid method.
secret	String	A secret key for your Ripple account. This is either the master secret, or a regular secret, if your account has one configured.

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

Field	Type	Description
validated	String	true or false. When set to true, will force the request to wait until the payment has been successfully validated by the server. Response format in this case will match GET /v1/accounts/{:address}/payments/{:payment}

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

Field	Type	Description
last_ledger_sequence	String	A string representation of a ledger sequence number. If this parameter is not set, it defaults to the current ledger sequence plus an appropriate buffer.
max_fee	String	A string representation of a fee amount in drops. If this parameter is not set, it defaults to a median of the connected ripple server fees

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

Note: This response holds when the validated query parameter is not set or set to false. For responses with validated true, please refer to GET /v1/accounts/{:address}/payments/{:payment}

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

Field	Type	Description
client_resource_id	String	The client resource ID provided in the request
status_url	String	A URL that you can GET to check the status of the request. This refers to the Confirm Payment method.

Response (With Validated Parameter)

Confirm Payment

[Source]

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

REST

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

Try it! >

The following URL parameters are required by this API endpoint:

Field	Type	Description
address	String	The Ripple account address of an account involved in the transaction.
id	String	A unique identifier for the transaction: either a client resource ID or a transaction hash.

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": {
      "currency": "USD",
      "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
      "value": "0.01"
    },
    "invoice_id": "",
    "paths": "[]",
    "no_direct_ripple": false,
    "partial_payment": true,
    "direction": "outgoing",
    "state": "validated",
    "result": "tesSUCCESS",
    "ledger": "8924146",
    "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
    "timestamp": "2014-09-17T21:47:00.000Z",
    "fee": "0.00001",
    "source_balance_changes": [
      {
        "value": "-0.00002",
        "currency": "XRP",
        "issuer": ""
      }
    ],
    "destination_balance_changes": [
      {
        "value": "5.08e-8",
        "currency": "USD",
        "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
      }
    ]
  }
}

Field	Type	Description
payment	Object	A payment object for the transaction.

If the payment.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 payment.result field 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.

REST

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

Try it! >

The following URL parameters are required by this API endpoint:

Field	Type	Description
address	String	The Ripple account address of an account involved in the transaction.

Optionally, you can also include the following query parameters:

Field	Type	Description
source_account	String (Address)	If provided, only include payments sent by a given account.
destination_account	String (Address)	If provided, only include payments received by a given account.
exclude_failed	Boolean	If true, only include successful transactions. Defaults to false.
direction	String	If provided, only include payments of the given type. Valid values include "incoming" (payments received by this account) and "outgoing" (payments sent by this account).
earliest_first	Boolean	If true, sort results with the oldest payments first. Defaults to false (sort with the most recent payments first).
start_ledger	Integer (Ledger sequence number)	If provided, exclude payments from ledger versions older than the given ledger.
end_ledger	Integer (Ledger sequence number)	If provided, exclude payments from ledger versions newer than the given ledger.
results_per_page	Integer	The maximum number of payments to be returned at once. Defaults to 10.
page	Integer	The page number for the results to return, if more than results_per_page are available. The first page of results is page 1, the second page is number 2, and so on. Defaults to 1.

Response

{
  "success": true,
  "payments": [
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "source_tag": "",
        "source_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "source_slippage": "0",
        "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "outgoing",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "9018940",
        "hash": "FED24FB85E5682E5FD03D2FFA047E1CE9F284671BCD82007C64B3FE735DD69B0",
        "timestamp": "2014-09-23T19:20:20.000Z",
        "fee": "0.000012",
        "source_balance_changes": [
          {
            "value": "-0.000012",
            "currency": "XRP",
            "issuer": ""
          },
          {
            "value": "-1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "source_tag": "",
        "source_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "source_slippage": "0",
        "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "outgoing",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "9018905",
        "hash": "63BCCAFA0D6D56B2F914B5933D7FABCD25925450F0675179E836D12DFA530C28",
        "timestamp": "2014-09-23T19:17:30.000Z",
        "fee": "0.000012",
        "source_balance_changes": [
          {
            "value": "-0.000012",
            "currency": "XRP",
            "issuer": ""
          },
          {
            "value": "-1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "source_tag": "",
        "source_amount": {
          "value": "0.00001",
          "currency": "XRP",
          "issuer": ""
        },
        "source_slippage": "0",
        "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
          "value": "0.01"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": true,
        "direction": "outgoing",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8924146",
        "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
        "timestamp": "2014-09-17T21:47:00.000Z",
        "fee": "0.00001",
        "source_balance_changes": [
          {
            "value": "-0.00002",
            "currency": "XRP",
            "issuer": ""
          }
        ],
        "destination_balance_changes": [
          {
            "value": "5.08e-8",
            "currency": "USD",
            "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc"
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "source_tag": "",
        "source_amount": {
          "value": "1",
          "currency": "XRP",
          "issuer": ""
        },
        "source_slippage": "0",
        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "destination_tag": "",
        "destination_amount": {
          "value": "1",
          "currency": "XRP",
          "issuer": ""
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "incoming",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8889845",
        "hash": "8496C20AEB453803CB80474B59AB1E8FAA26725561EFF5AF41BD588B325AFBA8",
        "timestamp": "2014-09-15T20:01:40.000Z",
        "fee": "0.000012",
        "source_balance_changes": [
          {
            "value": "-1.000012",
            "currency": "XRP",
            "issuer": ""
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "XRP",
            "issuer": ""
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "source_tag": "",
        "source_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "source_slippage": "0",
        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "incoming",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8889826",
        "hash": "4C9FA63D9F87AFC7E1BBD7F2644A1D4BD7537E833B1A945E27E5EC19F3B4B271",
        "timestamp": "2014-09-15T20:00:10.000Z",
        "fee": "0.000012",
        "source_balance_changes": [
          {
            "value": "-0.000012",
            "currency": "XRP",
            "issuer": ""
          },
          {
            "value": "-1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "source_tag": "",
        "source_amount": {
          "value": "30",
          "currency": "XRP",
          "issuer": ""
        },
        "source_slippage": "0",
        "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "destination_tag": "",
        "destination_amount": {
          "value": "30",
          "currency": "XRP",
          "issuer": ""
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "incoming",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8889256",
        "hash": "72549F0CB04C8C5F30F64256A4EBDE577B1943382AE44347F05FF70590FF7CCB",
        "timestamp": "2014-09-15T19:14:50.000Z",
        "fee": "0.000012",
        "source_balance_changes": [
          {
            "value": "-30.000012",
            "currency": "XRP",
            "issuer": ""
          }
        ],
        "destination_balance_changes": [
          {
            "value": "30",
            "currency": "XRP",
            "issuer": ""
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "source_tag": "",
        "source_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "source_slippage": "0",
        "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "outgoing",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8803725",
        "hash": "6A6E503211A32F7AB92FE747A8AD2759A1E597055CB8961F0B2FEDE3A53975AB",
        "timestamp": "2014-09-10T23:22:20.000Z",
        "fee": "0.000015",
        "source_balance_changes": [
          {
            "value": "-0.000015",
            "currency": "XRP",
            "issuer": ""
          },
          {
            "value": "-1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ]
      }
    },
    {
      "client_resource_id": "",
      "payment": {
        "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
        "source_tag": "",
        "source_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "source_slippage": "0",
        "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
        "destination_tag": "",
        "destination_amount": {
          "currency": "USD",
          "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
          "value": "1"
        },
        "invoice_id": "",
        "paths": "[]",
        "no_direct_ripple": false,
        "partial_payment": false,
        "direction": "outgoing",
        "state": "validated",
        "result": "tesSUCCESS",
        "ledger": "8711125",
        "hash": "82230B9D489370504B39BC2CE46216176CAC9E752E5C1774A8CBEC9FBB819208",
        "timestamp": "2014-09-05T19:59:50.000Z",
        "fee": "0.00001",
        "source_balance_changes": [
          {
            "value": "-0.00001",
            "currency": "XRP",
            "issuer": ""
          },
          {
            "value": "-1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ],
        "destination_balance_changes": [
          {
            "value": "1",
            "currency": "USD",
            "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"
          }
        ]
      }
    }
  ]
}

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.

TRUSTLINES

Get Trustlines

[Source]

Retrieves all trustlines associated with the Ripple address.

REST

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

Try it! >

The following URL parameters are required by this API endpoint:

Field	Value	Description
address	String	The Ripple account address whose trustlines to look up.

Optionally, you can also include the following query parameters:

Field	Value	Description
currency	String (ISO4217 currency code)	Filter results to include only trustlines for the given currency.
counterparty	String (Address)	Filter results to include only trustlines to the given account.
marker	String	Start position in response paging.
limit	String (Integer)	Max results per response. Will default to 10 if not set or set below 10.
ledger	String	Ledger to request paged results from. Use the ledger's hash.

Note: In order to use paging, you must provide ledger as a URL query parameter.

Response

The response is an object with a lines array, where each member is a trustline object.

{
  "success": true,
  "lines": [
    {
      "account": "rPs7nVbSops6xm4v77wpoPFf549cqjzUy9",
      "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
      "currency": "USD",
      "trust_limit": "100",
      "reciprocated_trust_limit": "0",
      "account_allows_rippling": false,
      "counterparty_allows_rippling": true
    },
    {
      "account": "rPs7nVbSops6xm4v77wpoPFf549cqjzUy9",
      "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs58B",
      "currency": "BTC",
      "trust_limit": "5",
      "reciprocated_trust_limit": "0",
      "account_allows_rippling": false,
      "counterparty_allows_rippling": true
    }
  ]
}

Grant Trustline

[Source]

Creates or modifies a trustline.

REST

POST /v1/accounts/{:address}/trustlines?validated=true
{
    "secret": "sneThnzgBgxc3zXPG....",
    "trustline": {
        "limit": "110",
        "currency": "USD",
        "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
        "account_allows_rippling": false
    }
}

Try it! >

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

Field	Value	Description
secret	String	A secret key for your Ripple account. This is either the master secret, or a regular secret, if your account has one configured.
trustline	Object (Trustline)	The trustline object to set. Ignores fields not controlled by this account. Any fields that are omitted are unchanged.

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

Field	Type	Description
validated	String	true or false. When set to true, will force the request to wait until the trustline transaction has been successfully validated by the server. A validated transaction will have the state attribute set to "validated" in the response.

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: Since a trustline occupies space in the ledger, a trustline increases the XRP the account must hold in reserve. You cannot create more trustlines if you do not have sufficient XRP to pay the reserve. This applies to the account extending trust, not to the account receiving it. A trustline with a limit and a balance of 0 is equivalent to no trust line.

Response

A successful response uses the 201 Created HTTP response code, and provides a JSON object that includes the trustline fields as saved, an identifying hash for the transaction that modified the trustline, and the sequence number of the ledger version that included the transaction.

{
  "success": true,
  "trustline": {
    "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "limit": "5",
    "currency": "USD",
    "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
    "account_allows_rippling": false,
    "account_froze_trustline": false,
    "state": "pending",
    "ledger": "9302926",
    "hash": "57695598CD32333F67A70DC6EBC3501D71569CE11C9803162CBA61990D89C1EE"
  }
}

NOTIFICATIONS

Notifications provide a mechanism to monitor for any kind of transactions that modify your Ripple account. Unlike the Get Payment History method, notifications include all types of transactions, but each is described in less detail.

Notifications are sorted in order of when they occurred, so you can save the most recently-known transaction and easily iterate forward to find any notifications that are newer than that.

Check Notifications

[Source]

Get a notification for the specific transaction hash, along with links to previous and next notifications, if available.

REST

GET /v1/accounts/{:address}/notifications/{:transaction_hash}

Try it! >

The following URL parameters are required by this API endpoint:

Field	Value	Description
address	String	The Ripple account address of an account involved in the transaction.
hash	String	A unique hash identifying the Ripple transaction that this notification describes

You can find a transaction hash in a few places:

• From the response when you submit a transaction (via Submit Payment, Update Account Settings, or Grant Trustline
• From objects in the payment history.
• From the previous_hash or next_hash fields of another Check Notifications response.

Response

A successful response contains a notification object, for example:

{
  "success": true,
  "notification": {
    "account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "type": "payment",
    "direction": "outgoing",
    "state": "validated",
    "result": "tesSUCCESS",
    "ledger": "8924146",
    "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
    "timestamp": "2014-09-17T21:47:00.000Z",
    "transaction_url": "http://api.ripple.com:5990/v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/payments/9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
    "previous_hash": "8496C20AEB453803CB80474B59AB1E8FAA26725561EFF5AF41BD588B325AFBA8",
    "previous_notification_url": "http://api.ripple.com:5990/v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/notifications/8496C20AEB453803CB80474B59AB1E8FAA26725561EFF5AF41BD588B325AFBA8",
    "next_hash": "AE79DE34230403EA2769B4DA21A0D4D2FD7A18518DBA0A4C5B6352AFD844D22A",
    "next_notification_url": "http://api.ripple.com:5990/v1/accounts/rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn/notifications/AE79DE34230403EA2769B4DA21A0D4D2FD7A18518DBA0A4C5B6352AFD844D22A"
  }
}

If the server has any notifications that are older than this one, the previous_hash field contains a hash you can use to call this method again to get the previous one. The previous_notification_url contains the same information, but already formatted into a URL you can perform a GET request on. If no older notifications are available, both fields are either omitted, or provided as an empty string.

The next_hash and next_notification_url fields work the same way, but they provide information on newer notifications instead.

Caution: If you are accessing the REST API through a proxy, you may not be able to access the URLs as provided. (See RA-129 for status and details.)

RIPPLED SERVER STATUS

The following two endpoints can be used to check if the ripple-rest API is currently connected to a rippled server, and to retrieve information about the current status of the API.

Check Connection

[Source]

Perform a simple ping to make sure that the server is working properly.

REST

GET /v1/server/connected

Try it! >

Response

{
  "success": true,
  "connected": true
}

If the server has any problems, for example with connecting to the rippled server, it returns an error message instead.

Get Server Status

[Source]

Retrieve information about the current status of the Ripple-REST API and the rippled server it is connected to.

REST

GET /v1/server

Try it! >

Response

{
  "success": true,
  "api_documentation_url": "https://github.com/ripple/ripple-rest",
  "rippled_server_url": "wss://s1.ripple.com:443",
  "rippled_server_status": {
    "build_version": "0.26.3-sp2",
    "complete_ledgers": "32570-9306249",
    "hostid": "MERT",
    "io_latency_ms": 1,
    "last_close": {
      "converge_time_s": 3.021,
      "proposers": 5
    },
    "load_factor": 1,
    "peers": 49,
    "pubkey_node": "n9LpPSgwfihQDRX68dykxtNCm4gi2dBEJCga7uwV7uztoRSswms8",
    "server_state": "full",
    "validated_ledger": {
      "age": 9,
      "base_fee_xrp": 0.00001,
      "hash": "7C3F4489091BAE5DCADE3B1A8A2C1E7E5C938FA4483660FD1A4098C4EC4805CD",
      "reserve_base_xrp": 20,
      "reserve_inc_xrp": 5,
      "seq": 9306249
    },
    "validation_quorum": 3
  }
}

The parameters in a successful response are as follows:

Field	Value	Description
api_documentation_url	String	A URL that contains more information about the software, typically the Ripple-REST Github Project.
rippled_server_url	String	The URL of the rippled server that Ripple-REST is using to interface with the Ripple Network
rippled_server_status	Object	Various information about the rippled server

The rippled_server_status object may have any of the following fields:

Field	Value	Description
build_version	String	The rippled software version number
complete_ledgers	String	A range (possibly a disjointed range) of ledger versions that the server has on hand
hostid	String	The hostname of the machine running the rippled server
io_latency_ms	Number	The number of milliseconds spent waiting for I/O operations to complete. A high number indicates too much load on the server, which can be improved with more RAM and faster hard disks.
last_close	Object	Some information about the most recently-closed ledger
last_close.converge_time_s	Number	How many seconds it took to reach consensus on the this ledger version
last_close.proposers	Number	How many trusted validators were involved in the consensus process for this ledger version
load_factor	Number	The load factor the server is currently enforcing, which affects transaction fees. The load factor is determined by the highest of the individual server’s load factor, cluster’s load factor, and the overall network’s load factor.
peers	Number	How many other rippled servers this server is connected to
pubkey_node	String	Public key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can just create a new pair of keys.)
server_state	String	A string indicating to what extent the server is participating in the network. See Possible Server States in the rippled documentation for more details.
validated_ledger	Object	Information about the fully-validated ledger with the highest sequence number (the most recent)
validated_ledger.age	Unsigned Integer	The time since the ledger was closed, in seconds
validated_ledger.base_fee_xrp	Number	Base fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005
validated_ledger.hash	String	Unique hash for the ledger, as hex
validated_ledger.reserve_base_xrp	Unsigned Integer	Minimum amount of XRP (not drops) necessary for every account to keep in reserve
validated_ledger.reserve_inc_xrp	Unsigned Integer	Amount of XRP (not drops) added to the account reserve for each object an account is responsible for in the ledger
validated_ledger.seq	Unsigned Integer	Identifying sequence number of this ledger version
validation_quorum	Number	Minimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations.

UTILITIES

Retrieve Ripple Transaction

[Source]

Returns a Ripple transaction, in its complete, original format.

REST

GET /v1/transactions/{:transaction_hash}

Try it! >

The following URL parameters are required by this API endpoint:

Field	Value	Description
hash	String	A unique hash identifying the Ripple transaction to retrieve

Response

The result is a JSON object, whose transaction field has the requested transaction. See the Transaction format documentation for a complete explanation of the fields of a transaction.

{
  "success": true,
  "transaction": {
    "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
    "Amount": {
      "currency": "USD",
      "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
      "value": "0.01"
    },
    "Destination": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
    "Fee": "10",
    "Flags": 131072,
    "SendMax": "10",
    "Sequence": 11,
    "SigningPubKey": "03AB40A0490F9B7ED8DF29D246BF2D6269820A0EE7742ACDD457BEA7C7D0931EDB",
    "TransactionType": "Payment",
    "TxnSignature": "304402206B62F24BA371DF6E8F2F5A4D0C006F4081494B8ED49F9B2C453FF50B58AB170702200886487FFD272799E5C88547692AD7DD48B04E10070F7A1F36D7AF73CCFB708D",
    "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E",
    "inLedger": 8924146,
    "ledger_index": 8924146,
    "meta": {
      "AffectedNodes": [
        {
          "ModifiedNode": {
            "FinalFields": {
              "Account": "rUrgXPxenRbjnFDXKWUhH8mBJcQ2CyPfkG",
              "Balance": "20357167562",
              "Flags": 0,
              "OwnerCount": 44,
              "Sequence": 709
            },
            "LedgerEntryType": "AccountRoot",
            "LedgerIndex": "0193CB8318BDB270B775835373E8789F5357CEF712DF3275F92A8CEE97E352FE",
            "PreviousFields": {
              "Balance": "20357167552"
            },
            "PreviousTxnID": "41F8D5612778AC1318599217E53198940EF16063A3F4B73DECE33EA0901FA96A",
            "PreviousTxnLgrSeq": 8924070
          }
        },
        {
          "ModifiedNode": {
            "FinalFields": {
              "Account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn",
              "Balance": "230999889",
              "Domain": "6D64756F31332E636F6D",
              "Flags": 0,
              "MessageKey": "0000000000000000000000070000000300",
              "OwnerCount": 0,
              "Sequence": 12
            },
            "LedgerEntryType": "AccountRoot",
            "LedgerIndex": "13F1A95D7AAB7108D5CE7EEAF504B2894B8C674E6D68499076441C4837282BF8",
            "PreviousFields": {
              "Balance": "230999909",
              "Sequence": 11
            },
            "PreviousTxnID": "8496C20AEB453803CB80474B59AB1E8FAA26725561EFF5AF41BD588B325AFBA8",
            "PreviousTxnLgrSeq": 8889845
          }
        },
        {
          "ModifiedNode": {
            "FinalFields": {
              "Balance": {
                "currency": "USD",
                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
                "value": "-19.84529319487081"
              },
              "Flags": 2228224,
              "HighLimit": {
                "currency": "USD",
                "issuer": "rUrgXPxenRbjnFDXKWUhH8mBJcQ2CyPfkG",
                "value": "0"
              },
              "HighNode": "0000000000000002",
              "LowLimit": {
                "currency": "USD",
                "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
                "value": "0"
              },
              "LowNode": "0000000000000010"
            },
            "LedgerEntryType": "RippleState",
            "LedgerIndex": "2E103526973EF8CCE3340125DD66D6BF84DD8473EF693EC5E06B2ACBF2BAC155",
            "PreviousFields": {
              "Balance": {
                "currency": "USD",
                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
                "value": "-19.84529324567081"
              }
            },
            "PreviousTxnID": "41F8D5612778AC1318599217E53198940EF16063A3F4B73DECE33EA0901FA96A",
            "PreviousTxnLgrSeq": 8924070
          }
        },
        {
          "ModifiedNode": {
            "FinalFields": {
              "Account": "rUrgXPxenRbjnFDXKWUhH8mBJcQ2CyPfkG",
              "BookDirectory": "3A574D1E645D05EA27A5D011AECF6C78FFB028AA9B584C245D06FE5809E78102",
              "BookNode": "0000000000000000",
              "Flags": 0,
              "OwnerNode": "0000000000000003",
              "Sequence": 696,
              "TakerGets": {
                "currency": "USD",
                "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
                "value": "15.2299999492"
              },
              "TakerPays": "2998031486"
            },
            "LedgerEntryType": "Offer",
            "LedgerIndex": "350327BB97B7707F4E7B8670C42F886E29B9C9615D4A8D93FC730DD17770D9B4",
            "PreviousFields": {
              "TakerGets": {
                "currency": "USD",
                "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
                "value": "15.23"
              },
              "TakerPays": "2998031496"
            },
            "PreviousTxnID": "41F8D5612778AC1318599217E53198940EF16063A3F4B73DECE33EA0901FA96A",
            "PreviousTxnLgrSeq": 8924070
          }
        },
        {
          "ModifiedNode": {
            "FinalFields": {
              "Balance": {
                "currency": "USD",
                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
                "value": "-0.0100000508"
              },
              "Flags": 131072,
              "HighLimit": {
                "currency": "USD",
                "issuer": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX",
                "value": "100"
              },
              "HighNode": "0000000000000000",
              "LowLimit": {
                "currency": "USD",
                "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
                "value": "0"
              },
              "LowNode": "000000000000000B"
            },
            "LedgerEntryType": "RippleState",
            "LedgerIndex": "E3DC31319B6C121387EAE05253AF71CAF98360BF1419249DD1A218A9B4C121A9",
            "PreviousFields": {
              "Balance": {
                "currency": "USD",
                "issuer": "rrrrrrrrrrrrrrrrrrrrBZbvji",
                "value": "-0.01"
              }
            },
            "PreviousTxnID": "41F8D5612778AC1318599217E53198940EF16063A3F4B73DECE33EA0901FA96A",
            "PreviousTxnLgrSeq": 8924070
          }
        }
      ],
      "DeliveredAmount": {
        "currency": "USD",
        "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc",
        "value": "0.00000005080000000000001"
      },
      "TransactionIndex": 5,
      "TransactionResult": "tesSUCCESS"
    },
    "validated": true,
    "date": 464305620
  }
}

Retrieve Transaction Fee

(New in Ripple-REST v1.3.1)

Retrieve the current transaction fee for the rippled server ripple-rest is connected to. If ripple-rest is connected to multiple rippled servers, the median fee between the connected servers is calculated.

REST

GET /v1/transaction-fee

Try it! >

Response

{
  "success": true,
  "fee": "12000"
}

Create Client Resource ID

Generate a universally-unique identifier suitable for use as the Client Resource ID for a payment.

REST

GET /v1/uuid

Try it! >

Response

{
  "success": true,
  "uuid": "a5a8fe40-3795-4b10-b2b6-f05f3ca31db9"
}