Introduction

FIX Introduction

This document details the Financial Information eXchange (FIX) protocol used by the Ripple Crypto trading. Ripple uses FIX protocol to stream (Taker API), retrieve (Maker API) prices, and handle orders with a counterparty, referred to generically in this document as the “Client”. To communicate with Ripple via the FIX protocol, there must be IP connectivity between Ripple and the Client, and the Client must initiate the connection. The Client must support the FIX 4.4 or FIX 4.2 protocol to communicate properly with Ripple. The diagram below presents a high-level overview of the FIX-based FX electronic dealing architecture.
Ripple provides two FIX sessions for interaction with Clients. The first session is specifically for price communication and the second is for trading. Clients need to ensure that the appropriate session is used when messages are sent to Ripple.
This document defines the Ripple FIX API for sending out market prices, receiving orders and providing trading execution notifications via the Ripple FIX gateway

• The FIX gateway is accessible with an OpenVPN connection.
• There are two interfaces: FIX Market data (price) and FIX Trading (orders).
• FIX Trading and Fix Market data require a valid SenderCompId, login, and password specified in the Logon message.
• The protocol is based on FIX protocol 4.4 FIX protocol 4.4. Refer to FIX 4.4 documentation if there is no tag information specified.
• FIX 4.2 is also supported, but is more limited and less recommended
• The FIX gateway supports a subset of messages and tags listed in this document.
• Price is represented in natural value (e.g. 25000.01 for BTC/USD).

FIX Connectivity

• The following are the ways a client can connect to the API:
  • Internet over VPN
• VPN connectivity is routed to the nearest geographical instance - New York, London, or Singapore.
• Access to the platform has to go through SSL encrypted TCP connection over the Internet. If needed, Ripple can provide all necessary keys and certifications.
  
• Only one market and trade connection per client is supported.

FIX Session Time

• The session will be up the full week with a 3-minute scheduled restart on a weekly basis every Sunday. The exact time for restart will be scheduled with the client.
  • StartDay=Sunday
  • EndDay=Sunday
  • StartTime=07:03:00
  • EndTime=07:00:00

FIX Sessions

• The Ripple trading interface supports the two types of orders
  • Limit
  • Market
• The Ripple trading interface supports the following Time in force (TIF):
  • IOC - Immediate or Cancel
  • FOK - Fill or kill
  • Market - Best attempt at market price

FIX Post Trade

For clients or partners requiring a post-trade message (supported only for Taker API), and that can code to the Ripple FIX API the following Trade Capture Report (AE) message will be sent. In addition, in the event of a communication breakdown, the client can send a “Request Trade Capture Report” message and include in it all the Order IDs for which they want to verify if a trade was created or not.

FIX Messages, Products and Support

• The API supports the following:
  • FIX version 4.4 (recommended) and 4.2
  • Single session or Dual session.
  • Product type - Spot trading only.
  • Assets - any crypto coin and FIAT currency are supported. Limitations on what Assets are allowed are defined in the application and business agreement.
  • For FIX 4.2 and FIX 4.4 dual sessions - if we receive a message on the wrong session- it will be rejected. In addition, FIX 4.2 doesn’t support all message types.

FIX Duplicate check (recovery)

Taker API There is always a possibility of duplicate trades being sent out. For example due to a network disconnection. The client is expected to be able to identify duplicate trades and reject them, by using the tag OrderID (37) with the combination of tags PossDupFlag (43) or OrigSendingTime (122).

Maker API Gap-fill (recovery) for Maker API is disabled by default to prevent sending out old orders that are no longer relevant. In case a Resend Request (35=2) from the maker side is sent: we will reply with Sequence Reset (35=4) and the latest NewSeqNo (36). We can enable Gap-fill but it is not recommended.

FIX Header and Trailer

The following defines the FIX messages standard header and trailer.

Header

Trailer

Websocket API Introduction

Ripple websocket provides two websocket session for communication.

• Market session - used for market data subscription requests and streaming prices.
• Trade session - used for sending orders and receiving execution reports.

Market and Trade session require valid login, server identifier, client identifier and password(used only for hashing) for authentication.

Websocket API Connectivity

• Only one market and trade connection per client supported, on new connection previous connection will be dropped.
• When the trade session goes down market data feed will not be consumed (Maker API) even if the market session is connected. Market data snapshot consumption will resume after the trade session is reconnected.
• Both market and trade session needs to be authenticated before any requests can be made.
• To keep alive both the market and trade session, the client needs to send a ping message every 30 seconds.

Websocket API Sessions

• The Ripple market websocket session supports the following subscription type:

  • Snapshot

• The Ripple market websocket session supports the following book type:

  • Spot

• The Ripple trading websocket session supports the two types of orders

  • Limit
  • Market

• The Ripple trading websocket session supports the following Time in force (TIF):

  • IOC - Immediate or Cancel
  • FOK - Fill or kill

Environments

Ripple offer a UAT environment for client testing along with the Production environment.

Production

When onBoarding is done, Ripple will issue all the credentials necessary to connect to the production environment.

UAT

Ripple User Acceptance Testing (UAT) environment provides full trading capabilities allowing you to test any part of the Taker and Maker API for Both FIX and WebSocket Protocol.
Please note that your experience in UAT environments may differ slightly from that of the current production implementation and undergoes regular maintenance. Please contact us to start onBoarding and receive the necessary credentials to login. Once your UAT account has been set up, we will provide you a URL linke to be able to start and stop your environment on demand.

FIX Taker API

Logon

FIX 4.4 Client -> Ripple

This message is sent to initiate a FIX session and establishes the communication session, authenticates the connecting client, and initializes the message sequence number.

8=FIX.4.4|9=79|35=A|49=cc11|56=cs1|34=1|52=20221031-07:40:55|98=0|108=20|553=User1|554=123456|10=034|

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=62|35=A|34=1|49=cs1|52=20221031-07:40:55.074|56=cc11|98=0|108=20|10=039|

FIX 4.2 Client -> Ripple

8=FIX.4.2|9=58|35=A|49=cc21|56=cs1|34=1|52=20221031-07:41:49|98=0|108=20|10=102|

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=62|35=A|34=1|49=cs1|52=20221031-07:41:50.005|56=cc21|98=0|108=20|10=028|

Heartbeat

This message is sent during periods of application inactivity to ensure connection validity. The receiving party should always respond with a heartbeat message.

Test Request

This message is used to verify connectivity and synchronize sequence numbers. A test request should be responded to with a heartbeat from the recipient

Logout

This message signals the normal termination of the trading session. A session terminated without a Logout message will be considered an abnormal condition.

Market Data Request

Once the logon process is complete, Market Data Requests can be sent to Ripple. Ripple will respond immediately with either a Market Data Full Refresh (35=W) message or a Market Data Request Reject message (35=Y). Only a single product can be requested in each request. The client will receive both bid and ask prices in a single message. Ripple also supports layers (also known elsewhere as price bands or tiers). Quotes containing bid prices and quantities for all layers are always streamed in the same message, as is the case for quotes containing ask prices and quantities.

This message is used to subscribe/unsubscribe to market data rate information.

FIX 4.4 Client -> Ripple subscribe

8=FIX.4.4|9=99|35=V|49=cc12|56=cs1|34=8|52=20221031-07:43:44|262=1|263=1|264=0|146=1|55=BTC/USD|267=2|269=0|269=1|10=095|

FIX 4.2 Client -> Ripple subscribe

8=FIX.4.2|9=99|35=V|49=cc22|56=cs1|34=3|52=20221031-08:34:43|262=1|263=1|264=0|146=1|55=BTC/USD|267=2|269=0|269=1|10=089|

FIX 4.4 Client -> Ripple Unsubscribe

8=FIX.4.4|9=99|35=V|49=cc12|56=cs1|34=7|52=20221031-08:35:17|262=1|263=2|264=0|146=1|55=BTC/USD|267=2|269=0|269=1|10=097|

FIX 4.4 Client -> Ripple Unsubscribe

8=FIX.4.2|9=99|35=V|49=cc22|56=cs1|34=5|52=20221031-08:34:55|262=1|263=2|264=0|146=1|55=BTC/USD|267=2|269=0|269=1|10=095|

Market Data Request Reject

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=85|35=Y|34=106|49=cs1|52=20221031-09:03:57.488|56=cc12|58=Duplicate MDReqID|262=1|281=1|10=094|

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=84|35=Y|34=84|49=cs1|52=20221031-08:58:35.817|56=cc22|58=Duplicate MDReqID|262=1|281=1|10=050|

Market Data Snapshot Full

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=710|35=W|34=8|49=cs1|52=20221031-08:35:11.416|56=cc12|55=BTC/USD|262=1|268=20|269=0|270=202.15|271=0.00000001|269=0|270=202.16|271=0.00000002|269=0|270=202.17|271=0.00000003|269=0|270=202.18|271=0.00000004|269=0|270=202.19|271=0.00000005|269=0|270=202.2|271=0.00000006|269=0|270=202.21|271=0.00000007|269=0|270=202.22|271=0.00000008|269=0|270=202.23|271=0.00000009|269=0|270=202.24|271=0.0000001|269=1|270=202.35|271=0.00000001|269=1|270=202.36|271=0.00000002|269=1|270=202.37|271=0.00000003|269=1|270=202.38|271=0.00000004|269=1|270=202.39|271=0.00000005|269=1|270=202.4|271=0.00000006|269=1|270=202.41|271=0.00000007|269=1|270=202.42|271=0.00000008|269=1|270=202.43|271=0.00000009|269=1|270=202.44|271=0.0000001|10=073|

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=710|35=W|34=3|49=cs1|52=20221031-08:34:44.164|56=cc22|55=BTC/USD|262=1|268=20|269=0|270=202.15|271=0.00000001|269=0|270=202.16|271=0.00000002|269=0|270=202.17|271=0.00000003|269=0|270=202.18|271=0.00000004|269=0|270=202.19|271=0.00000005|269=0|270=202.2|271=0.00000006|269=0|270=202.21|271=0.00000007|269=0|270=202.22|271=0.00000008|269=0|270=202.23|271=0.00000009|269=0|270=202.24|271=0.0000001|269=1|270=202.35|271=0.00000001|269=1|270=202.36|271=0.00000002|269=1|270=202.37|271=0.00000003|269=1|270=202.38|271=0.00000004|269=1|270=202.39|271=0.00000005|269=1|270=202.4|271=0.00000006|269=1|270=202.41|271=0.00000007|269=1|270=202.42|271=0.00000008|269=1|270=202.43|271=0.00000009|269=1|270=202.44|271=0.0000001|10=072|

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=100|35=W|34=268|49=cs1|52=20230619-09:45:58.883|56=cc12|55=ETH/USD|262=1|268=0|10=184| 

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=100|35=W|34=268|49=cs1|52=20230619-09:45:58.883|56=cc12|55=ETH/USD|262=1|268=0|10=184| 

New Order Single

A new order single message enables the client to send a request for a trade to Ripple. Ripple requires that the ClOrdID <11> be unique.

FIX 4.4 Client -> Ripple

8=FIX.4.4|9=133|35=D|49=cc11|56=cs1|34=113|52=20221031-09:10:46|11=1598950759|21=1|55=BTC/USD|54=1|60=20221031-09:10:46|40=2|44=19123.20|38=100|59=4|10=003|

FIX 4.2 Client -> Ripple

8=FIX.4.2|9=133|35=D|49=cc21|56=cs1|34=113|52=20221031-09:11:04|11=1805964193|21=1|55=BTC/USD|54=1|60=20221031-09:11:04|40=2|44=19123.20|38=100|59=4|10=23

Reject

This message is used by Ripple to reject any message. This can happen if the message doesn’t comply with the FIX dictionary, naming issue, or bad input.

Execution Report

This message is used to communicate Order Ack, Order Reject, Order Fill and Order Status Responses.

• There are Four possible 35=8 responses to an order
  • Ack - 150 =0
  • NACK - 150=8
  • Fill - partial - 150 =2/F, 39=1
  • Fill - full - 150 =2/F, 39=2

For a FOK type order, there are two possible responses – as an example if the order is for 5 BTC/USD

Scenario 1 – FOK – order is not filled - CANCEL

Scenario 2 – FOK – order is fully filled - DONE

For an IOC type order, there are two additional possible responses in addition to the ones above which may happen in the case of multiple partial fills. We use the OrdStatus tag to indicate if the order is partial or fully complete – as an example if the order is for 5 BTCUSD

Scenario1 – IOC – order is fully filled - DONE

FIX 4.4 Ripple -> Client Ack

8=FIX.4.4|9=197|35=8|34=112|49=cs1|52=20221031-09:10:46.686|56=cc11|11=1598950759|14=0|15=BTC|17=1598950759|32=0|37=A010tlPyxyg|39=0|41=1598950759|44=19123.2|54=1|55=BTC/USD|60=20221031-11:10:46.686|150=0|151=100|10=012|

FIX 4.2 Ripple -> Client Ack

8=FIX.4.2|9=197|35=8|34=113|49=cs1|52=20221031-09:11:04.479|56=cc21|11=1805964193|14=0|15=BTC|17=1805964193|20=0|32=0|37=A010tlPyxyh|39=0|41=1805964193|44=19123.2|54=1|55=BTC/USD|60=20221031-11:11:04.479|150=0|151=100|10=223|

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=228|35=8|34=113|49=cs1|52=20221031-09:10:46.706|56=cc11|6=19123.2|11=1598950759|14=100|15=BTC|17=VuzGNOBG|31=19123.2|32=100|37=A010tlPyxyg|38=100|39=2|41=1598950759|44=19123.2|54=1|55=BTC/USD|60=20221031-11:10:46.706|64=202210304|150=F|151=0|10=153|

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=228|35=8|34=114|49=cs1|52=20221031-09:11:04.480|56=cc21|6=19123.2|11=1805964193|14=100|15=BTC|17=CAfoHyfD|20=2|31=19123.2|32=100|37=A010tlPyxyh|38=100|39=2|41=1805964193|44=19123.2|54=1|55=BTC/USD|60=20221031-11:11:04.480|64=202210304|150=2|151=0|10=136|

Order Cancel Request

This message is used by the client to cancel any live order they may have. Applicable for orders of type GTC.
In case Ripple is unable to cancel the order a Cancel Rejected (35=9) message will be sent as a response.
In case Ripple was able to cancel the order an Execution Report (35=8) with status cancel for OrdStatus and ExecType (39=4, 150=0) will be sent back.

FIX 4.4 Client -> Ripple

8=FIX.4.4|9=109|35=F|49=cc11|56=cs1|34=15|52=20240326-12:50:52|41=1598950759|11=1598950759|55=BTC/USD|60=20240326-12:50:52|37=A010tlPyxyg|10=232|

FIX 4.2 Client -> Ripple

8=FIX.4.2|9=109|35=F|49=cc11|56=cs1|34=15|52=20240326-12:50:52|41=1598950759|11=1598950759|55=BTC/USD|60=20240326-12:50:52|37=A010tlPyxyg|10=232|

Cancel Rejected

This message is used by Ripple to reject a cancel order message. This can happen if the order is already filled or is in the process of getting filled.

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=112|35=9|34=44|49=cs1|52=20240326-12:23:27.864|56=cc21|11=1598950759|37=A010tlPyxyg|39=8|41=1598950759|102=99|434=1|10=134|

FIX 4.2 Ripple -> Client

8=FIX.4.2|9=112|35=9|34=44|49=cs1|52=20240326-12:23:27.864|56=cc21|11=1598950759|37=A010tlPyxyg|39=8|41=1598950759|102=99|434=1|10=134|

Trade Capture Report

Used to report a trade between counterparties.

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=239|35=AE|34=2|49=cs1|52=20221031-09:43:02.535|56=cc11|17=s1|31=1234.56|32=0.00025|55=BTC/USD|60=20221030-10:10:28.629|75=20190824|150=F|487=0|568=HjdFFY13|571=A010tlPGF9S|748=1|912=Y|552=1|54=1|37=s3|11=123546|453=1|448=1|447=C|452=17|15=BTC|10=031

Request Trade Capture Report

In the event of a communication breakdown, or any other prerogative the client can send a “Request Trade Capture Report” message and include in it the Order Id for which they want to verify if a trade was created or not using ClOrdID <11>. The system will respond with AE drop copy messages for all created trades. Please note – an Order (if not of type FOK) may result in several trades and may be partially filled. The system will respond with all trades related to an order.

FIX 4.4 Client -> Ripple

8=FIX.4.4|9=76|35=AD|49=cc11|56=cs1|34=3|52=20221031-09:43:02|568=HjdFFY13|569=1|11=123546|10=182|

Trade Capture Report Request Ack

Indicate that no trades were found that matched the selection criteria specified on the Trade Capture Report Request (AQ).

• No Trade - In this case the AQ msg is provided with Tag 750 =1 (Completed).
• In the event that system is unable to provide a response the AQ msg is provided with Tag 750=2 (Rejected) and a reason will be provided in Tag 58
• In the event the order has been “Timed Out” the AQ msg is provided with Tag 750=0 and a reason will be provided in Tag 58 “Time out”. In this case you can continue every 5 seconds to retry the Trade capture request (AD) until a final response is received.

FIX 4.4 Ripple -> Client

8=FIX.4.4|9=88|35=AQ|34=2|49=cs1|52=20221031-09:51:41.171|56=cc11|568=HjdFFY13|569=1|748=0|749=0|750=0|10=230

Order Status Request

The Order Status Request message is used by the client to generate an order status message and get details about it.

• If information exists client will receive an Execution Report message with the order status and order information.
  
• If information is missing client will get a Business Message Reject with the reject reason.

FIX 4.4 Client -> Ripple

8=FIX.4.4|9=90|35=H|49=cc11|56=cs1|34=16|52=20240902-08:40:11|55=BTC/USD|54=1|37=223456OID|11=223456COID|10=168

FIX 4.2 Client -> Ripple

8=FIX.4.2|9=90|35=H|49=cc11|56=cs1|34=16|52=20240902-08:40:11|55=BTC/USD|54=1|37=223456OID|11=223456COID|10=168

Error Code

Websocket API Signature

Signature needs to be generated at the time of login request. It can be generated using the following steps:

• Generate a string by concatenating password and constant string "/verify"
• Signature would be Base64 encoded hash of the above string generates using HMAC SHA256 algorithm.

Java code sample

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class SignatureDemo {

  public static String getSign(String passPhrase, long timeStamp) {
    try {
      String stringToHashAndEncode = timeStamp + "/verify";
      Mac sha256HMAC = Mac.getInstance("HmacSHA256");

      SecretKeySpec secretKeySpec = new SecretKeySpec(passPhrase.getBytes(), "HmacSHA256");
      sha256HMAC.init(secretKeySpec);
      String hash = Base64.getEncoder().encodeToString(sha256HMAC.doFinal(stringToHashAndEncode.getBytes()));
      return hash;
    } catch (Throwable t) {
      return null;
    }
  }

  public static void main(String[] args) {
    String signature = getSign("UfawYizemLAHMyAezkYQqLtQ3uJ9UQaXXJg6vrvL", System.currentTimeMillis());
    System.out.println("Signature : " + signature);
  }
}

Python Example

  import hashlib
  import hmac
  import base64

  string_to_hash_and_encode = timeStamp + "/verify"
  hash_obj = hmac.new(secret_key, message, hashlib.sha256)
  hash_value = base64.b64encode(hash_obj.digest()).decode("utf-8")

shell Example

getSign() {
    local passPhrase=$1
    local timeStamp=$2

    local stringToHashAndEncode="${timeStamp}/verify"
    local hash

    hash=$(echo -n "$stringToHashAndEncode" | openssl dgst -sha256 -hmac "$passPhrase" -binary | base64)
}

# Example usage:
passPhrase="UfawYizemLAHMyAezkYQqLtQ3uJ9UQaXXJg6vrvL"
timeStamp="1695616595908"

result=$(getSign "$passPhrase" "$timeStamp")
echo "Result: $result"

Websocket Taker API

Login

Client -> Ripple.
Both market and trade session needs to be authenticated before any requests can be made.

Request parameters

Request

{
  "op": "logon",
  "arg": {
    "apiKey": "User1",
    "sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs=",
    "server": "cs1",
    "client": "cc11"
  },
  "ts": 1667835722651
}

Response

Success Response

{
  "op": "logon",
  "arg": {
    "code": 0
  },
  "ts": 1682346263287
}

Error response

{
  "op": "logon",
  "arg": {
    "code": 50104,
    "errMsg": "Invalid credentials"
  },
  "ts": 1682346263287
}

Ping

Client -> Ripple.
To keep the connection alive client needs to send a heartbeat message ping once every 30 seconds. If no heartbeat message is received for 30 seconds connection will be dropped.
Rate limit : 1 request per 15 seconds Connection dropped in case of rate limit breach.

Request

{
  "op": "ping"
}

Response

{
  "op": "ping"
}

Subscribe

Client -> Ripple.
Client will subscribe to desired instruments to be able to retrieve a stream of market data.

Request Example

{
  "op": "subscribe",
  "arg": {
    "instrument": "BTC/USD",
    "side": "BOTH",
    "subscriptionId": "FhervfD",
    "quantity" : 0,
    "subscriptionRequestType": "snapshot",
    "typeBook": "SPOT",
    "aggBook": 0,
    "marketDepth":0
  },
  "ts": 1667835722651
}

Request subscribe RFQ

{
  "op": "rfqsubscribe",
  "arg": {
    "instrument": "ETH/USD",
    "side": "BOTH",
    "subscriptionId": "123456",
    "quantity" : 0.1,
    "subscriptionRequestType": "rfqsnapshot",
    "typeBook": "SPOT",
    "aggBook": "0",
    "marketDepth":0
  },
  "ts": 1667835722651
}

Success Response Example

{
  "op": "subscribe",
  "arg":
  {
    "instrument": "BTC/USD",
    "side": "BOTH",
    "subscriptionId": "FhervfD",
    "subscriptionRequestType": "snapshot",
    "typeBook": "SPOT",
    "aggBook": 0,
    "marketDepth": 0,
    "code": 0
  },
  "ts": 1667835722651
}

Error response Example

{
  "op": "subscribe",
  "arg":
  {
    "instrument": "BTC/USD",
    "side": "BOTH",
    "subscriptionId": "FhervfD",
    "subscriptionRequestType": "snapshot",
    "typeBook": "SPOT",
    "aggBook": 0,
    "marketDepth": 0,
    "errMsg": "Duplicate market data request symbol",
    "code": 50206
  },
  "ts": 1667835722651
}

Request parameters

Response

Unsubscribe

Client -> Ripple.
To stop receiving market data unsubscribe call for the product needs to be made. Taker sends the below request to Ripple.

Request Example

{
  "op": "unsubscribe",
  "arg": {
    "subscriptionId": "FhervfD",
    "instrument": "BTC/USD",
    "typeBook": "SPOT"
  },
  "timestamp": 1667835722653
}

Success Response Example

{
    "op": "unsubscribe",
    "arg":
    {
        "subscriptionId": "FhervfD",
        "instrument": "BTC/USD",
        "typeBook": "SPOT",
        "code": "0"
    },
    "ts": 1706601058528
}

Error response Example

{
    "ts": 1667835722653,
    "op": "unsubscribe",
    "arg":
    {
        "subscriptionId": "FhervfD",
        "instrument": "BTC/USD",
        "typeBook": "SPOT",
        "errMsg": "Invalid subscription id",
        "code": 50251
    }
}

Request parameters

Response

Market data snapshot

Ripple -> Client.
Once client subscribed to desired instrument a stream of market data snapshot will be sent to him.

Snapshot

{
    "op": "snapshot",
    "arg":
    {
        "instrument": "BTC/USD",
        "subscriptionId": "FhervfD"
    },
    "data":
    [
        {
            "bids":
            [
              [42732.79,0.1],
              [42732.78,0.2],
              [42732.77,0.3],
              [42732.76,0.4],
              [42732.75,0.5],
              [42732.74,0.6],
              [42732.73,0.6],
              [42732.72,0.7],
              [42732.71,0.8],
              [42732.70,0.9]
            ],
            "asks":
            [
              [42733.70,0.1],
              [42733.71,0.2],
              [42733.72,0.3],
              [42733.73,0.4],
              [42733.74,0.5],
              [42733.75,0.6],
              [42733.76,0.6],
              [42733.77,0.7],
              [42733.78,0.8],
              [42733.79,0.9]
            ]
        }
    ]
}

Request parameters

Order

Client -> Ripple.
To place an order taker sends request to Ripple.

Order

{
  "op": "order",
  "arg": {
    "instrument": "BTC/USD",
    "side": "BUY",
    "clOrderId": "SDfcsef35",
    "orderType": "LIMIT",
    "tif": "FOK",
    "account": "tag1",
    "quantity": 100,
    "price": 19123
  },
  "ts": 1667835722653
}

Order acknowledgement success

{
    "op": "order",
    "arg":
    {
        "instrument": "BTC/USD",
        "side": "BUY",
        "clOrderId": "SDfcsef35",
        "orderType": "LIMIT",
        "tif": "FOK",
        "account": "tag1",
        "quantity": 100.0,
        "price": 19123.0,
        "code": 0
    },
    "ts": 1706601667000
}

Order acknowledgement failure

{
    "ts": 1667835722653,
    "op": "order",
    "arg":
    {
        "instrument": "BTC/USD",
        "side": "B",
        "clOrderId": "SDfcsef35",
        "orderType": "LIMIT",
        "tif": "FOK",
        "account": "tag1",
        "quantity": 100,
        "price": 19123,
        "errMsg": "Unsupported side, only BUY or SELL allowed",
        "code": 50301
    }
}

Request parameters

Response

Order

Active GTC orders can be canceled by sending a cancel request to Ripple either using client order id or order id. If order cancellation succeeds a trade with canceled state will be sent to the client. If order cancellation fails order cancellation failure message will be sent to client.

Order Cancellation using client order id

{
  "op": "cancel_order",
  "arg":
  {
    "clOrderId": "f8e065c2-087e-4f22-b5b9-748ba2fed2fb",
    "instrument": "BTC/USD"
  },
  "ts": 1667835722653
}

Request parameters

Order Cancellation using order id

{
    "op": "cancel_order",
    "arg":
    {
        "orderId": "A010uoqUy4S",
        "instrument": "BTC/USD"
    },
    "ts": 1726392007830
}

Request parameters

Order Cancellation failure

{
    "op": "cancel_order",
    "arg":
    {
        "clOrderId": "cee79af3-8dac-4a2c-be7f-d73793f93b5d",
        "orderId": "A010uoqWW5g",
        "instrument": "BTC/USD",
        "code": 1,
        "errMsg": "Order cancellation failed for clientOrderId [cee79af3-8dac-4a2c-be7f-d73793f93b5d] error [error message]"
    },
    "ts": 1726392515132
}

Response parameters

Trade

Ripple -> Client.
As a response for an order Ripple will reply with a trade.

Request Example

{
    "ts": 1706601667037,
    "op": "trade",
    "arg":
    {
        "instrument": "BTC/USD",
        "side": "BUY",
        "clOrderId": "SDfcsef35",
        "orderId": "A010u2PAFQD",
        "tradeId": "OGdjCsRA",
        "orderType": "LIMIT",
        "state": "FILLED",
        "quantity": 100.0,
        "cumQty": 100.0,
        "account": "tag1",
        "lastQty": 100.0,
        "leaveQty": 0.0,
        "lastPrice": 19123.2,
        "price": 19123.2,
        "avgPrice": 19123.2
    }
}

Request parameters

Websocket API Error Codes

REST API

The Settlement REST API lets a Taker retrieve its own settlement obligations and the audit trail behind them. It complements the FIX and WebSocket trading APIs: trades executed there create settlement obligations that are exposed here.

All endpoints are read-only (GET) and scoped to the authenticated client — you only ever see your own settlements.

Authentication

Every request must include your client API key in the X-API-Key header. The key identifies your organization; there is no separate login step or request signing.

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/settlements"

Get Settlement Obligations

Retrieve all active (Open / Partial) settlement obligation lines for the authenticated client, with pagination.

HTTP Request

GET /api/client/settlements

Query Parameters

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/settlements?page=1&page_size=100"

200 OK

{
    "success": true,
    "settlements": {
        "SET12345678": {
            "client": 1,
            "organizationType": "TAKER",
            "type": "Net",
            "status": "Partial",
            "createdAt": "2025-10-28T10:00:00Z",
            "updatedAt": "2025-10-28T11:30:00Z",
            "lines": [
                {
                    "asset": "BTC",
                    "amount": "1.5",
                    "amountSettled": "0.5",
                    "direction": "Receive",
                    "status": "Partial",
                    "settlementDate": "30/10/2025"
                }
            ],
            "postTrades": ["LCXLBL0v65ZWb7", "LCXLBL0v65ZWb8"]
        }
    },
    "pagination": {
        "page": 1,
        "pageSize": 100,
        "totalObligations": 22,
        "totalLines": 45,
        "totalPages": 1
    }
}

Response Fields

Get Aggregated Settlements

Retrieve a net summary per asset for the authenticated client — total amounts to receive or pay — along with obligation status counts.

HTTP Request

GET /api/client/aggregated-settlements

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/aggregated-settlements"

200 OK

{
    "success": true,
    "client": 1,
    "totalObligations": 5,
    "open": 2,
    "partial": 1,
    "done": 2,
    "assets": {
        "BTC": { "asset": "BTC", "toReceive": 1.5, "toPay": 0 },
        "USD": { "asset": "USD", "toReceive": 0, "toPay": 1000 }
    }
}

Response Fields

Get Settlement By Id

Retrieve the details of a single settlement obligation. You can only access your own settlements.

HTTP Request

GET /api/client/settlements/{settlement_id}

Path Parameters

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/settlements/SET12345678"

200 OK

{
    "success": true,
    "settlement": {
        "id": "SET12345678",
        "client": 1,
        "organizationType": "TAKER",
        "type": "Net",
        "status": "Partial",
        "createdAt": "2025-10-28T10:00:00Z",
        "updatedAt": "2025-10-28T11:30:00Z",
        "lines": [
            {
                "asset": "BTC",
                "amount": "1.5",
                "amountSettled": "0.5",
                "direction": "Receive",
                "status": "Partial",
                "settlementDate": "30/10/2025"
            }
        ],
        "postTrades": ["LCXLBL0v65ZWb7", "LCXLBL0v65ZWb8"]
    }
}

The settlement object uses the same fields as the obligation entries in Get Settlement Obligations, with an additional id field.

Get Settlement Log

Retrieve the transaction history (audit trail) for the client's settlement obligations on a given date. Each entry records a status change and the amount settled.

HTTP Request

GET /api/client/settlements/log

Query Parameters

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/settlements/log?log_date=2025-10-28&asset=BTC"

200 OK

{
    "success": true,
    "transactions": [
        {
            "id": "456",
            "settlementId": "123",
            "client": 1,
            "asset": "BTC",
            "amountSettled": "0.5",
            "direction": "Receive",
            "timestamp": "2025-10-28T10:00:00Z",
            "notes": "Partial settlement",
            "previousStatus": "Open",
            "newStatus": "Partial"
        }
    ],
    "count": 1,
    "date": "2025-10-28"
}

Response Fields

Get Settlement Log By Id

Retrieve the audit trail for a single settlement obligation.

HTTP Request

GET /api/client/settlements/log/{settlement_id}

Path Parameters

Example

curl -H "X-API-Key: your-client-api-key" \
     "$BASE_URL/api/client/settlements/log/SET12345678"

200 OK

{
    "success": true,
    "settlementObligationId": "SET12345678",
    "transactions": [
        {
            "id": "456",
            "settlementId": "123",
            "client": 1,
            "asset": "BTC",
            "amountSettled": "0.5",
            "direction": "Receive",
            "timestamp": "2025-10-28T10:00:00Z",
            "notes": "Partial settlement",
            "previousStatus": "Open",
            "newStatus": "Partial"
        }
    ],
    "count": 1
}

The transactions entries use the same fields as Get Settlement Log.

REST API Errors