Skip to content

Latest commit

 

History

History
512 lines (380 loc) · 24.6 KB

API.md

File metadata and controls

512 lines (380 loc) · 24.6 KB

#INTRODUCTION

Ripple-REST API (BETA)

ripple-rest API is currently in BETA and subject to multiple changes and iterations as it is being finalized. Please double check with the ripple-rest github repo for the most up-to-date versions and documentation. Feel free to poke around the branches to see what we're working on changing as well.

The ripple-rest API makes it easy to access the Ripple system via a RESTful web interface. In this section, we will cover the concepts you need to understand, and get you started accessing the API and learning how to use it.

While there are different APIs that you can use, for example by accessing the rippled server directly via a web socket, this documentation focuses on the ripple-rest API as this is the high-level API recommended for working with the Ripple system.

A test version of the ripple-rest server is up and running at:

https://ripple-rest.herokuapp.com

Available API Routes

Ripple Concepts

Ripple Address

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 create the payment object. 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.

  3. Finally, you can check to see if your payment has gone through by looking for the appropriate notification.

You can also use notifications to see when a payment has been received.

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 - Payment transactions is an authorized transfer of balance from one address to another.
  • Trustline - Trustline transactions is an authorized grant of trust between two addresses.

##Getting Started

Setup

Before you can use the ripple-rest API, you will need to have two things:

  • An activated Ripple account. If you don't have a Ripple account, you can use the Ripple web client to create one, as described in the Client Manual. Make sure you have a copy of the Ripple address for your account; the address can be found by clicking on the Receive tab in the web client.

  • The URL of the server running the ripple-rest API that you wish to use. In this documentation, we will assume that the server is running at https://ripple-rest.herokuapp.com, which is the URL for a test version of the server. When you follow the examples below, make sure that you replace this with the URL for the server you want to access. Please remember to only use

As a programmer, you will also need to have a suitable HTTP client library that allows you to make secure HTTP (HTTPS) requests. To follow the examples below, you will need to have access to the curl command-line tool.

Exploring the API

Let's start by using curl to see if the ripple-rest API is currently running. Type the following into a terminal window:

curl https://ripple-rest.herokuapp.com/api/v1/status

After a short delay, the following response should be displayed:

{
       "api_server_status": "online",
       "rippled_server_url": "wss://s_west.ripple.com:443",
       "rippled_server_status": {
         "info": {
           "build_version": "0.21.0-rc2",
           "complete_ledgers": "32570-5254146",
           "hostid": "WEAN",
           "last_close": {
             "converge_time_s": 2.022,
             "proposers": 5
           },
           "load_factor": 1,
           "peers": 52,
           "pubkey_node": "n9LVyJ9GGBwHeeZ1bwPQUKj5P6vyD5tox2ozMPadMDvXx8CrPPmJ",
           "server_state": "full",
           "validated_ledger": {
             "age": 6,
             "base_fee_xrp": 1.0e-5,
             "hash": "ADF8BEFA91F4D355C60AE37E7ED79E91591704D052114F2BBDB6AF892E5E749E",
             "reserve_base_xrp": 20,
             "reserve_inc_xrp": 5,
             "seq": 5254146
           },
           "validation_quorum": 3
         }
       },
       "api_documentation_url": "https://github.com/ripple/ripple-rest"
     }

Using the API

The ripple-rest API conforms to the following general behavior for a web interface:

  • 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, including the desired resources within the URL itself.

  • 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 completion, the server will return 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.

  • The returned JSON object will include a success field indicating whether the request was successful or not.

Errors

Errors can be represented by general HTTP response codes. Errors specific to ripple-rest will return a 200 status but will include error and message fields, where error is a short string identifying the error that occurred, and message will be a longer human-readable string explaining what went wrong.

API Objects

1. Amount

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.

Note that the value can either be specified as a string or a number. Internally this API uses a BigNumber library to retain higher precision if numbers are inputted as strings.

Amount Object:

{
  "value": "1.0",
  "currency": "USD",
  "issuer": "r..."
}

Or for XRP:

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

2. Payment

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.

The following fields are the minimum required to submit a Payment:

  • src_address is the Ripple address for the source account, as a string.

  • dst_address is the Ripple address for the destination account, as a string.

  • dst_amount is an Amount object representing the amount that should be deposited into the destination account.

{
  "src_address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
  "dst_address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
  "dst_amount": {
    "value": "0.001",
    "currency": "XRP",
    "issuer": ""
  }
}

The full set of fields accepted on Payment submission is as follows:

  • src_tag is an optional unsigned 32 bit 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 dst_tag used to identify the hosted wallet when they are receiving a payment.
  • dst_tag is an optional unsigned 32 bit integer (0-4294967294, inclusive) that is generally used if the receiver is a hosted wallet at a gateway
  • src_slippage can be specified to give the src_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 src_address will never be charged more than src_slippage + the value specified in src_amount
  • invoice_id is an optional 256-bit hash field that can be used to link payments to an invoice or bill
  • paths is a "stringified" version of the Ripple PathSet structure. Most users of this API will want to treat this field as opaque. See the Ripple Wiki for more information about Ripple pathfinding
  • flag_no_direct_ripple is a boolean that can be set to true if paths are specified and the sender would like the Ripple Network to disregard any direct paths from the src_address to the dst_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 is a boolean that, if set to true, indicates that this payment should go through even if the whole amount cannot be sent because of a lack of liquidity or funds in the src_address account. The vast majority of senders will never need to use this option.
{
    /* User Specified */

    "src_address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
    "src_tag": "",
    "src_amount": {
        "value": "0.001",
        "currency": "XRP",
        "issuer": ""
    },
    "src_slippage": "0",
    "dst_address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
    "dst_tag": "",
    "dst_amount": {
        "value": "0.001",
        "currency": "XRP",
        "issuer": ""
    },

    /* Advanced Options */

    "invoice_id": "",
    "paths": "[]",
    "flag_no_direct_ripple": false,
    "flag_partial_payment": false
}

When a payment is confirmed in the Ripple ledger, it will have additional fields added:

  • tx_result will be tesSUCCESS if the transaction was successfully processed. If it was unsuccessful but a transaction fee was claimed the code will start with tec. More information about transaction errors can be found on the Ripple Wiki.
  • tx_timestamp is the UNIX timestamp for when the transaction was validated
  • tx_fee is the network transaction fee charged for processing the transaction. For more information on fees, see the Ripple Wiki. In the standard Ripple transaction format fees are expressed in drops, or millionths of an XRP, but for clarity the new formats introduced by this API always use the full XRP unit.
  • tx_src_bals_dec is an array of Amount objects representing all of the balance changes of the src_address caused by the payment. Note that this includes the tx_fee
  • tx_dst_bals_inc is an array of Amount objects representing all of the balance changes of the dst_address caused by the payment
{
    /* ... */

    /* Generated After Validation */

    "tx_direction": "outgoing",
    "tx_state": "confirmed",
    "tx_result": "tesSUCCESS",
    "tx_ledger": 4696959,
    "tx_hash": "55BA3440B1AAFFB64E51F497EFDF2022C90EDB171BBD979F04685904E38A89B7",
    "tx_timestamp": 1391025100000,
    "tx_timestamp_human": "2014-01-29T19:51:40.000Z",
    "tx_fee": "0.000012",
    "tx_src_bals_dec": [{
        "value": "-0.001012",
        "currency": "XRP",
        "issuer": ""
    }],
    "tx_dst_bals_inc": [{
        "value": "0.001",
        "currency": "XRP",
        "issuer": ""
    }]
}

3. Notification

Notifications are new type of object not used elsewhere on the Ripple Network but intended to simplify the process of monitoring accounts for new activity.

If there is a new Notification for an account it will contain information about the type of transaction that affected the account, as well as a link to the full details of the transaction and a link to get the next notification.

If there is a new notification for an account, it will come in this format:

  • timestamp is the UNIX timestamp for when the transaction was validated, or the number of milliseconds since January 1st, 1970 (00:00 UTC)
  • timestamp_human is the transaction validation time represented in the format YYYY-MM-DDTHH:mm:ss.sssZ. The timezone is always UTC as denoted by the suffix "Z"
  • transaction_url is a URL that can be queried to retrieve the full details of the transaction. If it the transaction is a payment it will be returned in the Payment object format, otherwise it will be returned in the standard Ripple transaction format
  • next_notification_url is a URL that can be queried to get the notification following this one for the given address
  • source_transaction_id will be the same as the source_transaction_id originally submitted by the sender. Senders should look for the source_transaction_id's of payments they have submitted to ripple-rest amongst Notifications of validated payments. If the source_transaction_id of a particular payment appears in a Notification with the state listed as validated, then that payment has been successfully written into the Ripple Ledger
{
  "address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
  "type": "payment",
  "tx_direction": "outgoing",
  "tx_state": "confirmed",
  "tx_result": "tesSUCCESS",
  "tx_ledger": 4696959,
  "tx_hash": "55BA3440B1AAFFB64E51F497EFDF2022C90EDB171BBD979F04685904E38A89B7",
  "tx_timestamp": 1391025100000,
  "tx_timestamp_human": "2014-01-29T19:51:40.000Z",
 "tx_url":"http://api/v1/addresses/r../payments/55B..",
 "next_notification_url":"http://api/v1/addresses/r../next_notification/5.."
  "confirmation_token": "55BA3440B1AAFFB64E51F497EFDF2022C90EDB171BBD979F04685904E38A89B7"
}

If there are no new notifications, the empty Notification object will be returned in this format:

  • type will be none if there are no new notifications
  • tx_state will be pending if there are still transactions waiting to clear and empty otherwise
  • next_notification_url will be provided whether there are new notifications or not so that that field can always be used to query the API for new notifications.
{
  "address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
  "type": "none",
  "tx_direction": "",
  "tx_state": "empty",
  "tx_result": "",
  "tx_ledger": "",
  "tx_hash": "",
  "tx_timestamp": "",
  "tx_timestamp_human": "",
  "tx_url": "",
  "next_notification_url": "http://api/v1/addresses/r../next_notification/5..",
  "confirmation_token": ""
}

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.

Making Payments

Preparing a Payment

GET /api/v1/addresses/:address/payments/:dst_address/:dst_amount

A payment needs to be formatted in the following order with the payment object to be submitted as a valid payment.

{
  "secret": "s...",
  "payment": { /* Payment Object */
    "source_address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
    "source_transaction_id": "12345",
    "destination_address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
    "destination_amount": {
      "value": "0.001",
      "currency": "XRP",
      "issuer": ""
    }
  }
}

The payment object itself can be prepared manually for any transactions that are occuring directly with XRP or if there are already established trustlines between the two parties for the currency being transferred. In most cases, a payment object can be created automatically by performing a GET on the payments endpoint.

This call generates possible payments for a given set of parameters. This is a wrapper around the Ripple path-find command that returns an array of Payment Objects, which can be submitted directly.

This uses the Payment Object format.

The :dst_amount parameter uses + to separate the value, currency, and issuer fields. For XRP the format is 0.1+XRP and for other currencies it is 0.1+USD+r..., where the r... is the Ripple address of the currency's issuer.

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

Submitting a Payment

POST /api/v1/addresses/:address/payments

Submit a payment in the Payment Object format.

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.

Request JSON:

{
  "secret": "s...",
  "payment": { /* Payment */ }
}

Response:

{
    "success": true,
    "confirmation_token": "55BA3440B1AAFFB64E51F497EFDF2022C90EDB171BBD979F04685904E38A89B7"
}

Or if there is a problem with the transaction:

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

Save the confirmation_token to check for transaction confirmation by matching that against new notification's. Payments cannot be cancelled once they are submitted.

Confirming a Payment

GET /api/v1/addresses/:address/next_notification/:tx_hash

A payment can be confirmed by retrieving a notification with the confirmation_token from the sucessfully submited payment. The tx_state will be "confirmed" if the payment has successfully gone through.

{
  "success": true,
  "notification": {
    "address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
    "type": "payment",
    "tx_direction": "outgoing",
    "tx_state": "confirmed",
    "tx_result": "tesSUCCESS",
    "tx_ledger": 4850743,
    "tx_hash": "81D48826FA84B0B83902CA3BFE49E2503A5BA1069B214D492AE6AB145B6C4781",
    "tx_timestamp": 1391792990000,
    "tx_timestamp_human": "2014-02-07T17:09:50.000Z",
    "tx_url": "https://api/v1/addresses/r../payments/81..?ledger=4850743",
    "next_notification_url": "https://api/v1/addresses/r../next_notification/81..?ledger=4850743"
    "confirmation_token": "81D48826FA84B0B83902CA3BFE49E2503A5BA1069B214D492AE6AB145B6C4781"
  }
}

#MONITORING

Applications will not only need to submit payments but monitor all incoming transactions that our occuring against the Ripple address. The general rule of thumb for monitoring your account should be the following:

  1. Checking the most recent notification
  2. Checking the next notification

Checking Notifications

Most recent notification

GET /api/v1/addresses/:address/next_notification

Use this to retrieve the most recent notification on the account:

To find out more information about that payment follow the link at tx_url. Otherwise follow the next_notification_url and check for the next notification.

If notifications are being retrieved from a rippled server that does not have a full historical database, the response may have serveral blank fields.

{
  "success": true,
  "notification": {
    "address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
    "type": "payment",
    "tx_direction": "incoming",
    "tx_state": "confirmed",
    "tx_result": "tesSUCCESS",
    "tx_ledger": 4716034,
    "tx_hash": "EC19E24AA51D39E809597A5DCF3A7E253F98C27FE3287CB919319A5C59AD8302",
    "tx_timestamp": 1391130630000,
    "tx_timestamp_human": "2014-01-31T01:10:30.000Z",
    "tx_url": "http://ripple-rest.herokuapp.com:49598/api/v1/addresses/rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz/payments/EC19E24AA51D39E809597A5DCF3A7E253F98C27FE3287CB919319A5C59AD8302?ledger=4716034",
    "next_notification_url": "http://ripple-rest.herokuapp.com:49598/api/v1/addresses/rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz/next_notification/EC19E24AA51D39E809597A5DCF3A7E253F98C27FE3287CB919319A5C59AD8302?ledger=4716034"
    "confirmation_token": ""
  }
}

Checking next notification

GET /api/v1/addresses/:address/next_notification/:prev_tx_hash

By checking for the most recent notification above, take the hash from the most recent notification to monitor if another notification has arrived. If there is no notifications newer than the most recent, than you will receive the notification object with:

"type": "none" "tx_state": "empty"

Because the type is none and the tx_state is empty, that means there is no next notification (yet) and there are no transactions pending in the outgoing queue. A tx_state of pending would indicate that there are still transactions waiting for confirmation.

If there is a newer notification than the one you are checking on, than the response will contain a new notification object.

Retrieving a Payment

GET /api/v1/addresses/:address/payments/:tx_hash

Use this to retrieve the details of a specfic payment with the transaction hash. A Payment object format will be returned with the details of the payment filled out including the path of the payment.

#RIPPLED SERVER STATUS

It is important to be able to check on the status of the ripple-rest server and the connected rippled server that it is currently connected to.

Check 'rippled' Status

GET /api/v1/status

Will return the status of the current rippled server that the ripple-rest server is configured to communicate with. The response body looks like this:

{
  "api_server_status": "online",
  "rippled_server_url": "wss://s_west.ripple.com:443",
  "rippled_server_status": {
    "info": {
      "build_version": "0.21.0-rc2",
      "complete_ledgers": "32570-4805506",
      "hostid": "BUSH",
      "last_close": {
        "converge_time_s": 2.011,
        "proposers": 5
      },
      "load_factor": 1,
      "peers": 51,
      "pubkey_node": "n9KNUUntNaDqvMVMKZLPHhGaWZDnx7soeUiHjeQE8ejR45DmHyfx",
      "server_state": "full",
      "validated_ledger": {
        "age": 2,
        "base_fee_xrp": 0.00001,
        "hash": "2B79CECB06A500A2FB92F4FB610D33A20CF8D7FB39F2C2C7C3A6BD0D75A1884A",
        "reserve_base_xrp": 20,
        "reserve_inc_xrp": 5,
        "seq": 4805506
      },
      "validation_quorum": 3
    }
  },
  "api_documentation_url": "https://github.com/ripple/ripple-rest"
}