Stellar Order Books API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Order Books API
  description: 'The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.

    '
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://platform-server.exampleanchor.com
tags:
- name: Order Books
  description: An order book is a collections of offers for a specific pair of assets.
paths:
  /order_book:
    get:
      tags:
      - Order Books
      summary: Retrieve an Order Book
      description: 'The order book endpoint provides an order book''s bids and asks and can be used in [streaming](https://developers.stellar.org/docs/data/apis/horizon/api-reference/structure/streaming) mode.


        When filtering for a specific order book, you must use use all six of these arguments: `base_asset_type`, `base_asset_issuer`, `base_asset_code`, `counter_asset_type`, `counter_asset_issuer`, and `counter_asset_code`. If the base or counter asset is XLM, you only need to indicate the asset type as `native` and do not need to designate the code or the issuer.

        '
      operationId: RetrieveAnOrderBook
      parameters:
      - $ref: '#/components/parameters/SellingAssetTypeRequiredParam'
      - $ref: '#/components/parameters/SellingAssetIssuerParam'
      - $ref: '#/components/parameters/SellingAssetCodeParam'
      - $ref: '#/components/parameters/BuyingAssetTypeParam'
      - $ref: '#/components/parameters/BuyingAssetIssuerParam'
      - $ref: '#/components/parameters/BuyingAssetCodeParam'
      - $ref: '#/components/parameters/OrderBookLimitParam'
      x-supports-streaming: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBook'
              examples:
                RetrieveAnOrderBook:
                  $ref: '#/components/examples/RetrieveAnOrderBook'
      x-codeSamples:
      - lang: Shell
        source: 'curl https://horizon-testnet.stellar.org/order_book?\

          selling_asset_type=native&\

          buying_asset_type=credit_alphanum4&\

          buying_asset_code=USDC&\

          buying_asset_issuer=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN&\

          limit=4

          '
      - lang: JavaScript
        label: '@stellar/stellar-sdk'
        source: "var StellarSdk = require(\"@stellar/stellar-sdk\");\nvar server = new StellarSdk.Horizon.Server(\n  \"https://horizon-testnet.stellar.org\",\n);\n\nserver\n  .orderbook(\n    new StellarSdk.Asset.native(),\n    new StellarSdk.Asset(\n      \"BB1\",\n      \"GD5J6HLF5666X4AZLTFTXLY46J5SW7EXRKBLEYPJP33S33MXZGV6CWFN\",\n    ),\n  )\n  .call()\n  .then(function (resp) {\n    console.log(resp);\n  })\n  .catch(function (err) {\n    console.error(err);\n  });\n"
components:
  schemas:
    OrderBook:
      type: object
      properties:
        bids:
          type: array
          items:
            type: object
            properties:
              price_r:
                type: object
                properties:
                  n:
                    type: integer
                  d:
                    type: integer
              price:
                type: string
              amount:
                type: string
        asks:
          type: array
          items:
            type: object
            properties:
              price_r:
                type: object
                properties:
                  n:
                    type: integer
                  d:
                    type: integer
              price:
                type: string
              amount:
                type: string
        base:
          type: object
          properties:
            asset_type:
              type: string
        counter:
          type: object
          properties:
            asset_type:
              type: string
            asset_code:
              type: string
            asset_issuer:
              $ref: '#/components/schemas/address'
    address:
      type: string
      pattern: G[A-Z0-9]{55}
  parameters:
    SellingAssetTypeRequiredParam:
      name: selling_asset_type
      in: query
      required: true
      description: The type for the asset being sold (base asset). Either `native`, `credit_alphanum4`, or `credit_alphanum12`.
      schema:
        type: string
        enum:
        - native
        - credit_alphanum4
        - credit_alphanum12
    BuyingAssetCodeParam:
      name: buying_asset_code
      in: query
      required: false
      description: The code for the asset being bought (counter asset). Required if the `buying_asset_type` is not `native`.
      schema:
        type: string
        example: EUR
    OrderBookLimitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of records returned. The limit can range from 1 to 200 — an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 20 for order books.
      schema:
        type: integer
        example: 20
    BuyingAssetIssuerParam:
      name: buying_asset_issuer
      in: query
      required: false
      description: The Stellar address of the issuer of the asset being bought (counter asset). Required if the `buying_asset_type` is not `native`.
      schema:
        type: string
        example: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
    SellingAssetCodeParam:
      name: selling_asset_code
      in: query
      required: false
      description: The code for the asset being sold (base asset). Required if the `selling_asset_type` is not `native`.
      schema:
        type: string
        example: USD
    SellingAssetIssuerParam:
      name: selling_asset_issuer
      in: query
      required: false
      description: The Stellar address of the issuer of the asset being sold (base asset). Required if the `selling_asset_type` is not `native`.
      schema:
        type: string
        example: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
    BuyingAssetTypeParam:
      name: buying_asset_type
      in: query
      required: false
      description: The type for the asset being bought (counter asset). Either `native`, `credit_alphanum4`, or `credit_alphanum12`.
      schema:
        type: string
        enum:
        - native
        - credit_alphanum4
        - credit_alphanum12
  examples:
    RetrieveAnOrderBook:
      value:
        bids:
        - price_r:
            n: 10000000
            d: 139999999
          price: '0.0714286'
          amount: '24.9999990'
        - price_r:
            n: 1
            d: 14
          price: '0.0714286'
          amount: '188.0000000'
        - price_r:
            n: 1
            d: 15
          price: '0.0666667'
          amount: '230.3200000'
        - price_r:
            n: 1
            d: 16
          price: '0.0625000'
          amount: '50.0000000'
        asks:
        - price_r:
            n: 5000000
            d: 62500001
          price: '0.0800000'
          amount: '4.9400001'
        - price_r:
            n: 10000000
            d: 125000001
          price: '0.0800000'
          amount: '2516.5154327'
        - price_r:
            n: 2
            d: 25
          price: '0.0800000'
          amount: '3125.0000000'
        - price_r:
            n: 4
            d: 49
          price: '0.0816327'
          amount: '4593.7500000'
        base:
          asset_type: native
        counter:
          asset_type: credit_alphanum4
          asset_code: BB1
          asset_issuer: GD5J6HLF5666X4AZLTFTXLY46J5SW7EXRKBLEYPJP33S33MXZGV6CWFN