xrpl-dev-portal/ripplerest_api.md

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.

Installation instructions and source code can be found in the Ripple-REST repository.

Available API Routes

Accounts

• Generate Account - GET /v1/accounts/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/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/tx
• 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.

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

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

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

• 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.
• 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.)
• If more complicated information needs to be sent, it will be included as JSON-formatted data within the body of the HTTP POST request.
• 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. (Note: Old versions of Ripple-REST return 200 OK regardless of the outcome.)

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

• Codes in the 200-299 range indicate success. (Note: Old versions of Ripple-REST return 200 OK even in some failure cases.)
• 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:
  • 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	Value	Description
success	Boolean	false indicates that an error occurred.
error_type	String	A short string identifying the error that occurred.
message	String	A longer human-readable string explaining what went wrong.

Formatting Conventions

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	Value	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, you can 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	Value	Description
source_address	String	The Ripple address of the account sending the payment
destination_address	String	The Ripple address of the account receiving the payment
destination_amount	Amount Object	The amount of currency that should be deposited into the account receiving the payment.
source_tag	Unsigned Integer	(Optional) A 32-bit unsigned integer (0-4294967294, inclusive) that is generally used if the sender is a hosted wallet at a gateway. This should be the same as the destination_tag used to identify the hosted wallet when they are receiving a payment.
destination_tag	Unsigned Integer	(Optional) A 32-bit unsigned integer (0-4294967294, inclusive) that is generally used if the recipient of the payment is a hosted wallet at a gateway.
source_slippage	String (Quoted decimal number)	can be specified to give the source_amount a cushion and 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) 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.
flag_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.
flag_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

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.

Payments

Prepare Payment

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

Try it! >

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: consider it like getting quotes before actually making the payment.

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.

The following URL parameters are required by this API endpoint:

Field	Value	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	Value	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.

This method effectively performs a ripple_path_find and constructs a payment object for the paths it finds.

Response Body:

{
  "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/payments endpoint for processing.

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

Submitting a Payment

POST /v1/payments

Before you can submit a payment, you will need to have three pieces of information:

• The Payment [required] object to be submitted.

• The secret [required] or private key for your Ripple account.

DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER -- this is the key to your account and your money. If you are using the test server provided, only use test accounts to submit payments.

• A client_resource_id [required] that will uniquely identify this payment. This is a 36-character UUID (universally unique identifier) value which will uniquely identify this payment within the ripple-rest API. This value can be any unique string such as "123" or "ABC123". Note that you can use the GET /v1/uuid endpoint to calculate a UUID value if you do not have a UUID generator readily available.

This HTTP POST request must have a content-type of application/json, and the body of the request should look like this:

{
  "secret": "s...",
  "client_resource_id": "123",
  "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! >

Upon completion, the server will return a JSON object which looks like the following:

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

The status_url value is a URL that can be queried to get the current status for this payment. This will be a reference to the GET /v1/accounts/{:address}/payments endpoint, with the client resource ID filled in to retrieve the details of the payment. More information on this endpoint can be found in the section on confirming a payment.

If an error occurred that prevented the payment from being submitted, the response object will look like this:

{
  "success": false,
  "error": "tecPATH_DRY",
  "message": "Path could not send partial amount. Please ensure that the src_address has sufficient funds (in the src_amount currency, if specified) to execute this transaction."
}

More information about transaction errors can be found on the Ripple Wiki.

Note that payments cannot be cancelled once they have been submitted.

Confirming a Payment

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

The {:id} value can be either a client resource identifier or a transaction hash value.

Try it! >

To confirm that your payment has been submitted successfully, you can call this API endpoint. The hash value can either be the transaction hash for the desired payment, or the payment's client resource ID.

The server will return the details of your payment:

{
  "success": true,
  "payment": {
    "source_account": "rPs7nVbSops6xm4v77wpoPFf549cqjzUy9",
    "source_tag": "",
    "source_amount": {
    "value": "1",
    "currency": "XRP",
    "issuer": ""
  },
  "source_slippage": "0",
  "destination_account" "rKB4oSXwPkRpb2sZRhgGyRfaEhhYS6tf4M",
  "destination_tag": "",
  "destination_amount": {
    "value": "1",
    "currency": "XRP",
    "issuer": ""
  },
  "invoice_id": "",
  "paths": "[]",
  "no_direct_ripple": false,
  "partial_payment": false,
  "direction": "outgoing",
  "state": "validated",
  "result": "tesSUCCESS",
  "ledger": "6141074",
  "hash": "85C5E6762DE7969DC1BD69B3C8C7387A5B8FCE6A416AA1F74C0ED5D10F08EADD",
  "timestamp": "2014-04-18T01:21:00.000Z",
  "fee": "0.000012",
  "source_balance_changes":
  [
    {
      "value": "-1.000012",
      "currency": "XRP",
      "issuer": ""
    }
  ],
  "destination_balance_changes":
  [
    {
      "value": "1",
      "currency": "XRP",
      "issuer": ""
    }
  ]
}

You can then check the state field to see if the payment has gone through; it will have the value "validated" when the payment has been validated and written to the Ripple ledger.

If the payment cannot be found, then an error will be returned instead:

{
  "success": true,
  "error": "Payment Not Found",
  "message": "This may indicate that the payment was never validated and written into the Ripple ledger and it was not submitted through this ripple-rest instance. This error may also be seen if the databases of either ripple-rest or rippled were recently created or deleted."
}

Note that there can be a delay in processing a submitted payment; if the payment does not exist yet, or has not been validated, you should wait for a short period of time before checking again.

Receiving Payments

As well as sending payments, your application will need to know when incoming payments have been received. To do this, you first make the following API call:

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

Try it! >

This will return the most recent payments (both incoming and outgoing will be denoted in the direction)

{
  "success": true,
  "payments": [
    { /* payment */ }.
    { /* payment */ }.
    { /* payment */ }.
    { /* payment */ }.
    { /* payment */ }
  ]
}

GET /v1/accounts/{:address}/payments?direction=incoming

This will return the most recent incoming payments for your account, up to a maximum of 20. You can process these historical payments if you want, and also retrieve more historical payments if you need to by using the page parameter, as described in the Payment History section below.

Regardless of what else you do with these payments, you need to extract the value of the ledger field from the most recent (ie, first) payment in the returned list. Convert this number to an integer and increment it by one. The resulting value, which will we call the next_ledger value, is the starting point for polling for new payments.

Your application should then periodically make the following API call:

GET /v1/accounts/{:address}/payments?direction=incoming&earliest_first=true&start_ledger={next_ledger}

This will return any new payments which have been received, up to a maximum of 20. You should process these incoming payments. If you received a list of 20 payments, there may be more payments to be processed. You should then use the page parameter to get the next chunk of 20 payments, like this:

GET /v1/accounts/{:address}/payments?direction=incoming&earliest_first=true&start_ledger={next_ledger}&page=2

Continue retrieving the payments, incrementing the page parameter each time, until there are no new incoming payments to be processed.

Note: We use the earliest_first parameter to retrieve the payments in ascending date order (ie, the oldest payment first). This ensures that if any more payments come in after the first API call with start_ledger set to next_ledger, you won't miss any payments. If you use the page parameter while retrieving the payments in descending order (ie, the most recent payment first), you may miss one or more payments while scanning through the pages.

Once you have retrieved all the payments, you should update your next_ledger value by once again taking the value of the ledger field from the most recent (ie, last) payment received, converting this value to an integer and incrementing it by one. This will give you the next_ledger value to use the next time you poll for payments.

Using this approach, you can regularly poll for new incoming payments, confident that no payments will be processed twice, and no incoming payments will be missed.

Payment History

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

Try it! >

This API endpoint can be used to browse through an account's payment history and also used to confirm specific payments after a payment has been submitted. The following query string parameters can be used to filter the list of returned payments:

• source_account Filter the results to only include payments sent by the given account.

• destination_account Filter the results to only include payments received by the given account.

• exclude_failed If set to true, the results will only include payments which were successfully validated and written into the ledger. Otherwise, failed payments will be included.

• direction Limit the results to only include the given type of payments. The following direction values are currently supported:

• incoming

• outgoing

• pending

• earliest_first If set to true, the payments will be returned in ascending date order. Otherwise, the payments will be returned in descending date order (ie, the most recent payment will be returned first). Defaults to false.

• start_ledger The index for the starting ledger. If earliest_first is true, this will be the oldest ledger to be queried; otherwise, it will be the most recent ledger. Defaults to the first ledger in the rippled server's database.

• end_ledger The index for the ending ledger. If earliest_first is true, this will be the most recent ledger to be queried; otherwise, it will be the oldest ledger. Defaults to the most recent ledger in the rippled server's database.

• results_per_page The maximum number of payments to be returned at once. Defaults to 20.

• page The page number to be returned. The first page of results will have page number 1, the second page will have page number 2, and so on. Defaults to 1.

Upon completion, the server will return a JSON object which looks like the following:

{
  "success": true,
  "payments": [
    {
      "client_resource_id": "3492375b-d4d0-42db-9a80-a6a82925ccd5",
      "payment": {
        /* Payment */
      }
    }, {
      "client_resource_id": "4a4e3fa5-d81e-4786-8383-7164c3cc9b01",
      "payment": {
        /* Payment */
      }
    }
  ]
}

If the server returns fewer than results_per_page payments, then there are no more pages of results to be returned. Otherwise, increment the page number and re-issue the query to get the next page of results.

Note that the ripple-rest API has to retrieve the full list of payments from the server and then filter them before returning them back to the caller. This means that there is no speed advantage to specifying more filter values.

ACCOUNTS

ripple-rest provides the ability to review and confirm on information regarding your Ripple account. You can view your current balances and settings, as well as the ability to set your account setting flags.

Generating Accounts

(New in Ripple-REST v1.3.0)

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!

GET /v1/accounts/new

Try it! >

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.

Account Balances

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

Try it! >

Retrieve the current balances for the given Ripple account.

The account parameter should be set to the Ripple address of the desired account. The server will return a JSON object which looks like the following:

{
  "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.

Account Settings

You can retrieve an account's settings by using the following endpoint:

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

Try it! >

The server will return a list of the current settings in force for the given account, in the form of a JSON object:

{
  "success": true,
  "settings": {
    "transfer_rate": 100,
    "password_spent": false,
    "require_destination_tag": false,
    "require_authorization": false,
    "disallow_xrp": false,
    "disable_master": false,
    "transaction_sequence": 22
  }
}

The following account settings are currently supported:

• PasswordSpent true if the password has been "spent", else false.

• RequireDestTag If this is set to true, incoming payments will only be validated if they include a destination_tag value. Note that this is used primarily by gateways that operate exclusively with hosted wallets.

• RequireAuth If this is set to true, incoming trustlines will only be validated if this account first creates a trustline to the counterparty with the authorized flag set to true. This may be used by gateways to prevent accounts unknown to them from holding currencies they issue.

• DisallowXRP If this is set to true, payments in XRP will not be allowed.

• EmailHash The MD5 128-bit hash of the account owner's email address, if known.

• MessageKey An optional public key, represented as a hex string, that can be used to allow others to send encrypted messages to the account owner.

• Domain The domain name associated with this account.

• TransferRate The rate charged each time a holder of currency issued by this account transfers some funds. The default rate is "1.0"; a rate of "1.01"` is a 1% charge on top of the amount being transferred. Up to nine decimal places are supported.

Updating Account Settings

To change an account's settings, make an HTTP POST request to the above endpoint. The request must have a content-type of application/json, and the body of the request should look like this:

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

{
  "secret": "s...",
  "settings": {
    "transfer_rate": 100,
    "password_spent": false,
    "require_destination_tag": false,
    "require_authorization": false,
    "disallow_xrp": false,
    "disable_master": false,
    "transaction_sequence": 22
  }
}

Try it! >

The given settings will be updated.

TRUSTLINES

Reviewing Trustlines

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

Try it! >

Retrieves all trustlines associated with the Ripple address. Upon completion, the server will return a JSON object which represents each trustline individually along with the currency, limit, and counterparty.

The following query string parameters are supported to provide additional filtering for either trustlines to a particular currency or trustlines from a specific counterparty:

• currency Three letter currency denominations (i.e. USD, BTC).
• counterparty Ripple address of the counterparty trusted.

GET /v1/accounts/{:address}/trustlines?currency=USD&counterparty=rPs723Dsd...

The object returned looks like this:

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

Granting a Trustline

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

A trustline can also updated and simply set with a currency,amount,counterparty combination by submitting to this endpoint with the following JSON object.

{
  "secret": "sneThnzgBgxc3zXPG....",
  "trustline": {
  "limit": "110",
  "currency": "USD",
  "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
  "allows_rippling": false
  }
}

Try it! >

A successful submission will result in a returning JSON object that includes a transaction hash to the trustline transaction.

{
  "success": true,
  "line": {
    "account": "rPs7nVbSops6xm4v77wpoPGf549cqjzUy9",
    "counterparty": "rKB4oSXwPkRpb2sZRhgGyRfaEhhYS6tf4M",
    "currency": "USD",
    "trust_limit": "100",
    "allows_rippling": true
  },
  "ledger": "6146255",
  "hash": "6434F18B3997D81152F1AB31911E8D40E1346A05478419B7B3DF78B270C1151A"
}

NOTIFICATIONS

Notifications can be used as a looping mechanism to monitor any transactions against your Ripple address or to confirm against missed notifications if your connection to rippled goes down. Notifications are generic and span across all types of Ripple transactions which is different than the "Payments" endpoints which specifically retrieve payment transactions. The "Payments" endpoints also provide full payment objects versus the notification objects which described the transaction at a higher level with less detail.

Checking Notifications

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

Try it! >

This endpoint will grab the notification based on the specific transaction hash specified. Once called the notification object retreived will provide information on the type of transaction and also the previous and next notifications will be shown as well. The previous_notification_url and next_notification_url can be used to walk up and down the notification queue. Once the next_notification_url is empty that means you have the most current notification, this applies for the previous_notification_url similarly when it's empty as it means you are holding the earliest notification available on the rippled you are connecting to.

A successful retrieval will look like this:

{
  "success": true,
  "notification": {
    "account": "rPs7nVbSops6xm4v77wpoPFf549cqjzUy9",
    "type": "payment",
    "direction": "outgoing",
    "state": "validated",
    "result": "tesSUCCESS",
    "ledger": "5704389",
    "hash": "EA1C8349FFFDB180BF6805FB69B32A41A5C86E27B4F79BED3CD8BA9A1E902721",
    "timestamp": "+046228-05-27T00:20:00.000Z",
    "transaction_url": "/v1/accounts/rPs7nVbSops6xm4v77wpoPFf549cqjzUy9/payments/EA1C8349FFFDB180BF6805FB69B32A41A5C86E27B4F79BED3CD8BA9A1E902721",
    "previous_hash": "1578758880412050B6C9C367DAE090B5452649549F00780276BED51BDEECF63C",
    "previous_notification_url": "/v1/accounts/rPs7nVbSops6xm4v77wpoPFf549cqjzUy9/notifications/1578758880412050B6C9C367DAE090B5452649549F00780276BED51BDEECF63C",
    "next_hash": "441E8AEC90A3674318710B4978E9598BD47190CF51E44CBD11C28FFF75FBC934",
    "next_notification_url": "/v1/accounts/rPs7nVbSops6xm4v77wpoPFf549cqjzUy9/notifications/441E8AEC90A3674318710B4978E9598BD47190CF51E44CBD11C28FFF75FBC934"
  }
}

The notification of the most recent transaction will show next_notification_url as an empty string.

The earliest notification available on the rippled server will show previous_notification_url as an empty string.

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 State

GET /v1/server/connected

Try it! >

Checks to see if the ripple-rest API is currently connected to a rippled server, and is ready to be used. This provides a quick and easy way to check to see if the API is up and running, before attempting to process transactions.

No additional parameters are required. Upon completion, the server will return true if the API is connected, and false otherwise.

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

Get Server Status

GET /v1/server

Try it! >

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

This endpoint takes no parameters, and returns a JSON object with information on the current status of the API:

{
  "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-sp1",
    "complete_ledgers": "32570-8926343",
    "hostid": "LIED",
    "io_latency_ms": 1,
    "last_close": {
      "converge_time_s": 3.068,
      "proposers": 5
    },
    "load_factor": 1,
    "peers": 52,
    "pubkey_node": "n9LpxYuMx4Epz4Wz8Kg2kH3eBTx1mUtHnYwtCdLoj3HC85L2pvBm",
    "server_state": "full",
    "validated_ledger": {
      "age": 10,
      "base_fee_xrp": 0.00001,
      "hash": "5A24FC580674F444BAA72B897C906FF1E167227869BF3D2971C2D87272B038EF",
      "reserve_base_xrp": 20,
      "reserve_inc_xrp": 5,
      "seq": 8926343
    },
    "validation_quorum": 3
  }
}

If the server is not currently connected to the Ripple network, the following error will be returned:

{
  "success": false,
  "error": "rippled Disconnected",
  "message": "ripple-rest is unable to connect to the specified rippled server, or the rippled server is unable to communicate with the rest of the Ripple Network. Please check your internet and rippled server settings and try again"
}

UTILITIES

Retrieve Ripple Transaction

While the ripple-rest API is a high-level API built on top of the rippled server, there are times when you may need to access an underlying Ripple transaction rather than dealing with the ripple-rest data format. When you need to do this, you can retrieve a standard Ripple formatted transaction by using the following endpoint:

GET /v1/tx/{:transaction_hash}

Try it! >

This retrieves the underlying Ripple transaction with the given transaction hash value. Upon completion, the server will return following JSON object:

{
  "success": true,
  "tx": { /* Ripple Transaction */ }
}

Please refer to the Transaction Format page in the Ripple Wiki for more information about Ripple transactions.

If the given transaction could not be found in the rippled server's historical database, the following error will be returned:

{
  "success": false,
  "error": "txnNotFound",
  "message": "Transaction not found."
}

Create Client Resource ID

GET /v1/uuid

Try it! >

This endpoint creates a universally unique identifier (UUID) value which can be used to calculate a client resource ID for a payment. This can be useful if the application does not have a UUID generator handy.

This API endpoint takes no parameters, and returns a JSON object which looks like the following:

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