Stellar Order Books API

openapi: 3.2.0
info:
  title: Horizon Order Books API
  version: 0.0.1
  summary: Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by Stellar Core. This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.
  description: 'Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by [Stellar Core](https://developers.stellar.org/network/core-node). This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.


    Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](https://developers.stellar.org/docs/tools/sdks). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls.


    This guide describes how to administer a production Horizon instance (refer to the [Developers'' Blog](https://www.stellar.org/developers-blog/a-new-sun-on-the-horizon) for some background on the performance and architectural improvements of this major version bump). For information about developing on the Horizon codebase, check out the [Development Guide](https://github.com/stellar/stellar-horizon/blob/main/DEVELOPING.md).


    Before we begin, it''s worth reiterating the sentiment echoed in the [Core Node](https://developers.stellar.org/network/core-node) documentation: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we''ll refer to this as a "Captive Core" instance).

    '
  termsOfService: https://stellar.org/terms-of-service
  contact:
    name: Stellar Development Foundation
    url: https://stellar.org
    email: hello@stellar.org
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://horizon-testnet.stellar.org
  description: The Testnet Network
- url: https://horizon-futurenet.stellar.org
  description: The Futurenet network
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:
  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
    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
    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
    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
    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
    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
  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}
  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
x-tagGroups:
- name: Resources
  tags:
  - Accounts
  - Assets
  - Claimable Balances
  - Effects
  - Ledgers
  - Liquidity Pools
  - Offers
  - Operations
  - Payments
  - Trades
  - Transactions
- name: Aggregations
  tags:
  - Order Books
  - Paths
  - Trade Aggregations
  - Fee Stats