> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onboard.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Best Offer

Automatically retrieves a single offer that best matches the user's trading parameters. This offer is optimized for factors such as merchant availability, competitive rates, and faster completion times, providing a seamless trading experience.


## OpenAPI

````yaml get /exchange/api/offers/best-offer
openapi: 3.0.3
info:
  version: 2.1.0
  title: Onboard External API Gateway
  description: >-
    **Introduction**

    API Gateway for Onboard


    This specification describes API endpoints that are available to the public
    internet via the API gateway. The different endpoints require different
    authentication schemes, see documentation for what applies to the operation
    you want to access.


    **Errors**

    Uses conventional HTTP response codes to indicate success or failure. In

    general:
     
    - `2xx` status codes indicate success. Codes in the

    - `4xx` range

    indicate a client error (e.g. required parameters, failed request etc.).

    - `5xx` status codes indicate a server error occurred.
  contact:
    name: Nestcoin TechOps
    email: techops@nestcoin.com
  license:
    name: UNLICENSED
servers:
  - url: https://external.dev.onboardpay.co
    description: Gateway for external API on staging environment.
security: []
tags:
  - name: users-onboardapi
    description: Endpoints available to for merchants liquidity automation
  - name: users-users
    description: User related endpoints
  - name: users-partners
    description: Partner related endpoints
  - name: users-admin
    description: Back office related endpoints
  - name: users-user2fa
    description: User 2fa related endpoints
  - name: users-usernotifications
    description: User notifications related endpoints
  - name: users-merchantnetwork
    description: Merchant network endpoints
  - name: users-userauth
    description: Authentication endpoints
  - name: users-userservice
    description: Service endpoints
  - name: users-webhook
    description: webhook endpoints
paths:
  /exchange/api/offers/best-offer:
    get:
      tags:
        - exchange-external-api
      summary: Get best offer using trade parameters
      operationId: getBestOfferExchange
      parameters:
        - $ref: '#/components/parameters/ExchangeSvcofferTypeQueryParam'
        - $ref: '#/components/parameters/ExchangeSvctokenQueryParam'
        - $ref: '#/components/parameters/ExchangeSvcfiatQueryParam'
        - $ref: '#/components/parameters/ExchangeSvctokenAmountQueryParam'
        - $ref: '#/components/parameters/ExchangeSvcfiatAmountQueryParam'
        - $ref: '#/components/parameters/ExchangeSvcnetworkQueryParam'
        - $ref: '#/components/parameters/ExchangeSvcpaymentChannelQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  offer:
                    $ref: '#/components/schemas/BestOfferDTO'
                  orderRequestTradeId:
                    type: string
                required:
                  - offer
                  - orderRequestTradeId
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessageDto'
      security: []
components:
  parameters:
    ExchangeSvcofferTypeQueryParam:
      name: offerType
      in: query
      schema:
        $ref: '#/components/schemas/OfferTypeQueryParamOfferTypeEnum'
    ExchangeSvctokenQueryParam:
      name: token
      in: query
      schema:
        type: string
    ExchangeSvcfiatQueryParam:
      name: fiat
      in: query
      schema:
        type: string
    ExchangeSvctokenAmountQueryParam:
      name: tokenAmount
      in: query
      schema:
        type: number
    ExchangeSvcfiatAmountQueryParam:
      name: fiatAmount
      in: query
      schema:
        type: number
    ExchangeSvcnetworkQueryParam:
      name: networkId
      in: query
      description: >-
        Onboard blockchain network identifier or chain Id e.g Base will be
        `base` or `8453` or `0x2105`
      schema:
        type: string
    ExchangeSvcpaymentChannelQueryParam:
      name: paymentChannel
      in: query
      schema:
        type: string
  schemas:
    BestOfferDTO:
      type: object
      properties:
        offer:
          $ref: '#/components/schemas/OfferDto'
        orderRequestTradeId:
          type: string
      required:
        - offer
        - orderRequestTradeId
    ErrorMessageDto:
      description: >-
        Default error object for services. This gives consistent error object
        that all services may use.
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          example: UNKNOWN_ERROR
        message:
          type: string
          description: Descriptive error message
          example: Request could not be completed due to an error
        data:
          type: object
          description: Additional data for this error message.
          additionalProperties: true
          properties: {}
      x-common-model: ErrorMessageDto
    OfferTypeQueryParamOfferTypeEnum:
      type: string
      enum:
        - ONRAMP
        - OFFRAMP
    OfferDto:
      type: object
      properties:
        offerId:
          type: string
          description: external offer id
        userId:
          type: string
          description: userId of the merchant that created offer
        network:
          type: string
          description: id of network on which the asset is on
        tokenSymbol:
          type: string
          description: symbol of token been sold or bought
          example: BNB
        fiatSymbol:
          type: string
          description: ISO 4217 code for fiat currency
          example: USD, NGN
        offerType:
          $ref: '#/components/schemas/OfferType'
        behaviour:
          $ref: '#/components/schemas/OfferBehavior'
        totalUnit:
          type: number
          description: offer total unit in fiat
          example: 5000
        tradedUnit:
          type: number
          description: units that has been traded out of the total unit
          example: 5000
        lockedUnit:
          type: number
          description: units that has been locked out of the offer total unit
          example: 5000
        rate:
          type: number
          description: price rate to buy or sell
          example: 500
        rateCap:
          type: number
          description: >-
            The minimum (for onramp) or maximum (for offramp) rate allowed for
            this ad if it's a flexible ad
          example: 500
        paymentMethods:
          type: array
          items:
            $ref: '#/components/schemas/OfferPaymentMethod'
        paymentChannels:
          type: array
          items:
            $ref: '#/components/schemas/OfferPaymentChannel'
        flexibleOfferMargin:
          type: number
          description: offer margin in percentage allowed for flexible offers
          example: 10
        status:
          $ref: '#/components/schemas/OfferStatus'
        partnerDisplayName:
          type: string
          description: Partner's display name
        partnerRating:
          type: number
          example: -1
        partnerStats:
          $ref: '#/components/schemas/PartnerStats'
        statusReason:
          type: string
          description: >-
            the reason for the current status - mostly applied to non active or
            offline status
        tradeMinimumLimit:
          type: number
          description: minimum trade limit
        tradeMaximumLimit:
          type: number
          description: maximum trade limit
        previewImageUrl:
          type: string
          description: preview image url
        maxTimeout:
          type: object
          properties:
            deposit:
              type: integer
              description: timeout for buyer to pay in seconds
              example: 1440
            confirmation:
              type: integer
              description: timeout for seller to confirm in seconds
              example: 600
        feeConfig:
          $ref: '#/components/schemas/FeeConfig'
        feeConfigs:
          type: array
          items:
            $ref: '#/components/schemas/FeeConfig'
        tradeCriteria:
          $ref: '#/components/schemas/TradeCriteria'
        autoResponseMessage:
          type: string
          description: auto response message to be shown to customers
        adNote:
          type: string
          description: note to be shown to the customer
        tradeRequestBroadcastId:
          type: string
          description: trade request broadcast id
        isPrivate:
          type: boolean
          description: >-
            Indicates if an ad should be hidden from the public and treated as a
            private ad.
        isRateHidden:
          type: boolean
          description: Indicates if rate is hidden
        instantPayEnabled:
          type: boolean
          description: Is instant pay enabled for offer
          default: false
        instantPayLimit:
          type: number
          description: Max tradeable by instant pay on this add. (In fiat value)
        instantPayMinimum:
          type: number
          description: minimum tradeable by instant pay on this add. (In fiat value)
        instantPayAccountId:
          type: string
          description: Account id of instantpay. Useful especially for onramp payins
        customPayinProvider:
          type: string
          description: Provider for custom payin (ONRAMP only)
        latestCounterOffer:
          $ref: '#/components/schemas/CounterOfferDto'
        createdAt:
          type: string
          format: date-time
          description: Timestamp field.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp field.
        editedAt:
          type: string
          format: date-time
          description: Timestamp field.
        partnerLastActiveAt:
          type: string
          format: date-time
          description: Timestamp field.
        primaryEscrowAddress:
          type: string
        fiatTradeMinimumLimit:
          type: number
        fiatTradeMaximumLimit:
          type: number
        maxFiatLimit:
          type: number
          description: Maximum fiat limit consideration available units
        availableUnits:
          type: number
          description: >-
            Calculated available units when locked  and traded units are
            deducted
        fulfillOrderAs:
          $ref: '#/components/schemas/FulfillOrderAs'
        autoRefillEnabled:
          type: boolean
          description: Flag indicating if auto refill is enabled for this ad
        autoRefillConfig:
          $ref: '#/components/schemas/AutoRefillConfig'
      required:
        - offerId
        - userId
        - network
        - tokenSymbol
        - fiatSymbol
        - offerType
        - behaviour
        - totalUnit
        - tradedUnit
        - lockedUnit
        - rate
        - paymentMethods
        - status
        - availableUnits
        - maxFiatLimit
        - tradeMinimumLimit
        - tradeMaximumLimit
        - createdAt
        - updatedAt
        - editedAt
        - partnerDisplayName
        - partnerRating
        - partnerLastActiveAt
    OfferType:
      type: string
      enum:
        - ONRAMP
        - OFFRAMP
    OfferBehavior:
      type: string
      description: Offer rate behavior
      enum:
        - FIXED
        - FLEXIBLE
    OfferPaymentMethod:
      type: object
      allOf:
        - $ref: '#/components/schemas/OfferPaymentChannel'
        - type: object
          properties:
            id:
              type: string
    OfferPaymentChannel:
      type: object
      properties:
        channelId:
          type: string
        channelName:
          type: string
        channelType:
          type: string
        color:
          $ref: '#/components/schemas/OfferPaymentChannelColor'
    OfferStatus:
      type: string
      description: the current offer status
      default: ACTIVE
      enum:
        - PENDING
        - ACTIVE
        - OFFLINE
        - LOW_BALANCE
        - LIMIT_REACHED
    PartnerStats:
      type: object
      properties:
        partnerId:
          type: string
          format: uuid
        averageRating:
          type: number
          example: 3
        totalTransactions:
          type: number
        tradeCount:
          type: number
        completionPercentage:
          type: number
          format: double
          example: 94
        averageResponseTime:
          type: number
          format: double
          example: 5
    FeeConfig:
      type: object
      properties:
        tradeType:
          $ref: '#/components/schemas/OfferType'
        tradeMode:
          $ref: '#/components/schemas/TradeMode'
        base:
          type: number
          description: Flat fee that must be paid for irrespective of percentage fee
        tradePercentage:
          type: number
          description: Fee described as a percentage of the trade
        cap:
          type: number
          description: Maximum value a fee is allowed to have
        network:
          type: string
          description: >
            The network this config should be applied to(There will always be at
            least

            one fee config, that config will have network value of `default`
      required:
        - base
        - tradePercentage
        - network
    TradeCriteria:
      type: object
      properties:
        verifiedKyc:
          type: boolean
    CounterOfferDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        offerId:
          type: string
          format: uuid
          description: related offer id
        userId:
          type: string
          format: uuid
          description: userId of user that created counter offer
        otherUserId:
          type: string
          format: uuid
          description: userId of other user on the created counter offer
        rate:
          type: number
          description: proposed rate
          example: 500
        previousCounterRate:
          type: number
          description: previous proposed rate
          example: 500
        previousCounterId:
          type: string
          description: id of previous counter offer
        status:
          $ref: '#/components/schemas/CounterOfferStatus'
        statusReason:
          type: string
          description: the reason for the current status
        message:
          type: string
          description: additional message
        tradeRequestBroadcastId:
          type: string
          format: uuid
          description: trade request broadcast id
        createdAt:
          type: string
          format: date-time
          description: Timestamp field.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp field.
        deletedAt:
          type: string
          format: date-time
          description: Timestamp field.
    FulfillOrderAs:
      type: string
      enum:
        - BUSINESS
        - PERSONAL
    AutoRefillConfig:
      type: object
      required:
        - threshold
        - amount
      properties:
        threshold:
          type: number
          description: >-
            If ad available unit go belows this value the system would trigger a
            auto refill
        amount:
          type: number
          description: The token amount to refill the ad with
    OfferPaymentChannelColor:
      type: object
      properties:
        bg:
          type: string
        fg:
          type: string
      required:
        - bg
        - fg
    TradeMode:
      type: string
      enum:
        - P2P
        - IP
        - OTC
    CounterOfferStatus:
      type: string
      description: counter offer status
      enum:
        - PENDING
        - ACCEPTED
        - REJECTED

````