openapi: 3.1.0
info:
  title: X2Y2 Fi Chain Orders API
  version: '3.0'
servers:
- url: https://loan-api.x2y2.org/
- url: https://goerli-loan-api.x2y2.org/
security:
- sec0: []
tags:
- name: Orders
paths:
  /v1/orders:
    get:
      summary: Fetch open orders
      operationId: get-v1-orders
      security:
      - ApiKeyAuth: []
      tags:
      - Orders
      parameters:
      - in: query
        name: maker
        description: Filter by the order maker's wallet address
        schema:
          type: string
        required: false
      - in: query
        name: contract
        description: Filter by contract address
        schema:
          type: string
        required: false
      - in: query
        name: token_id
        description: Filter by the token ID of contract. Needs to be sent together with `contract`.
        schema:
          type: integer
        required: false
      - in: query
        name: created_before
        description: Filter orders listed before this timestamp.
        schema:
          type: string
        required: false
      - in: query
        name: created_after
        description: Filter orders listed after this timestamp.
        schema:
          type: string
        required: false
      - in: query
        name: cursor
        description: A cursor to be supplied as a query param to retrieve the next page.
        schema:
          type: string
        required: false
      - in: query
        name: sort
        description: The property to sort the results by.
        schema:
          type: string
          enum:
          - created_at
          - price
        required: false
      - in: query
        name: limit
        description: Number of orders to return (capped at 50).
        schema:
          type: integer
        required: false
      - in: query
        name: direction
        description: The order to sort by.
        schema:
          type: string
          enum:
          - asc
          - desc
        required: false
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
  /orders/add:
    post:
      summary: Create open order
      description: Create a new open order, including new listings, price changes, and collection offers.
      operationId: create-open-order
      tags:
      - Orders
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - order
              - isBundle
              - orderIds
              - changePrice
              - isCollection
              properties:
                order:
                  type: string
                  description: An order payload that contains the order info.
                isBundle:
                  type: boolean
                  description: Must be false.
                  default: false
                orderIds:
                  type: array
                  description: Empty array for new listing. OrderId of the current order when changing its price.
                  items:
                    type: integer
                    format: int32
                changePrice:
                  type: boolean
                  description: Set to true only when changing the price of an existing listing.
                  default: false
                isCollection:
                  type: boolean
                  description: Set to true only when creating a new collection offer.
                  default: false
                isPrivate:
                  type: boolean
                  description: Set to true to create a private listing. Must be used together with `taker`.
                  default: false
                taker:
                  type: string
                  description: 'Must be used with isPrivate: true. Specifies who could buy the private listing.'
                  default: 'null'
      responses:
        '200':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: {}
  /orders/sign:
    post:
      summary: Fetch order purchase input
      description: Get the input to be submitted via user's wallet to purchase or accept an offer.
      operationId: sign-order-info
      tags:
      - Orders
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - caller
              - op
              - amountToEth
              - amountToWeth
              - items
              properties:
                caller:
                  type: string
                  description: Caller's address.
                op:
                  type: integer
                  description: 1 for purchase a listing, 2 for accept an offer.
                  default: 1
                  format: int32
                amountToEth:
                  type: string
                  description: Must be '0'.
                  default: '0'
                amountToWeth:
                  type: string
                  description: Must be '0'.
                  default: '0'
                items:
                  type: array
                  description: Info of the orders to be purchased.
                  items:
                    type: object
                    required:
                    - orderId
                    - currency
                    - price
                    properties:
                      orderId:
                        type: integer
                        format: int32
                      currency:
                        type: string
                      price:
                        type: string
                      tokenId:
                        type: string
                        description: Required when accepting collection offer.
                check:
                  type: boolean
                  description: Whether to check if owners of items are approved for x2y2 contract.
                  default: true
      responses:
        '200':
          description: Purchase input returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        order_id:
                          type: integer
                          example: 1
                          default: 0
                        input:
                          type: string
                          example: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: {}
  /orders/cancel:
    post:
      summary: Fetch order cancel input
      description: Get the input to be submitted via user's wallet to cancel orders on chain.
      operationId: sign-cancel-order
      tags:
      - Orders
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - caller
              - op
              - items
              - sign_message
              - sign
              properties:
                caller:
                  type: string
                  description: Order maker's address.
                op:
                  type: integer
                  description: Must be 3 to cancel any order.
                  default: 3
                  format: int32
                items:
                  type: array
                  description: Id of orders to cancel.
                  items:
                    type: object
                    properties:
                      orderId:
                        type: integer
                        format: int32
                sign_message:
                  type: string
                  description: A random string generated by ethers.utils.keccak256().
                sign:
                  type: string
                  description: Signed by user's wallet, from `[signMessage, userAddress]`.
      responses:
        '200':
          description: Cancel input returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        order_id:
                          type: integer
                          example: 1
                          default: 0
                        input:
                          type: string
                          example: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: {}
components:
  schemas:
    TokenLite:
      type: object
      properties:
        contract:
          type: string
          default: '0xef1a89cbfabe59397ffda11fc5df293e9bc5db90'
          nullable: false
        token_id:
          type: integer
          default: 1
          nullable: false
        erc_type:
          type: string
          default: erc721
          enum:
          - erc721
          - erc1155
          nullable: false
    OrderResponse:
      type: object
      properties:
        success:
          type: boolean
          default: true
        next:
          type: string
          default: null
        data:
          type: array
          items:
            $ref: '#/components/schemas/Order'
      required:
      - success
    Order:
      type: object
      properties:
        id:
          type: integer
          default: 1
        item_hash:
          type: string
          default: '0x41a2753400f805db148079f60355df470aece45941a45cb96a25ab5d24e4c243'
        maker:
          type: string
          default: '0x40415c1c0e7a8ff3e184b51a94a2fc5b92df9434'
        taker:
          type: string
          default: null
        token:
          $ref: '#/components/schemas/TokenLite'
        price:
          type: string
          default: '48700000000000000'
        currency:
          type: string
          default: '0x0000000000000000000000000000000000000000'
        type:
          type: string
          default: sell
        is_collection_offer:
          type: string
          default: false
        royalty_fee:
          type: integer
          default: 0
          description: Base rate is 10^6. For example, 50000 means 5%
        created_at:
          type: string
          default: 1654983000
        end_at:
          type: string
          default: 1654999000
      required:
      - type
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: X-API-KEY