Ripple Labs Liquidations API

openapi: 3.0.0
info:
  title: Palisade Addresses Liquidations API
  description: The Palisade API enables programmatic interaction with the various features of the Palisade platform
  version: '2.0'
servers:
- url: https://api.sandbox.palisade.co
  description: Sandbox server (uses TESTNET data, private keys and accounts)
- url: https://api.palisade.co
  description: Palisade server (uses MAINNET data, private keys and accounts)
security:
- TokenAuth: []
tags:
- name: Liquidations
  description: 'Use these operations to retrieve liquidations from the Smart Liquidation service.


    | Operation | Method | Description |

    | -- | -- | -- |

    | [Get liquidations](#operation/getLiquidations)   | GET       | List all liquidations by date range.    |

    | [Get liquidation by Liquidation Id](#operation/getLiquidationById)  | GET       | Gets a liquidation by `Id`. |

    | [Get liquidation by RippleNet Payment Id](#operation/getLiquidationsByRipplenetPaymentId) | GET | Gets a liquidation by `ripplenet_payment_id`. |


    **Note:** To configure liquidation, contact your RippleNet liaison.


    ### Authentication with Smart Liquidation Service


    All API operations require a bearer access token for your target environment.<br>Learn how to [request the access token](/products/payments-odl/api-docs/ripplenet/best-practices/authentication/#request-the-access-token).


    ### Domain prefixes with Smart Liquidation Service


    | **Environment** | **Domain Prefix** | **Request URL** |

    | --- | --- | --- |

    | **Test** | `liquidation-test.pub.prod` | `https://liquidation-test.pub.prod.ripplenet.com` |

    | **Production** | `liquidation.pub.prod` | `https://liquidation.pub.prod.ripplenet.com` |

    '
paths:
  /liquidations:
    get:
      tags:
      - Liquidations
      operationId: getLiquidations
      summary: Get liquidations
      description: List all liquidations by date range
      parameters:
      - name: start_date
        in: query
        description: Start date (inclusive) of first activity. Specified in ISO-8601 format, for example `2018-08-06T23:13:55.997Z`
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: End date (exclusive) of last activity. Specified in ISO-8601 format, for example `2018-08-06T23:13:55.997Z`
        schema:
          type: string
          format: date-time
      - name: payment_id
        in: query
        description: RippleNet payment ID(s)
        explode: true
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: reference_id
        in: query
        description: Unique reference ID(s)
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: status
        in: query
        description: Liquidation status
        schema:
          type: string
      - name: page
        in: query
        description: 'The page number for [paginated results](/products/payments-odl/api-docs/ripplenet/best-practices/pagination/). The value is zero-based, where `0` represents the first page.<br/>

          Set it to `0` to get the first page of results.

          '
        schema:
          type: integer
          default: 0
      - name: size
        in: query
        description: Number of liquidations to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: Returns a paginated list of liquidations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiquidationListResponse'
        '400':
          description: Bad liquidation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: BAD_REQUEST
                    title: Bad Request
                    status: 400
                    detail: 'JSON parse error: problem: Cannot build LiquidationRequest, some of required attributes are not set [destinationVenue]'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '401':
          description: Authorization has expired for user to get liquidations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Unauthorized
                    status: 401
                    detail: 'An error occurred while attempting to decode the Jwt: Expired JWT'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '403':
          description: User is not authorized to get all liquidations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Forbidden
                    status: 403
                    detail: Could not verify the provided CSRF token because no token was found to compare.
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
  /liquidations/{id}:
    get:
      tags:
      - Liquidations
      operationId: getLiquidationById
      summary: Get liquidation by Id
      description: Get a specific liquidation by its unique `Id` value
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the liquidation. Obtain this value by performing a [GET liquidations](#operation/getLiquidations) operation.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns a liquidation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Liquidation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: BAD_REQUEST
                    title: Bad Request
                    status: 400
                    detail: 'JSON parse error: problem: Cannot build LiquidationRequest, some of required attributes are not set [destinationVenue]'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '401':
          description: Authorization has expired for user to get liquidations by ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Unauthorized
                    status: 401
                    detail: 'An error occurred while attempting to decode the Jwt: Expired JWT'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '403':
          description: User is not authorized to get liquidation by ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Forbidden
                    status: 403
                    detail: Could not verify the provided CSRF token because no token was found to compare.
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '404':
          description: Liquidation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: NOT_FOUND
                    title: Liquidation not found
                    status: 404
                    detail: Liquidation 'c2812c43-0874-42e6-b1b1-27e07b2bb1e5' not found
                    liquidationId: c2812c43-0874-42e6-b1b1-27e07b2bb1e5
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
  /liquidations/ripplenet-payment-id/{ripplenet_payment_id}:
    get:
      tags:
      - Liquidations
      operationId: getLiquidationsByRipplenetPaymentId
      summary: Get liquidations by payment Id
      description: Get a list of liquidations associated with a `ripplenet_payment_id`
      parameters:
      - name: ripplenet_payment_id
        in: path
        required: true
        description: Unique identifier for a RippleNet payment. Obtain this value by performing a [GET liquidations](#operation/getLiquidations) operation.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns a list of liquidations associated with the given ripplenet_payment_id
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Liquidation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: BAD_REQUEST
                    title: Bad Request
                    status: 400
                    detail: 'JSON parse error: problem: Cannot build LiquidationRequest, some of required attributes are not set [destinationVenue]'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '401':
          description: Authorization has expired for user to get liquidations by Ripplenet Payment ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Unauthorized
                    status: 401
                    detail: 'An error occurred while attempting to decode the Jwt: Expired JWT'
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
        '403':
          description: User is not authorized to get liquidations by Ripplenet Payment ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    type: AUTH_PROBLEM
                    title: Forbidden
                    status: 403
                    detail: Could not verify the provided CSRF token because no token was found to compare.
                    correlationId: b99decdd-0fe2-4f4c-bb6a-f7b6d60aee1c
                    timestamp: '2018-04-06T20:33:35Z'
components:
  schemas:
    Sort:
      type: object
      properties:
        direction:
          type: string
          description: Direction of the sort
          example: ASC
        property:
          type: string
          description: Property name to sort on
        ascending:
          type: boolean
          description: True if the sort direction is ascending
          example: true
        descending:
          type: boolean
          description: True if the sort direction is descending
          example: false
    LiquidationListResponse:
      allOf:
      - $ref: '#/components/schemas/Page'
      - type: object
        required:
        - results
        properties:
          results:
            type: array
            description: Array of all liquidation objects that match the specified query parameters, if any
            items:
              $ref: '#/components/schemas/LiquidationSummary'
    TradeExecution:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - type: object
        required:
        - trade_request_id
        - venue
        properties:
          trade_request_id:
            type: string
            description: The identifier of the trade request
          venue:
            type: string
            description: The exchange used by this trade
          venue_id:
            type: string
            description: The mapped id for the exchange used by this trade
          amount:
            type: number
            format: decimal
            description: The amount of XRP sent by this trade
          adjusted_amount:
            type: number
            format: decimal
            description: The adjusted amount of XRP sent by this trade
          proceeds:
            type: number
            format: decimal
            description: The amount of XRP liquidated
          adjusted_proceeds:
            type: number
            format: decimal
            description: The adjusted amount of XRP liquidated
          start_date:
            type: string
            format: date-time
            example: '2018-04-06T20:33:35Z'
            description: Start date (inclusive) of last activity
          end_date:
            type: string
            format: date-time
            example: '2018-04-06T20:33:35Z'
            description: Start date (inclusive) of last activity
          incentive_type:
            type: string
            description: The type of incentive (also called slippage)
          incentive_value:
            type: number
            format: decimal
            description: Amount of incentive (also called slippage) used
          is_pushed_forward:
            type: boolean
            description: True if the funds from a failed trade will be made available in fiat currency
          adjusted_trade_difference:
            type: number
            description: The trade amount including incentives
          executed_slippage_bps:
            type: integer
    LiquidationSourceEnum:
      type: string
      enum:
      - xrrn
      - operator
    LiquidationSummary:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/LiquidationRequest'
      - type: object
        required:
        - id
        - status
        - liquidation_source
        properties:
          liquidation_source:
            $ref: '#/components/schemas/LiquidationSourceEnum'
          status:
            $ref: '#/components/schemas/LiquidationStatusEnum'
    Page:
      type: object
      required:
      - first
      - last
      - number
      - numberOfElements
      - size
      - totalElements
      - totalPages
      - sort
      properties:
        first:
          type: boolean
          description: True if this is the first page
        last:
          type: boolean
          description: True if this is the last page
        number:
          type: integer
          description: Page number
        numberOfElements:
          type: integer
          description: Number of elements in this request
        size:
          type: integer
          description: Number of objects returned per page
        totalElements:
          type: integer
          description: Total number of elements for the given request
          format: int64
        totalPages:
          type: integer
          description: Total number of pages for the given request
        sort:
          type: array
          description: Sort details of this page
          items:
            $ref: '#/components/schemas/Sort'
      description: Paginated response base object
    EstimateTypeEnum:
      type: string
      enum:
      - firm
      - indicative
    Entity:
      type: object
      required:
      - id
      - account_id
      - created_at
      - modified_at
      properties:
        id:
          type: string
          description: Unique liquidation identifier
          format: uuid
        account_id:
          type: string
          description: The identifier of the account requesting the liquidation
        created_at:
          type: string
          description: Date specified in ISO-8601 format, for example `2018-04-06T20:33:35Z`
          format: date-time
          example: '2018-04-06T20:33:35Z'
        modified_at:
          type: string
          description: Date specified in ISO-8601 format, for example `2018-04-06T20:33:35Z`
          format: date-time
          example: '2018-04-06T20:33:35Z'
    ErrorResponse:
      type: object
      required:
      - title
      - status
      properties:
        type:
          $ref: '#/components/schemas/ErrorCodeEnum'
        title:
          type: string
          description: Summary of the returned problem.
        status:
          type: integer
          description: HTTP error code.
        detail:
          type: string
          description: Description of the returned problem.
        correlationId:
          type: string
          description: ID of the correlating request.
        timestamp:
          type: string
          description: Date and time at which the error occured.
        liquidationId:
          type: string
          description: Unique identifier of the liquidation.
    ErrorCodeEnum:
      type: string
      description: Type of problem.
      enum:
      - BAD_REQUEST
      - INVALID_DATES
      - INVALID_VENUE_AND_OR_CURRENCY
      - INVALID_LIQUIDATION_AMOUNT
      - NOT_FOUND
      - REFERENCE_ID_NOT_UNIQUE
      - AUTH_PROBLEM
      - GENERIC_CLIENT_ERROR
      - GENERIC_SERVER_ERROR
    Liquidation:
      allOf:
      - $ref: '#/components/schemas/LiquidationSummary'
      - type: object
        required:
        - trade_requests
        - execution_summary
        properties:
          status:
            $ref: '#/components/schemas/LiquidationStatusEnum'
          trade_requests:
            type: array
            description: An array of trade objects representing the trades of the liquidation
            items:
              $ref: '#/components/schemas/LiquidationTrade'
          execution_strategy:
            $ref: '#/components/schemas/ExecutionStrategy'
          execution_summary:
            $ref: '#/components/schemas/ExecutionSummary'
          trading_summary:
            $ref: '#/components/schemas/TradingSummary'
    LiquidationTrade:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - type: object
        required:
        - sequence_number
        - destination_venue
        - destination_currency
        - destination_amount
        - status
        - expires_at
        - liquidation_id
        - account_id
        - trade_executions
        - bridge_currency_code
        properties:
          liquidation_id:
            type: string
            description: The identifier of the liquidation
          sequence_number:
            type: integer
            description: The sequence number of the liquidation trade
          odl_payment_id:
            type: string
            description: The identifier of the ODL payment corresponding to the liquidation
          status:
            $ref: '#/components/schemas/LiquidationTradeStatusEnum'
          bridge_currency_code:
            type: string
            x-interal: true
          destination_amount:
            type: number
            format: decimal
            description: The total amount available for withdrawal after all fees have been collected
          destination_currency:
            type: string
            description: The 3-letter currency code of the destination currency of the trade
          destination_venue:
            type: string
            description: The name of the trade exchange where XRP is liquidated into fiat currency
          expires_at:
            type: string
            description: The expiration time of the liquidation trade
            format: date-time
            example: '2018-04-06T20:33:35Z'
          xrp_deposit_amount:
            type: number
            description: The XRP deposit amount of the trade
            format: decimal
          trade_executions:
            type: array
            description: The trade execution objects
            items:
              $ref: '#/components/schemas/TradeExecution'
          error_message:
            type: string
            description: The reason why a trade failed
          estimated_trade_displacement_bps:
            type: integer
            description: trade displacement bps in estimate
    LiquidationTradeStatusEnum:
      type: string
      enum:
      - CREATED
      - QUEUED
      - THROTTLED
      - QUOTED
      - STARTED
      - COMPLETED
      - PARTIALLY_COMPLETED
      - FAILED
      - FAILED_RETRYABLE
    ExecutionStrategy:
      type: object
      description: The trade execution strategy
      required:
      - maxAmountPerTrade
      - minimumTradeInterval
      properties:
        maxAmountPerTrade:
          type: number
          format: decimal
          description: The maximum amount (in destination currency) per trade
        minimumTradeInterval:
          type: integer
          description: The minimum interval (in seconds) between creation of trades
    LiquidationStatusEnum:
      type: string
      enum:
      - CREATED
      - QUEUED
      - STARTED
      - COMPLETED
      - PARTIALLY_COMPLETED
      - FAILED
    TradingSummary:
      type: object
      description: The trading summary
      properties:
        total_fiat_executed:
          type: number
          format: decimal
          description: the total amount of successfully delivered fiat
        total_fiat_in_flight:
          type: number
          format: decimal
          description: the total amount of fiat in flight (started but not yet finished trades)
        total_fiat_non_deliverable:
          type: number
          format: decimal
          description: the total amount of fiat that was not successfully confirmed to have been delivered due to unknown trade failures
        total_fiat_remaining_deliverable:
          type: number
          format: decimal
          description: the total amount of fiat that has not yet been delivered but is eligible to be delivered
    ExecutionSummary:
      type: object
      description: The trade execution summary
      required:
      - total_xrp
      - total_fiat
      - total_slippage
      - total_trades
      - total_sender_fees
      - total_receiver_fees
      properties:
        total_xrp:
          type: number
          format: decimal
          description: Total amount of XRP successfully liquidated
        total_fiat:
          type: number
          format: decimal
          description: Total fiat amount available for withdrawal after all fees have been collected
        total_slippage:
          type: number
          format: decimal
          description: Total amount of slippage (also called incentive) used
        total_sender_fees:
          type: number
          format: decimal
          description: Total XRP sender fees
        total_receiver_fees:
          type: number
          format: decimal
          description: Total fiat receiver fees
        total_trades:
          type: integer
          description: The total number of exchange orders/trades completed
        fx_rate:
          type: number
          format: decimal
          description: The conversion rate from XRP to destination currency (fiat)
        incentive_type:
          type: string
    LiquidationRequest:
      type: object
      required:
      - unique_reference_id
      - destination_venue
      - destination_currency
      - destination_amount
      - bridge_currency_code
      properties:
        unique_reference_id:
          type: string
          description: The unique 32-character string representing the liquidation
        ripplenet_payment_id:
          type: string
          format: uuid
          description: Unique identifier for a RippleNet payment
        ripplenet_payment_created_at:
          description: Timestamp when the RippleNet payment was created
          type: string
          format: date-time
        ripplenet_sender_address:
          description: RippleNet address of the sender
          type: string
          example: sf_gbp@rn.us.ca.san_francisco
        ripplenet_receiver_address:
          description: RippleNet address of the receiver
          example: sf_gbp@rn.us.ca.san_francisco
          type: string
        destination_amount:
          description: The total amount available for withdrawal after all fees have been collected
          type: number
          format: decimal
          example: 10000
        destination_currency:
          type: string
          description: The 3-letter currency code of the destination currency
          example: usd
        destination_venue:
          type: string
          description: The name of the exchange where XRP is liquidated into fiat currency
          example: bitso
        estimate_type:
          $ref: '#/components/schemas/EstimateTypeEnum'
        expires_at:
          type: string
          description: The expiration time of the liquidation
          format: date-time
          example: '2018-04-06T20:33:35Z'
  securitySchemes:
    TokenAuth:
      type: apiKey
      name: Authorization
      in: header
externalDocs:
  description: Click here for the API docs
  url: https://palisade.readme.io