Stellar Trades API

openapi: 3.2.0
info:
  title: Horizon Trades 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: Trades
  description: When an offer is fully or partially fulfilled, a trade happens. Trades can also be caused by successful path payments, because path payments involve fulfilling offers. A trade occurs between two parties—base and counter. Which is which is either arbitrary or determined by the calling query.
paths:
  /trades:
    get:
      tags:
      - Trades
      summary: List All Trades
      description: 'This endpoint lists all trades and can be used in streaming mode. Streaming mode allows you to listen for new trades as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known trade unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream trades created since your request time. When filtering for a specific orderbook, 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: GetAllTrades
      parameters:
      - $ref: '#/components/parameters/OfferIdParam'
      - $ref: '#/components/parameters/BaseAssetTypeParam'
      - $ref: '#/components/parameters/BaseAssetIssuerParam'
      - $ref: '#/components/parameters/BaseAssetCodeParam'
      - $ref: '#/components/parameters/CounterAssetTypeParam'
      - $ref: '#/components/parameters/CounterAssetIssuerParam'
      - $ref: '#/components/parameters/CounterAssetCodeParam'
      - $ref: '#/components/parameters/TradeTypeParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      x-supports-streaming: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/Trade'
              examples:
                GetAllTrades:
                  $ref: '#/components/examples/GetAllTrades'
components:
  parameters:
    OrderParam:
      name: order
      in: query
      required: false
      description: A designation of the order in which records should appear. Options include `asc` (ascending) or `desc` (descending). If this argument isn’t set, it defaults to `asc`.
      schema:
        type: string
        enum:
        - asc
        - desc
    BaseAssetTypeParam:
      name: base_asset_type
      in: query
      required: false
      description: The type for the base asset. Either `native`, `credit_alphanum4`, or `credit_alphanum12`.
      schema:
        type: string
        enum:
        - native
        - credit_alphanum4
        - credit_alphanum12
    CounterAssetIssuerParam:
      name: counter_asset_issuer
      in: query
      required: false
      description: The Stellar address of the counter asset’s issuer. Required if the `counter_asset_type` is not `native`.
      schema:
        type: string
        example: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
    BaseAssetIssuerParam:
      name: base_asset_issuer
      in: query
      required: false
      description: The Stellar address of the base asset’s issuer. Required if the `base_asset_type` is not `native`.
      schema:
        type: string
        example: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
    BaseAssetCodeParam:
      name: base_asset_code
      in: query
      required: false
      description: The code for the base asset. Required if the `base_asset_type` is not `native`.
      schema:
        type: string
        example: USD
    LimitParam:
      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 10.
      schema:
        type: integer
        example: 10
    CounterAssetTypeParam:
      name: counter_asset_type
      in: query
      required: false
      description: The type for the counter asset. Either native, credit_alphanum4, or credit_alphanum12.
      schema:
        type: string
        enum:
        - native
        - credit_alphanum4
        - credit_alphanum12
    OfferIdParam:
      name: offer_id
      in: query
      required: false
      description: The offer ID. Used to filter for trades originating from a specific offer.
    CursorParam:
      name: cursor
      in: query
      required: false
      description: A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.
      schema:
        type: integer
        example: 6606617478959105
    TradeTypeParam:
      name: trade_type
      in: query
      required: false
      description: Can be set to all, orderbook, or liquidity_pools to filter only trades executed across a given mechanism.
      schema:
        type: string
        enum:
        - all
        - orderbook
        - liquidity_pools
    CounterAssetCodeParam:
      name: counter_asset_code
      in: query
      required: false
      description: The code for the counter asset. Required if the `counter_asset_type` is not `native`.
      schema:
        type: string
        example: USD
  schemas:
    Trade:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      base:
                        $ref: '#/components/schemas/link'
                      counter:
                        $ref: '#/components/schemas/link'
                      operation:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - base
                    - counter
                    - operation
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    $ref: '#/components/schemas/paging_token'
                  ledger_close_time:
                    type: string
                  offer_id:
                    type: string
                  trade_type:
                    type: string
                  liquidity_pool_fee_bp:
                    type: number
                    format: uint32
                  base_liquidity_pool_id:
                    type: string
                  base_offer_id:
                    type: string
                  base_account:
                    $ref: '#/components/schemas/address'
                  base_amount:
                    type: string
                  base_asset_type:
                    type: string
                  base_asset_code:
                    type: string
                  base_asset_issuer:
                    type: string
                  counter_liquidity_pool_id:
                    type: string
                  counter_offer_id:
                    type: string
                  counter_account:
                    $ref: '#/components/schemas/address'
                  counter_amount:
                    type: string
                  counter_asset_type:
                    type: string
                  counter_asset_code:
                    type: string
                  counter_asset_issuer:
                    $ref: '#/components/schemas/address'
                  base_is_seller:
                    type: boolean
                  price:
                    $ref: '#/components/schemas/tradePrice'
                    required:
                    - id
                    - paging_token
                    - ledger_close_time
                    - trade_type
                    - base_amount
                    - base_asset_type
                    - counter_amount
                    - counter_asset_type
                    - base_is_seller
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            next:
              $ref: '#/components/schemas/link'
            prev:
              $ref: '#/components/schemas/link'
    paging_token:
      type: string
    tradePrice:
      type: object
      properties:
        n:
          type: string
        d:
          type: string
    link:
      type: object
      properties:
        href:
          type: string
          format: link
        templated:
          type: boolean
      required:
      - href
    address:
      type: string
      pattern: G[A-Z0-9]{55}
    id:
      type: string
  examples:
    GetAllTrades:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/trades?base_asset_code=USD&base_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&base_asset_type=credit_alphanum4&counter_asset_type=native&cursor=&limit=3&order=asc
          next:
            href: https://horizon-testnet.stellar.org/trades?base_asset_code=USD&base_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&base_asset_type=credit_alphanum4&counter_asset_type=native&cursor=83056000260648961-0&limit=3&order=asc
          prev:
            href: https://horizon-testnet.stellar.org/trades?base_asset_code=USD&base_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&base_asset_type=credit_alphanum4&counter_asset_type=native&cursor=82854686553571330-0&limit=3&order=desc
        _embedded:
          records:
          - _links:
              self:
                href: ''
              base:
                href: https://horizon-testnet.stellar.org/accounts/GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
              counter:
                href: https://horizon-testnet.stellar.org/accounts/GBCHK52UXADCQCO7FBA5VBYPGCJFXHCNAVJTMUEKOCCNKJH5F35UZU5T
              operation:
                href: https://horizon-testnet.stellar.org/operations/82854686553571330
            id: 82854686553571330-0
            paging_token: 82854686553571330-0
            ledger_close_time: '2018-08-05T00:55:34Z'
            offer_id: '23074703'
            base_offer_id: '23074703'
            base_account: GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
            base_amount: '22.9174941'
            base_asset_type: credit_alphanum4
            base_asset_code: USD
            base_asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            counter_offer_id: '4694540704980959234'
            counter_account: GBCHK52UXADCQCO7FBA5VBYPGCJFXHCNAVJTMUEKOCCNKJH5F35UZU5T
            counter_amount: '97.9999800'
            counter_asset_type: native
            base_is_seller: true
            price:
              n: '106905209'
              d: '25000000'
          - _links:
              self:
                href: ''
              base:
                href: https://horizon-testnet.stellar.org/accounts/GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
              counter:
                href: https://horizon-testnet.stellar.org/accounts/GDURV3I6U5OTUV75WWAG2HWZTQHNMCR3NR2P5GPKDCIS2AEWCFSOLVFU
              operation:
                href: https://horizon-testnet.stellar.org/operations/83005225157287937
            id: 83005225157287937-0
            paging_token: 83005225157287937-0
            ledger_close_time: '2018-08-07T02:01:53Z'
            offer_id: '23400441'
            base_offer_id: '23400441'
            base_account: GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
            base_amount: '1.0000000'
            base_asset_type: credit_alphanum4
            base_asset_code: USD
            base_asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            counter_offer_id: '4694691243584675841'
            counter_account: GDURV3I6U5OTUV75WWAG2HWZTQHNMCR3NR2P5GPKDCIS2AEWCFSOLVFU
            counter_amount: '4.3080953'
            counter_asset_type: native
            base_is_seller: true
            price:
              n: '430809521'
              d: '100000000'
          - _links:
              self:
                href: ''
              base:
                href: https://horizon-testnet.stellar.org/accounts/GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
              counter:
                href: https://horizon-testnet.stellar.org/accounts/GBNDB4UHLDRBLR35JNU4ADYG3J5WA4LJZOPBXMNHZKTKSL37BDX4UBQY
              operation:
                href: https://horizon-testnet.stellar.org/operations/83056000260648961
            id: 83056000260648961-0
            paging_token: 83056000260648961-0
            ledger_close_time: '2018-08-07T18:27:33Z'
            offer_id: '23400441'
            base_offer_id: '23400441'
            base_account: GD47M25MLSCSYP4SIVNQXVQ4KWNLVGXS4S2AXPTYEJK6OY4VALJWK4BS
            base_amount: '1.0000000'
            base_asset_type: credit_alphanum4
            base_asset_code: USD
            base_asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            counter_offer_id: '4694742018688036865'
            counter_account: GBNDB4UHLDRBLR35JNU4ADYG3J5WA4LJZOPBXMNHZKTKSL37BDX4UBQY
            counter_amount: '4.3080953'
            counter_asset_type: native
            base_is_seller: true
            price:
              n: '430809521'
              d: '100000000'
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