Ripple Labs Rates API

openapi: 3.0.0
info:
  title: Palisade Addresses Rates 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: Rates
  description: '

    Use these operations to manage your rates.


    | Operation | Method | Description |

    | -- | -- | -- |

    | [Get rates](/products/payments-odl/api-docs/ripplenet/reference/openapi/rates/getrates)         | GET    | Gets a list of configured exchange rates. |

    | [Create rate](/products/payments-odl/api-docs/ripplenet/reference/openapi/rates/createrate)     | POST   | Creates an exchange rate for a specified currency pair. |

    | [Get rate by ID](/products/payments-odl/api-docs/ripplenet/reference/openapi/rates/getratebyid) | GET    | Gets a configured exchange rate by ID. |

    | [Update rate](/products/payments-odl/api-docs/ripplenet/reference/openapi/rates/updaterate)     | PUT    | Updates an existing exchange rate. |

    | [Delete rate](/products/payments-odl/api-docs/ripplenet/reference/openapi/rates/deleterate)     | DELETE | Deletes an exchange rate. Once deleted, an exchange rate cannot be accessed. |

    '
paths:
  /config/rates:
    get:
      tags:
      - Rates
      summary: Get rates
      description: Gets a list of configured exchange rates.
      operationId: getRates
      parameters:
      - 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.

          '
        required: false
        schema:
          type: integer
          default: 0
      - name: size
        in: query
        description: Number of objects to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Successfully returned list of rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rates'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleNetProblem'
      security:
      - Bearer: []
    post:
      tags:
      - Rates
      summary: Create rate
      description: 'Creates an exchange rate for a specified currency pair.


        **Example** - Applying a margin to the live FX rate:<br>

        A USD-GBP live FX rate of 0.80 is provided by a third-party rate provider and you want to reduce that rate by 20 BPS. In this API call, you would set `"value_type": "MARGIN"`, then `"margin_type": "BPS"`, and `"rate": "20"`. After that, during the `Get quotes` call, the final FX rate will be calculated as 0.80*(1-(20/10000))=`0.7984` and then applied during quote creation.

        '
      operationId: createRate
      requestBody:
        $ref: '#/components/requestBodies/RateRequest'
      responses:
        '200':
          description: Successfully created rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
        '400':
          description: Request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleNetProblem'
      security:
      - Bearer: []
  /config/rates/{rate_id}:
    get:
      tags:
      - Rates
      summary: Get rate by ID
      description: Gets a configured exchange rate by ID.
      operationId: getRateById
      parameters:
      - name: rate_id
        in: path
        description: Provide the `rate_id` of the exchange rate you want to return.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Sucessfully returned rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
        '404':
          description: Rate not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleNetProblem'
      security:
      - Bearer: []
    put:
      tags:
      - Rates
      summary: Update rate
      description: 'Updates an existing exchange rate. With this call, you can change `value_type` from `RATE` to `MARGIN` (and vice versa), change the actual `rate` value of the specified value type, or both.


        **Example** - Updating an existing margin applied to the live FX rate:<br>

        A USD-GBP live FX rate of 0.80 is provided by a third-party rate provider and you currently reduce that rate by 20 BPS. You now want to change it and reduce it by 10 BPS instead. To do so, set `"rate": "10"` in the request. Once the change is applied, the final FX rate is calculated as 0.80*(1-(10/10000))=`0.7992` during the `Get quotes` call, and then applied during quote creation.

        '
      operationId: updateRate
      parameters:
      - name: rate_id
        in: path
        description: Provide the `rate_id` of the exchange rate you want to update.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        $ref: '#/components/requestBodies/RateRequest'
      responses:
        '200':
          description: Successfully updated rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponse'
        '400':
          description: Request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleNetProblem'
      security:
      - Bearer: []
    delete:
      tags:
      - Rates
      summary: Delete rate
      description: Deletes an exchange rate. Once deleted, an exchange rate cannot be accessed.
      operationId: deleteRate
      parameters:
      - name: rate_id
        in: path
        description: Provide the `rate_id` of the exchange rate you want to delete.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully deleted rate.
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleNetProblem'
      security:
      - Bearer: []
components:
  schemas:
    Sort:
      type: object
      properties:
        direction:
          type: string
          description: Direction of the sort
          example: ASC
        property:
          type: string
        ignoreCase:
          type: boolean
        nullHandling:
          type: string
          example: NULLS_FIRST
        ascending:
          type: boolean
          example: true
        descending:
          type: boolean
          example: false
    RateRequest:
      type: object
      required:
      - base_currency
      - counter_currency
      - expiration_offset
      - order_type
      - rate
      properties:
        expiration_offset:
          type: integer
          example: 95000
          description: Set to the amount of time in milliseconds that the rate is valid for after the rate's `created_date` value. Set to `0` to indicate that the rate does not expire. The value returned in the response object for this field is `null`. Refer to the `expires_at` value in the response object to verify your expiration offset timing.
        order_type:
          type: string
          example: buy
          description: Set to the order type for the exchange rate.
          enum:
          - buy
          - sell
        rate:
          type: number
          example: 0.89
          description: "This value of this field represents either rate or margin based on what you specify in the `value_type` field. \n\nIf you specify `value_type=rate`, set the value of this field to the exchange rate for a base and counter currency. The rate can use up to 6 decimal\nplaces. \n\nIf you specify `value_type=margin`, set the value of this field depending on the unit of margin you specified in the `margin_type` field.\n"
        base_currency:
          type: string
          example: USD
          description: Set to the base currency of the exchange rate.
        counter_currency:
          type: string
          example: GBP
          description: Set to the counter currency of the exchange rate.
        ledger:
          $ref: '#/components/schemas/RatePerLedgerRequest'
        account:
          $ref: '#/components/schemas/RatePerAccountRequest'
        lower_limit:
          type: number
          example: 0
          description: To create a slab-based exchange rate, provide the lower limit of the slab. You must also provide an `upper_limit` value.
        upper_limit:
          type: number
          example: 1000
          description: To create a slab-based exchange rate, provide the upper limit of the slab. You must also provide a `lower_limit` value.
        payout_method:
          type: string
          example: LOCAL_RAILS
          description: The payout method for the rate.
        value_type:
          type: string
          example: MARGIN
          description: Specify whether you want to use a live exchange rate (`MARGIN`) or an exchange rate manually configured by Ripple (`RATE`). If you set this value to `MARGIN`, you must also provide `margin_type`.
          enum:
          - MARGIN
          - RATE
        margin_type:
          type: string
          example: BPS
          description: Specify the unit of margin to be applied (BPS) in addition to the rate provided by Ripple. Specify this field only if you set `value_type` = `MARGIN`.
          enum:
          - BPS
      description: Use this JSON request body to create an exchange rate for a base and counter currency.
    RateResponse:
      type: object
      required:
      - base_currency
      - counter_currency
      - created_date
      - destination_currency
      - destination_ledger
      - destination_ledger_account
      - expiration_offset
      - lower_limit
      - order_type
      - rate
      - rate_id
      - rate_scale
      - source_currency
      - source_ledger
      - source_ledger_account
      - upper_limit
      - value_type
      - margin_type
      properties:
        rate_id:
          type: string
          format: uuid
          example: 328b3e50-7983-46d5-94a0-ef004d78db1d
          description: Unique identifier of the exchange rate.
        expiration_offset:
          type: integer
          example: 95000
          description: <b>(DEPRECATED)</b> This property is deprecated. Refer to `expires_at` to determine rate expiration. <p>Amount of time in milliseconds that the rate is valid for after the rate's `created_date` value. For example, if the `expiration_offset` value is `100000` milliseconds, the rate expires `100000` milliseconds after this `created_date` value. If set to `0`, the rate does not expire.</p>
        order_type:
          type: string
          example: buy
          description: Order type for the exchange rate.
          enum:
          - buy
          - sell
        rate_scale:
          type: integer
          example: 9
          description: Number of decimal places to which the exchange rate is calculated. For example, if the `rate_scale` value is set to `9` and the `rate` value is set to `1.25`, the scaled value of the rate is `1.250000000`.
          default: 9
        rate:
          type: number
          example: 0.89
          description: Exchange rate for the specified base and counter currency.
        base_currency:
          type: string
          example: USD
          description: Base currency of the exchange rate.
        counter_currency:
          type: string
          example: GBP
          description: Counter currency of the exchange rate.
        source_currency:
          type: string
          example: USD
          description: If `order_type` is set to `buy`, this is set to the base currency. If `order_type` is set to `sell`, this is set to the counter currency.
        destination_currency:
          type: string
          example: GBP
          description: If `order_type` is set to `buy`, this is set to the counter currency. If `order_type` is set to `sell`, this is set to the base currency.
        source_ledger:
          type: string
          example: rn.eur.uk.london
          description: Source ledger associated with the exchange rate.
        destination_ledger:
          type: string
          example: rn.eur.uk.london
          description: Destination ledger associated with the exchange rate.
        source_ledger_account:
          type: string
          example: alias_usd_lon
          description: Account on the source ledger associated with rate.
        destination_ledger_account:
          type: string
          example: conct_gbp_lon
          description: Account on the destination ledger associated with rate.
        created_date:
          type: string
          format: date-time
          description: Date and time at which the exchange rate was created, as an ISO-8601 timestamp in UTC. Fiat determines a rate's expiration date and time based on this value and `expiration_offset` value. For example, if the `expiration_offset` value is `100000` milliseconds, the rate expires `100000` milliseconds after this `created_date` value.
        expires_at:
          type: string
          format: date-time
          description: The time in which this rate expires in system local timezone
        lower_limit:
          type: number
          example: 0
          description: For a slab-based exchange rate, indicates the lower limit of the slab.
        upper_limit:
          type: number
          example: 1000
          description: For a slab-based exchange rate, indicates the upper limit of the slab.
        payout_method:
          type: string
          example: LOCAL_RAILS
          description: The payout method for the rate.
        value_type:
          type: string
          example: MARGIN
          description: Indicates whether the rate is a live exchange rate (`MARGIN`) or an exchange rate manually configured by Ripple (`RATE`). If this value is `MARGIN`, then `margin_type` will show a value.
          enum:
          - MARGIN
          - RATE
        margin_type:
          type: string
          example: BPS
          description: Indicates the unit of margin applied in addition to the rate provided by Ripple. This field has a value only if `value_type` = `MARGIN`. If `value_type` is `RATE`, this field is `null`.
          enum:
          - BPS
      description: JSON response object that represents an exchange rate.
    RatePerLedgerRequest:
      type: object
      required:
      - destination_ledger
      - source_ledger
      properties:
        source_ledger:
          type: string
          example: rn.eur.uk.london
          description: Set to the source ledger associated with the exchange rate.
        destination_ledger:
          type: string
          example: rn.eur.uk.london
          description: Set to the destination ledger associated with the exchange rate.
      description: Use the `ledger` request object to create an exchange rate that applies to exchanges between a specific source ledger and destination ledger.
    RatePerAccountRequest:
      type: object
      required:
      - destination_ledger
      - destination_ledger_account
      - source_ledger
      - source_ledger_account
      properties:
        source_ledger:
          type: string
          example: rn.eur.uk.london
          description: Set to the source ledger associated with the exchange rate.
        destination_ledger:
          type: string
          example: rn.eur.uk.london
          description: Set to the destination ledger associated with the exchange rate.
        source_ledger_account:
          type: string
          example: alias_usd_lon
          description: Set to the account on the source ledger associated with the rate.
        destination_ledger_account:
          type: string
          example: conct_gbp_lon
          description: Set to the account on the destination ledger associated with the rate.
      description: Use the `account` request object to create an exchange rate that applies to exchanges between a specific source ledger account and destination ledger account.
    Page:
      type: object
      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: page size
        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.
    Rates:
      type: object
      required:
      - content
      allOf:
      - $ref: '#/components/schemas/Page'
      - properties:
          content:
            description: Provides an array of rate objects.
            type: array
            items:
              $ref: '#/components/schemas/RateResponse'
      description: Provides a `content` array of rate objects and a set of pagination information fields.
    RippleNetProblem:
      type: object
      description: Represents a request to create and update a payout method record.
      properties:
        type:
          type: string
          example: https://errors.ripplenet.ripple.com/error/json-processing-error
          description: URL to the error documentation.
        title:
          type: string
          example: Invalid Request Object
          description: Summary of the returned problem.
        detail:
          type: string
          example: The request parameter [account_id] is not in the correct format.
          description: Description of the returned problem.
        status:
          type: number
          example: 400
          description: HTTP error code.
        ripplenet_error_code:
          type: string
          example: E0104
          description: RippleNet specific error code.
        finality:
          type: string
          example: PERMANENT
          description: Specifies if the request can be retried for a successful response.
  requestBodies:
    RateRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateRequest'
      required: true
  securitySchemes:
    TokenAuth:
      type: apiKey
      name: Authorization
      in: header
externalDocs:
  description: Click here for the API docs
  url: https://palisade.readme.io