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

# Create a new gateway order.

> Creates a new request, reserves the required liquidity.



## OpenAPI

````yaml /api-reference/openapi.json post /v2/create-order
openapi: 3.1.0
info:
  title: BOB Gateway API
  description: BOB Gateway API for Bitcoin swaps
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://gateway-api-mainnet.gobob.xyz
    description: Production
  - url: https://gateway-api-staging.gobob.xyz
    description: Staging
security: []
tags:
  - name: v1
    description: BOB Gateway Core API (v1)
  - name: v2
    description: BOB Gateway Core API (v2)
  - name: v3
    description: BOB Gateway Core API (v3)
paths:
  /v2/create-order:
    post:
      tags:
        - v2
      summary: Create a new gateway order.
      description: Creates a new request, reserves the required liquidity.
      operationId: create_order_v2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayQuoteV2'
        required: true
      responses:
        '201':
          description: Created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayCreateOrderV2'
        '400':
          description: Create order error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorV2'
components:
  schemas:
    GatewayQuoteV2:
      oneOf:
        - type: object
          required:
            - onramp
          properties:
            onramp:
              $ref: '#/components/schemas/GatewayOnrampQuoteV2'
        - type: object
          required:
            - offramp
          properties:
            offramp:
              $ref: '#/components/schemas/GatewayOfframpQuoteV2'
        - type: object
          required:
            - tokenSwap
          properties:
            tokenSwap:
              $ref: '#/components/schemas/GatewayTokenSwapQuoteV2'
      description: Gateway quote.
    GatewayCreateOrderV2:
      oneOf:
        - type: object
          required:
            - onramp
          properties:
            onramp:
              type: object
              required:
                - order_id
                - address
              properties:
                address:
                  type: string
                  description: Bitcoin address to pay to
                op_return_data:
                  type:
                    - string
                    - 'null'
                  description: Optional OP_RETURN data
                order_id:
                  type: string
                  description: Unique order id
                  example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                psbt_hex:
                  type:
                    - string
                    - 'null'
                  description: >-
                    Hex-encoded Bitcoin PSBT (only present when sender address
                    was provided)
        - type: object
          required:
            - offramp
          properties:
            offramp:
              type: object
              required:
                - order_id
                - tx
              properties:
                order_id:
                  type: string
                  description: Unique order id
                  example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                tx:
                  $ref: '#/components/schemas/TxInfo'
                  description: Tx info to execute the swap
        - type: object
          required:
            - tokenSwap
          properties:
            tokenSwap:
              type: object
              required:
                - order_id
                - tx
              properties:
                order_id:
                  type: string
                  description: Unique order id
                  example: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
                tx:
                  $ref: '#/components/schemas/TxInfo'
                  description: Tx info to execute the swap
      description: V2 create-order response
    GatewayErrorV2:
      type: object
      description: >-
        Structured error response for V2 API.

        Contains an error code, human-readable message, and optional structured
        details.
      required:
        - code
        - error
      properties:
        code:
          $ref: '#/components/schemas/GatewayErrorCodeV2'
          description: Stable error code for frontend parsing
        details:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/GatewayErrorDetailsV2'
              description: Optional structured details specific to the error type
        error:
          type: string
          description: Human-readable error message
    GatewayOnrampQuoteV2:
      type: object
      description: >-
        V2 onramp quote: identical to V1 plus a resolved `affiliates` list. Kept
        as

        a separate type so the V1 OpenAPI schema stays frozen.
      required:
        - inputAmount
        - outputAmount
        - fees
        - executionFees
        - recipient
        - token
        - slippage
        - feeBreakdown
        - dstChain
        - dstToken
        - signedQuoteData
      properties:
        affiliateAddress:
          type:
            - string
            - 'null'
          description: >-
            Affiliate address (V1-compatible field; first entry from
            `affiliates`).
        affiliates:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedAffiliate'
          description: Resolved affiliate recipients and computed fees.
        dstChain:
          type: string
          description: Destination chain
        dstToken:
          type: string
          description: Destination token address
        estimatedTimeInSecs:
          type:
            - integer
            - 'null'
          format: int64
          description: Estimated time in secs to complete the Order
          minimum: 0
        executionFees:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
          description: Cost to execute the onramp on-chain
        feeBreakdown:
          $ref: '#/components/schemas/GatewayOnrampFeeBreakdownV2'
          description: Detailed fee breakdown
        fees:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
          description: Total fees for this swap
        gasRefill:
          type:
            - string
            - 'null'
          description: Optional gas refill amount
        inputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
          description: Amount requested by the user
        outputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
          description: Final amount after fees
        priceImpact:
          type:
            - string
            - 'null'
          description: >-
            Price impact as a fraction, e.g. `"-0.05"` means 5% loss. Absent if
            no price feed is

            available.
        priceImpactUsd:
          type:
            - string
            - 'null'
          description: >-
            Price impact in USD, excluding execution fee. E.g. `"-1.00"` means
            $1 loss. Absent if no

            price feed is available.
        recipient:
          type: string
          description: Recipient address
        sender:
          type:
            - string
            - 'null'
          description: Sender address
        signedQuoteData:
          type: string
          description: The signed quote data to be used in create-order
        slippage:
          type: string
          description: Slippage tolerance
        strategyAddress:
          type:
            - string
            - 'null'
        strategyMessage:
          type:
            - string
            - 'null'
        token:
          type: string
          description: Token address
    GatewayOfframpQuoteV2:
      type: object
      required:
        - srcChain
        - tokenAddress
        - inputAmount
        - outputAmount
        - totalFeeUsd
        - feeBreakdown
        - recipient
        - slippage
        - txTo
      properties:
        affiliateAddress:
          type:
            - string
            - 'null'
          description: >-
            Affiliate address (V1-compatible field; first entry from
            `affiliates`).
        affiliates:
          type: array
          items:
            $ref: '#/components/schemas/ResolvedAffiliate'
          description: Resolved affiliate recipients and computed fees (V2).
        estimatedTimeInSecs:
          type:
            - integer
            - 'null'
          format: int64
          description: Estimated time in secs to complete the Order
          minimum: 0
        feeBreakdown:
          $ref: '#/components/schemas/GatewayOfframpFeeBreakdownV2'
        inputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        outputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        priceImpact:
          type:
            - string
            - 'null'
          description: >-
            Price impact as a fraction, e.g. `"-0.05"` means 5% loss. Absent if
            no price feed is

            available.
        priceImpactUsd:
          type:
            - string
            - 'null'
          description: >-
            Price impact in USD, excluding execution fee. E.g. `"-1.00"` means
            $1 loss. Absent if no

            price feed is available.
        recipient:
          type: string
        sender:
          type:
            - string
            - 'null'
        slippage:
          type: integer
          format: int32
          minimum: 0
        srcChain:
          type: string
        tokenAddress:
          type: string
        totalFeeUsd:
          type: string
        txTo:
          type: string
    GatewayTokenSwapQuoteV2:
      type: object
      required:
        - srcChain
        - dstChain
        - inputAmount
        - outputAmount
        - estimatedTimeInSecs
        - recipient
        - slippage
        - fees
        - txTo
      properties:
        dstChain:
          type: string
        estimatedTimeInSecs:
          type: integer
          format: int64
          description: Estimated time in secs to complete the Order
          minimum: 0
        fees:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        inputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        outputAmount:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        priceImpact:
          type:
            - string
            - 'null'
          description: >-
            Price impact as a fraction, e.g. `"-0.05"` means 5% loss. Absent if
            no price feed is

            available.
        priceImpactUsd:
          type:
            - string
            - 'null'
          description: >-
            Price impact in USD, excluding execution fee. E.g. `"-1.00"` means
            $1 loss. Absent if no

            price feed is available.
        recipient:
          type: string
        sender:
          type:
            - string
            - 'null'
        slippage:
          type: integer
          format: int32
          minimum: 0
        srcChain:
          type: string
        txTo:
          type: string
    TxInfo:
      type: object
      required:
        - to
        - data
        - value
        - chain
      properties:
        chain:
          type: string
        data:
          type: string
        to:
          type: string
        value:
          type: string
    GatewayErrorCodeV2:
      oneOf:
        - $ref: '#/components/schemas/GatewayErrorCode'
        - $ref: '#/components/schemas/GatewayErrorCodeV2Variants'
      description: Error codes for V2 API - includes all V1 codes plus new ones.
    GatewayErrorDetailsV2:
      oneOf:
        - type: object
          required:
            - expected
            - actual
          properties:
            actual:
              type: string
            expected:
              type: string
        - type: object
          required:
            - required
            - available
          properties:
            available:
              type: string
            required:
              type: string
        - type: object
          required:
            - total_fees
            - available_amount
          properties:
            available_amount:
              type: string
            total_fees:
              type: string
        - type: object
          properties:
            tenderly_url:
              type:
                - string
                - 'null'
        - type: object
          required:
            - src_chain
            - src_token
            - dst_chain
            - dst_token
          properties:
            dst_chain:
              type: string
            dst_token:
              type: string
            src_chain:
              type: string
            src_token:
              type: string
        - type: object
          required:
            - limit
          properties:
            limit:
              type: string
        - type: 'null'
          default: null
        - type: object
          required:
            - minimum
            - actual
          properties:
            actual:
              type: string
            minimum:
              type: string
        - type: object
          required:
            - limit
            - token
            - chain_id
          properties:
            chain_id:
              type: string
            limit:
              type: string
            token:
              type: string
        - type: object
          required:
            - src_chain
            - src_token
            - dst_chain
            - dst_token
          properties:
            dst_chain:
              type: string
            dst_token:
              type: string
            src_chain:
              type: string
            src_token:
              type: string
        - type: object
          required:
            - message
          properties:
            message:
              type: string
      description: >-
        Structured details for V2 error types - all V1 variants plus V2-only
        ones.


        Kept as a single flat `oneOf` (not nested under V1/V2 wrappers) so
        OpenAPI clients

        (e.g. typescript-fetch) can generate type guards correctly.
    ResolvedAffiliate:
      type: object
      description: >-
        Resolved affiliate returned in V2 responses. Includes the computed fee
        amount in

        inventory asset units (sats for wBTC, 6-decimal units for USDT).
      required:
        - address
        - fee
      properties:
        address:
          type: string
          description: Affiliate recipient address.
        fee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
          description: Computed affiliate fee in the inventory asset smallest unit.
    GatewayTokenAmountV2:
      type: object
      required:
        - amount
        - address
        - chain
      properties:
        address:
          type: string
        amount:
          type: string
        chain:
          type: string
        usd:
          type:
            - string
            - 'null'
          description: USD value of `amount`, absent if no price feed is available.
    GatewayOnrampFeeBreakdownV2:
      type: object
      required:
        - solverFee
        - protocolFee
        - affiliateFee
        - executionFee
        - layerzeroFee
      properties:
        affiliateFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        executionFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        layerzeroFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        protocolFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        solverFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
    GatewayOfframpFeeBreakdownV2:
      type: object
      description: V2 offramp fee breakdown. Same shape as V1 but each line carries USD.
      required:
        - solverFee
        - inclusionFee
        - protocolFee
        - affiliateFee
        - fastestFeeRate
      properties:
        affiliateFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        fastestFeeRate:
          type: string
        inclusionFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        protocolFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
        solverFee:
          $ref: '#/components/schemas/GatewayTokenAmountV2'
    GatewayErrorCode:
      type: string
      description: >-
        Error codes for structured error responses that the frontend can parse.

        These codes are stable and should not be changed without coordinating
        with the frontend.
      enum:
        - INSUFFICIENT_AMOUNT
        - QUOTE_AMOUNT_TOO_LOW
        - INSUFFICIENT_SWAP_AMOUNT
        - INSUFFICIENT_SOLVER_BALANCE
        - INSUFFICIENT_PAYMENT_AMOUNT
        - UNABLE_TO_COVER_FEES
        - INSUFFICIENT_CONFIRMED_FUNDS
        - SIMULATION_FAILED
        - GAS_ESTIMATE_FAILED
        - PER_ACCOUNT_LIMIT_EXCEEDED
        - GLOBAL_LIMIT_EXCEEDED
        - EXCEEDED_LIMIT
        - INVALID_REQUEST
        - INVALID_ORDER_ARGS
        - INVALID_AFFILIATE_FEE
        - SLIPPAGE_TOO_LOW
        - SLIPPAGE_TOO_HIGH
        - NO_ROUTE
        - DISABLED_CHAIN
        - INVALID_DESTINATION_CHAIN_ID
        - ORDER_NOT_FOUND
        - ORDER_EXPIRED
        - DUPLICATE_ORDER
        - INTERNAL_ERROR
    GatewayErrorCodeV2Variants:
      type: string
      description: New error codes for V2.
      enum:
        - INVALID_CURSOR
        - INSUFFICIENT_SOLVER_BALANCE
        - AFFILIATE_FEES_NOT_SUPPORTED_FOR_ROUTE
        - UNKNOWN

````