Skip to content

RippleNet Server API (4.0.0)

The RippleNet Server API provides you the ability to develop custom applications to manage or interact with your RippleNet instance.

Check out the best practices and tutorials.

Authentication

All API operations require a bearer access token for your target environment.<br>Learn how to request the access token.

API environments

The RippleNet Server API creates a dynamic [domainPrefix] that consists of {tenant}.{environment}.

Note: This example uses aperture as the tenant. Your tenant ID is different.

EnvironmentDomaing PrefixDomainBase URL
Testaperture.testripplexcurrent.comhttps://aperture.test.ripplexcurrent.com
UATaperture.uatripplexcurrent.comhttps://aperture.uat.ripplexcurrent.com
Productionaperture.prodripplexcurrent.comhttps://aperture.prod.ripplexcurrent.com
Languages
Servers
Mock server

https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/

https://[domainPrefix].ripplexcurrent.com/v4/

Account configuration

Operations

Auditing

Operations

Balances and statements

Operations

Beneficiary confirmation

Operations

Diagnostics

Operations

Exchange transfers

Operations

Get exchange transfers

Request

Gets all exchange transfers.

Security
Bearer
Query
pageinteger

The page number for paginated results. The value is zero-based, where 0 represents the first page.<br/> Set it to 0 to get the first page of results.

Default 0
sizeinteger[ 1 .. 100 ]

Number of objects to return per page.

Default 20
curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/exchange_transfers?page=0&size=20' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved exchange transfers.

Bodyapplication/json
firstboolean

true if this is the first page.

lastboolean

true if this is the last page.

numberinteger

page number

numberOfElementsinteger

Number Of elements in this request

sizeinteger

page size

totalElementsinteger(int64)

Total number of elements for the given request

totalPagesinteger

Total number of pages for the given request

sortArray of objects

Sort details of this page

directionstring

Direction of the sort

Example: "ASC"
propertystring
ignoreCaseboolean
nullHandlingstring
Example: "NULLS_FIRST"
ascendingboolean
Example: true
descendingboolean
Example: false
contentArray of objects

Provides an array of exchange transfer objects.

exchange_transfer_idstring(uuid)required

Unique identifier of the exchange transfer.

Example: "e3b20ba4-28ed-4752-990d-e67887bb331e"
statestringrequired

State of the exchange transfer.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
typestringrequired

Indicates the exchange transfer's quoted FX rate type.

Default "FIRM"
Enum ValueDescription
FIRM

A firm exchange rate ensures that the quoted and delivered transfer amounts are equal.

INDICATIVE

An indicative exchange rate allows for movement between quoted rate and transfer execution, such that the quoted amount and delivered amount may differ.

Example: "INDICATIVE"
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf@rn.us.ca.san_francisco"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf_gbp@rn.us.ca.san_francisco"
source_amountnumberrequired

Sending amount of the exchange transfer.

Example: 1
destination_amountnumberrequired

Receiving amount of the exchange transfer.

Example: 355
source_currencystringrequired

Sending currency of the exchange transfer.

Example: "USD"
destination_currencystringrequired

Receiving currency of the exchange transfer.

Example: "GBP"
fx_transfer_rateobjectrequired

Describes an exchange rate used in an exchange transfer.

ratenumberrequired

Exchange rate used to make the exchange transfer.

Example: 0.89
base_currencystringrequired

Base currency for custom rate for the sending account.

Example: "USD"
counter_currencystringrequired

Counter currency for custom rate for the sending account.

Example: "GBP"
rate_typestringrequired

Rate type used to make the exchange transfer. Valid values are BUY or SELL.

Example: "BUY"
end_to_end_idstringrequired

ID set by the sender that is persisted on all fiat node instances that participated in the transfer.

internal_idstringrequired

Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.

user_infoArray of objectsrequired

Custom information set by a RippleNet address involved in the exchange transfer.

node_addressstringrequired

RippleNet address of the fiat node instance that set the user information.

Example: "rn.us.ny.new_york"
statestringrequired

State of the exchange transfer set when the RippleNet address set the user information.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
jsonobjectrequired

One or more arbitrary key/value pairs.

created_atstring(date-time)

timestamp of when this user info was created

Response
application/json
{
  "first": true,
  "last": true,
  "number": 0,
  "numberOfElements": 0,
  "size": 0,
  "totalElements": 0,
  "totalPages": 0,
  "sort": [
    { … }
  ],
  "content": [
    { … }
  ]
}

Execute exchange transfer

Request

Execute an exchange transfer to move funds from one of your accounts in one currency (USD, for example) to another one of your accounts in another currency (EUR, for example) at an exchange rate set by your peer who maintains both of your accounts on their ledger. An exchange transfer enables you to fund a foreign currency account from your domestic currency account in bulk.

Before you make this request, you may want to use the Quote Exchange Transfer request to see a quote for the exchange transfer you want to make.

Security
Bearer
Bodyapplication/jsonrequired
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "alias_usd_lon@rn.eur.uk.london"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "conct_gbp_lon@rn.eur.uk.london"
amountnumber>= 0required

Amount transferred, expressed in the curency of the account indicated by the amount_type value.

Example: 100
amount_typestringrequired

Amount type used for the exchange transfer.<p>To indicate that the amount is expressed in the currency of the account provided by the sender_address value, set to SENDER_AMOUNT.</p> <p>To indicate that the amount is expressed in the currency of the account provided by the receiver_address value, set to RECEIVER_AMOUNT.</p>

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT"
Example: "SENDER_AMOUNT"
end_to_end_idstring<= 128 characters

ID set by the sender that is persisted on all fiat node instances that participated in the transfer.

Example: 378910
internal_idstring<= 128 characters

Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.

Example: 1987
user_infoobject

Provide one or more arbitrary key/value pairs.

curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/exchange_transfers/execute \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_address": "alias_usd_lon@rn.eur.uk.london",
    "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
    "amount": 100,
    "amount_type": "SENDER_AMOUNT",
    "end_to_end_id": 378910,
    "internal_id": 1987,
    "user_info": {}
  }'

Responses

Successfully executed exchange transfer.

Bodyapplication/json
exchange_transfer_idstring(uuid)required

Unique identifier of the exchange transfer.

Example: "e3b20ba4-28ed-4752-990d-e67887bb331e"
statestringrequired

State of the exchange transfer.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
typestringrequired

Indicates the exchange transfer's quoted FX rate type.

Default "FIRM"
Enum ValueDescription
FIRM

A firm exchange rate ensures that the quoted and delivered transfer amounts are equal.

INDICATIVE

An indicative exchange rate allows for movement between quoted rate and transfer execution, such that the quoted amount and delivered amount may differ.

Example: "INDICATIVE"
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf@rn.us.ca.san_francisco"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf_gbp@rn.us.ca.san_francisco"
source_amountnumberrequired

Sending amount of the exchange transfer.

Example: 1
destination_amountnumberrequired

Receiving amount of the exchange transfer.

Example: 355
source_currencystringrequired

Sending currency of the exchange transfer.

Example: "USD"
destination_currencystringrequired

Receiving currency of the exchange transfer.

Example: "GBP"
fx_transfer_rateobjectrequired

Describes an exchange rate used in an exchange transfer.

ratenumberrequired

Exchange rate used to make the exchange transfer.

Example: 0.89
base_currencystringrequired

Base currency for custom rate for the sending account.

Example: "USD"
counter_currencystringrequired

Counter currency for custom rate for the sending account.

Example: "GBP"
rate_typestringrequired

Rate type used to make the exchange transfer. Valid values are BUY or SELL.

Example: "BUY"
end_to_end_idstringrequired

ID set by the sender that is persisted on all fiat node instances that participated in the transfer.

internal_idstringrequired

Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.

user_infoArray of objectsrequired

Custom information set by a RippleNet address involved in the exchange transfer.

node_addressstringrequired

RippleNet address of the fiat node instance that set the user information.

Example: "rn.us.ny.new_york"
statestringrequired

State of the exchange transfer set when the RippleNet address set the user information.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
jsonobjectrequired

One or more arbitrary key/value pairs.

created_atstring(date-time)

timestamp of when this user info was created

Response
application/json
{
  "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  "state": "EXECUTED",
  "type": "INDICATIVE",
  "sender_address": "sf@rn.us.ca.san_francisco",
  "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  "source_amount": 1,
  "destination_amount": 355,
  "source_currency": "USD",
  "destination_currency": "GBP",
  "fx_transfer_rate": {
    "rate": 0.89,
    "base_currency": "USD",
    "counter_currency": "GBP",
    "rate_type": "BUY"
  },
  "end_to_end_id": "string",
  "internal_id": "string",
  "user_info": [
    { … }
  ]
}

Get exchange transfer quote

Request

Requests a quote for an exchange transfer.

Security
Bearer
Bodyapplication/jsonrequired
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "alias_usd_lon@rn.eur.uk.london"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "conct_gbp_lon@rn.eur.uk.london"
amountnumber>= 0required

Amount transferred, expressed in the curency of the account indicated by the amount_type value.

Example: 100
amount_typestringrequired

Amount type of the exchange transfer.<p>To indicate that the amount is expressed in the currency of the account provided by the sender_address value, set to SENDER_AMOUNT.</p> <p>To indicate that the amount is expressed in the currency of the account provided by the receiver_address value, set to RECEIVER_AMOUNT.</p>

Enum"SENDER_AMOUNT""RECEIVER_AMOUNT"
Example: "SENDER_AMOUNT"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/exchange_transfers/quote \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "sender_address": "alias_usd_lon@rn.eur.uk.london",
    "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
    "amount": 100,
    "amount_type": "SENDER_AMOUNT"
  }'

Responses

Successfully quoted exchange transfer.

Bodyapplication/json
typestringrequired

Indicates the exchange transfer's quoted FX rate type.

Default "FIRM"
Enum ValueDescription
FIRM

A firm exchange rate ensures that the quoted and delivered transfer amounts are equal.

INDICATIVE

An indicative exchange rate allows for movement between quoted rate and transfer execution, such that the quoted amount and delivered amount may differ.

Example: "INDICATIVE"
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "alias_usd_lon@rn.eur.uk.london"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "conct_gbp_lon@rn.eur.uk.london"
source_amountnumberrequired

Sending amount of the exchange transfer.

Example: 100
destination_amountnumberrequired

Receiving amount of the exchange transfer.

Example: 89
source_currencystringrequired

Sending currency of the exchange transfer.

Example: "USD"
destination_currencystringrequired

Receiving currency of the exchange transfer.

Example: "GBP"
fx_transfer_rateobjectrequired

Describes an exchange rate used in an exchange transfer.

ratenumberrequired

Exchange rate used to make the exchange transfer.

Example: 0.89
base_currencystringrequired

Base currency for custom rate for the sending account.

Example: "USD"
counter_currencystringrequired

Counter currency for custom rate for the sending account.

Example: "GBP"
rate_typestringrequired

Rate type used to make the exchange transfer. Valid values are BUY or SELL.

Example: "BUY"
Response
application/json
{
  "type": "INDICATIVE",
  "sender_address": "alias_usd_lon@rn.eur.uk.london",
  "receiver_address": "conct_gbp_lon@rn.eur.uk.london",
  "source_amount": 100,
  "destination_amount": 89,
  "source_currency": "USD",
  "destination_currency": "GBP",
  "fx_transfer_rate": {
    "rate": 0.89,
    "base_currency": "USD",
    "counter_currency": "GBP",
    "rate_type": "BUY"
  }
}

Complete exchange transfer

Request

Updates the status of an exchange transfer to COMPLETED. Make this request once the exchange transfer has been made on both the ledger and on internal systems.

Security
Bearer
Path
idstring(uuid)required

Unique identifier of the exchange transfer to complete.

curl -i -X POST \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/exchange_transfers/{id}/complete' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully completed exchange transfer.

Bodyapplication/json
exchange_transfer_idstring(uuid)required

Unique identifier of the exchange transfer.

Example: "e3b20ba4-28ed-4752-990d-e67887bb331e"
statestringrequired

State of the exchange transfer.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
typestringrequired

Indicates the exchange transfer's quoted FX rate type.

Default "FIRM"
Enum ValueDescription
FIRM

A firm exchange rate ensures that the quoted and delivered transfer amounts are equal.

INDICATIVE

An indicative exchange rate allows for movement between quoted rate and transfer execution, such that the quoted amount and delivered amount may differ.

Example: "INDICATIVE"
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf@rn.us.ca.san_francisco"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf_gbp@rn.us.ca.san_francisco"
source_amountnumberrequired

Sending amount of the exchange transfer.

Example: 1
destination_amountnumberrequired

Receiving amount of the exchange transfer.

Example: 355
source_currencystringrequired

Sending currency of the exchange transfer.

Example: "USD"
destination_currencystringrequired

Receiving currency of the exchange transfer.

Example: "GBP"
fx_transfer_rateobjectrequired

Describes an exchange rate used in an exchange transfer.

ratenumberrequired

Exchange rate used to make the exchange transfer.

Example: 0.89
base_currencystringrequired

Base currency for custom rate for the sending account.

Example: "USD"
counter_currencystringrequired

Counter currency for custom rate for the sending account.

Example: "GBP"
rate_typestringrequired

Rate type used to make the exchange transfer. Valid values are BUY or SELL.

Example: "BUY"
end_to_end_idstringrequired

ID set by the sender that is persisted on all fiat node instances that participated in the transfer.

internal_idstringrequired

Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.

user_infoArray of objectsrequired

Custom information set by a RippleNet address involved in the exchange transfer.

node_addressstringrequired

RippleNet address of the fiat node instance that set the user information.

Example: "rn.us.ny.new_york"
statestringrequired

State of the exchange transfer set when the RippleNet address set the user information.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
jsonobjectrequired

One or more arbitrary key/value pairs.

created_atstring(date-time)

timestamp of when this user info was created

Response
application/json
{
  "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  "state": "EXECUTED",
  "type": "INDICATIVE",
  "sender_address": "sf@rn.us.ca.san_francisco",
  "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  "source_amount": 1,
  "destination_amount": 355,
  "source_currency": "USD",
  "destination_currency": "GBP",
  "fx_transfer_rate": {
    "rate": 0.89,
    "base_currency": "USD",
    "counter_currency": "GBP",
    "rate_type": "BUY"
  },
  "end_to_end_id": "string",
  "internal_id": "string",
  "user_info": [
    { … }
  ]
}

Get exchange transfer by ID

Request

Gets an exchange transfer by ID.

Security
Bearer
Path
idstring(uuid)required

Unique identifier of the exchange transfer you want to retrieve.

curl -i -X GET \
  'https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/exchange_transfers/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully retrieved exchange transfer.

Bodyapplication/json
exchange_transfer_idstring(uuid)required

Unique identifier of the exchange transfer.

Example: "e3b20ba4-28ed-4752-990d-e67887bb331e"
statestringrequired

State of the exchange transfer.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
typestringrequired

Indicates the exchange transfer's quoted FX rate type.

Default "FIRM"
Enum ValueDescription
FIRM

A firm exchange rate ensures that the quoted and delivered transfer amounts are equal.

INDICATIVE

An indicative exchange rate allows for movement between quoted rate and transfer execution, such that the quoted amount and delivered amount may differ.

Example: "INDICATIVE"
sender_addressstringrequired

RippleNet account name and address of the sender, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf@rn.us.ca.san_francisco"
receiver_addressstringrequired

RippleNet account name and address of the receiver, in the format accountname@ripplenetaddress. For example, new_york@rn.us.ny.new_york.

Example: "sf_gbp@rn.us.ca.san_francisco"
source_amountnumberrequired

Sending amount of the exchange transfer.

Example: 1
destination_amountnumberrequired

Receiving amount of the exchange transfer.

Example: 355
source_currencystringrequired

Sending currency of the exchange transfer.

Example: "USD"
destination_currencystringrequired

Receiving currency of the exchange transfer.

Example: "GBP"
fx_transfer_rateobjectrequired

Describes an exchange rate used in an exchange transfer.

ratenumberrequired

Exchange rate used to make the exchange transfer.

Example: 0.89
base_currencystringrequired

Base currency for custom rate for the sending account.

Example: "USD"
counter_currencystringrequired

Counter currency for custom rate for the sending account.

Example: "GBP"
rate_typestringrequired

Rate type used to make the exchange transfer. Valid values are BUY or SELL.

Example: "BUY"
end_to_end_idstringrequired

ID set by the sender that is persisted on all fiat node instances that participated in the transfer.

internal_idstringrequired

Internal ID that the sender can optionally specify. Only visible to the sender. Only the sending fiat node instance stores this ID.

user_infoArray of objectsrequired

Custom information set by a RippleNet address involved in the exchange transfer.

node_addressstringrequired

RippleNet address of the fiat node instance that set the user information.

Example: "rn.us.ny.new_york"
statestringrequired

State of the exchange transfer set when the RippleNet address set the user information.

Enum"EXECUTED""COMPLETED""FAILED"
Example: "EXECUTED"
jsonobjectrequired

One or more arbitrary key/value pairs.

created_atstring(date-time)

timestamp of when this user info was created

Response
application/json
{
  "exchange_transfer_id": "e3b20ba4-28ed-4752-990d-e67887bb331e",
  "state": "EXECUTED",
  "type": "INDICATIVE",
  "sender_address": "sf@rn.us.ca.san_francisco",
  "receiver_address": "sf_gbp@rn.us.ca.san_francisco",
  "source_amount": 1,
  "destination_amount": 355,
  "source_currency": "USD",
  "destination_currency": "GBP",
  "fx_transfer_rate": {
    "rate": 0.89,
    "base_currency": "USD",
    "counter_currency": "GBP",
    "rate_type": "BUY"
  },
  "end_to_end_id": "string",
  "internal_id": "string",
  "user_info": [
    { … }
  ]
}

Fees

Operations

Liquidation configuration

Operations

Non-orchestration payments

Operations

Notifications

Operations

ODL flags configuration

Operations

Orchestration payments

Operations

Payment expiration

Operations

Payout method

Operations

Platform accounts

Operations

Pool accounts

Operations

Quote expiration

Operations

Quotes

Operations

Rates

Operations

Request for payment

Operations

Sender segregated account configuration

Operations

Transfers

Operations

schema

Operations

activity

Operations

Orchestration Template

Operations

diagnostics

Operations

payment

Operations

Get application info

Request

Gets application information.

Security
Bearer
curl -i -X GET \
  https://docs.ripple.com/_mock/products/payments-odl/api-docs/ripplenet/ripplenet/v4/orchestration/info \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successfully fetched application info.

Bodyapplication/json
namestring

Application name.

Example: "Integration Module"
versionstring

Application version.

Example: "1.2.0"
Response
application/json
{
  "name": "Integration Module",
  "version": "1.2.0"
}

tenant

Operations

Orchestration internal action

Operations

Orchestration internal payments

Operations

Orchestration internal notifications

Operations