Stellar Offers API

openapi: 3.2.0
info:
  title: Horizon Offers 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.
  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: Offers
  description: Offers are statements about how much of an asset an account wants to buy or sell.
paths:
  /offers:
    get:
      tags:
      - Offers
      summary: List All Offers
      description: This endpoint lists all currently open offers and can be used in streaming mode. Streaming mode allows you to listen for new offers as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known offer unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream offers created since your request time. When filtering by buying or selling arguments, you must use a combination of selling_asset_type, selling_asset_issuer, and selling_asset_code for the selling asset, or a combination of buying_asset_type, buying_asset_issuer, and buying_asset_code for the buying asset.
      operationId: GetAllOffers
      parameters:
      - $ref: '#/components/parameters/SponsorParam'
      - $ref: '#/components/parameters/SellerParam'
      - $ref: '#/components/parameters/SellingAssetTypeParam'
      - $ref: '#/components/parameters/SellingAssetIssuerParam'
      - $ref: '#/components/parameters/SellingAssetCodeParam'
      - $ref: '#/components/parameters/BuyingAssetTypeParam'
      - $ref: '#/components/parameters/BuyingAssetIssuerParam'
      - $ref: '#/components/parameters/BuyingAssetCodeParam'
      - $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/Offer'
              examples:
                GetAllOffers:
                  $ref: '#/components/examples/GetAllOffers'
  /offers/{offer_id}:
    get:
      tags:
      - Offers
      summary: Retrieve an Offer
      description: The single offer endpoint provides information on a specific offer.
      operationId: GetOfferByOfferId
      parameters:
      - $ref: '#/components/parameters/OfferIDParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/Offer'
              examples:
                GetOfferByOfferId:
                  $ref: '#/components/examples/GetOfferByOfferId'
  /offers/{offer_id}/trades:
    get:
      tags:
      - Offers
      summary: Retrieve an Offer's Trades
      description: This endpoint represents all trades for a given offer and can be used in streaming mode. Streaming mode allows you to listen for trades for this offer 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.
      operationId: GetTradesByOfferId
      parameters:
      - $ref: '#/components/parameters/OfferIDParam'
      - $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:
                GetTradesByOfferId:
                  $ref: '#/components/examples/GetTradesByOfferId'
components:
  schemas:
    BaseAsset:
      type: object
      properties:
        asset_type:
          type: string
        asset_code:
          type: string
        asset_issuer:
          type: string
      required:
      - asset_type
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            next:
              $ref: '#/components/schemas/link'
            prev:
              $ref: '#/components/schemas/link'
    last_modified_ledger:
      type: integer
      format: uint32
    link:
      type: object
      properties:
        href:
          type: string
          format: link
        templated:
          type: boolean
      required:
      - href
    paging_token:
      type: string
    Offer:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      offer_maker:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - offer_maker
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    type: string
                  seller:
                    $ref: '#/components/schemas/address'
                  selling:
                    $ref: '#/components/schemas/BaseAsset'
                  buying:
                    $ref: '#/components/schemas/BaseAsset'
                  amount:
                    type: string
                  price_r:
                    $ref: '#/components/schemas/Price'
                  price:
                    type: string
                  last_modified_ledger:
                    $ref: '#/components/schemas/last_modified_ledger'
                  last_modified_time:
                    type: string
                  sponser:
                    type: string
                required:
                - id
                - paging_token
                - seller
                - selling
                - buying
                - amount
                - price_r
                - price
                - last_modified_ledger
                - last_modified_time
    Price:
      type: object
      properties:
        n:
          type: integer
          format: int32
        d:
          type: integer
          format: int32
    address:
      type: string
      pattern: G[A-Z0-9]{55}
    id:
      type: string
    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
    tradePrice:
      type: object
      properties:
        n:
          type: string
        d:
          type: string
  parameters:
    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
    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
    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
    SellerParam:
      name: seller
      in: query
      required: false
      description: The account ID of the offer creator.
    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
    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
    SponsorParam:
      name: sponser
      in: query
      required: false
      description: Account ID of the sponsor. Every account in the response will either be sponsored by the given account ID or have a subentry (trustline, offer, or data entry) which is sponsored by the given account ID.
      schema:
        type: string
        example: GDMQQNJM4UL7QIA66P7R2PZHMQINWZBM77BEBMHLFXD5JEUAHGJ7R4JZ
    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
    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
    OfferIDParam:
      name: offer_id
      in: path
      required: true
      description: A unique identifier for this offer.
    SellingAssetTypeParam:
      name: selling_asset_type
      in: query
      required: false
      description: The type for the selling 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
  examples:
    GetAllOffers:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/offers?cursor=&limit=3&order=asc&selling_asset_code=USD&selling_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&selling_asset_type=credit_alphanum4
          next:
            href: https://horizon-testnet.stellar.org/offers?cursor=88345152&limit=3&order=asc&selling_asset_code=USD&selling_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&selling_asset_type=credit_alphanum4
          prev:
            href: https://horizon-testnet.stellar.org/offers?cursor=71673427&limit=3&order=desc&selling_asset_code=USD&selling_asset_issuer=GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX&selling_asset_type=credit_alphanum4
        _embedded:
          records:
          - _links:
              self:
                href: https://horizon-testnet.stellar.org/offers/71673427
              offer_maker:
                href: https://horizon-testnet.stellar.org/accounts/GBJPWEIFX6KO4H52BF3QJDYRCLXB2P3Z3QTKWUGFOOFH5MSRZV4WLRZ7
            id: 71673427
            paging_token: '71673427'
            seller: GBJPWEIFX6KO4H52BF3QJDYRCLXB2P3Z3QTKWUGFOOFH5MSRZV4WLRZ7
            selling:
              asset_type: credit_alphanum4
              asset_code: USD
              asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            buying:
              asset_type: credit_alphanum4
              asset_code: BTC
              asset_issuer: GAUTUYY2THLF7SGITDFMXJVYH3LHDSMGEAKSBU267M2K7A3W543CKUEF
            amount: '25.6545775'
            price_r:
              n: 289696073
              d: 25654776
            price: '11.2920913'
            last_modified_ledger: 26981646
            last_modified_time: '2019-11-26T13:42:10Z'
          - _links:
              self:
                href: https://horizon-testnet.stellar.org/offers/88328208
              offer_maker:
                href: https://horizon-testnet.stellar.org/accounts/GBSYMLHG5TGQ4O3NSPIO4DSCS4AC6YRJOQWQC3EW7O257RAUHI5SA45R
            id: 88328208
            paging_token: '88328208'
            seller: GBSYMLHG5TGQ4O3NSPIO4DSCS4AC6YRJOQWQC3EW7O257RAUHI5SA45R
            selling:
              asset_type: credit_alphanum4
              asset_code: USD
              asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            buying:
              asset_type: credit_alphanum4
              asset_code: BTC
              asset_issuer: GBVOL67TMUQBGL4TZYNMY3ZQ5WGQYFPFD5VJRWXR72VA33VFNL225PL5
            amount: '2.4664893'
            price_r:
              n: 500
              d: 1233
            price: '0.4055150'
            last_modified_ledger: 23886660
            last_modified_time: '2019-05-17T00:33:16Z'
          - _links:
              self:
                href: https://horizon-testnet.stellar.org/offers/88345152
              offer_maker:
                href: https://horizon-testnet.stellar.org/accounts/GACTQP5TAWIXF2LV4GWGJWIUNHKDWZ2ITCFDP37FIGOFPR3ORMQRR63U
            id: 88345152
            paging_token: '88345152'
            seller: GACTQP5TAWIXF2LV4GWGJWIUNHKDWZ2ITCFDP37FIGOFPR3ORMQRR63U
            selling:
              asset_type: credit_alphanum4
              asset_code: USD
              asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
            buying:
              asset_type: credit_alphanum4
              asset_code: USD
              asset_issuer: GBUYUAI75XXWDZEKLY66CFYKQPET5JR4EENXZBUZ3YXZ7DS56Z4OKOFU
            amount: '10.0000000'
            price_r:
              n: 11
              d: 10
            price: '1.1000000'
            last_modified_ledger: 23887778
            last_modified_time: '2019-05-17T02:19:19Z'
    GetOfferByOfferId:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/offers/165563085
          offer_maker:
            href: https://horizon-testnet.stellar.org/accounts/GCM4PT6XDZBWOOENDS6FOU22GJQLJPV2GC7VRVII4TFGZBA3ZXNM55SV
        id: 165563085
        paging_token: '165563085'
        seller: GCM4PT6XDZBWOOENDS6FOU22GJQLJPV2GC7VRVII4TFGZBA3ZXNM55SV
        selling:
          asset_type: credit_alphanum4
          asset_code: USD
          asset_issuer: GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX
        buying:
          asset_type: native
        amount: '26.1075388'
        price_r:
          n: 1449156725
          d: 84642346
        price: '17.1209423'
        last_modified_ledger: 28412042
        last_modified_time: null
    GetTradesByOfferId:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/offers/104078276/trades?cursor=&limit=3&order=asc
          next:
            href: https://horizon-testnet.stellar.org/offers/104078276/trades?cursor=107449584845914113-0&limit=3&order=asc
          prev:
            href: https://horizon-testnet.stellar.org/offers/104078276/trades?cursor=107449468881756161-0&limit=3&order=desc
        _embedded:
          records:
          - _links:
              self:
                href: ''
              base:
                href: https://horizon-testnet.stellar.org/accounts/GCO7OW5P2PP7WDN6YUDXUUOPAR4ZHJSDDCZTIAQRTRZHKQWV45WUPBWX
              counter:
                href: https://horizon-testnet.stellar.org/accounts/GD3CJYUTZAY6JQF4CEI6Z7VW5O6VNGKZTBYUECTOJPEDTB7I2HZSPI2K
              operation:
                href: https://horizon-testnet.stellar.org/operations/107449468881756161
            id: 107449468881756161-0
            paging_token: 107449468881756161-0
            ledger_close_time: '2019-07-26T09:17:02Z'
            offer_id: '104078276'
            base_offer_id: '104078276'
            base_account: GCO7OW5P2PP7WDN6YUDXUUOPAR4ZHJSDDCZTIAQRTRZHKQWV45WUPBWX
            base_amount: '4433.2000000'
            base_asset_type: native
            counter_offer_id: '4719135487309144065'
            counter_account: GD3CJYUTZAY6JQF4CEI6Z7VW5O6VNGKZTBYUECTOJPEDTB7I2HZSPI2K
            counter_amount: '443.3200000'
            counter_asset_type: credit_alphanum4
            counter_asset_code: BB1
            counter_asset_issuer: GD5J6HLF5666X4AZLTFTXLY46J5SW7EXRKBLEYPJP33S33MXZGV6CWFN
            base_is_seller: true
            price:
              n: 1
              d: 10
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