> ## 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 (V3).

> Accepts a `GatewayQuoteV3` — the signed V3 quote with `ownerAddress` embedded in each variant.



## OpenAPI

````yaml /api-reference/openapi.json post /v3/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:
  /v3/create-order:
    post:
      tags:
        - v3
      summary: Create a new gateway order (V3).
      description: >-
        Accepts a `GatewayQuoteV3` — the signed V3 quote with `ownerAddress`
        embedded in each variant.
      operationId: create_order_v3
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GatewayQuoteV3'
        required: true
      responses:
        '201':
          description: Created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayCreateOrderV3'
        '400':
          description: Create order error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayErrorV3'
components:
  schemas:
    GatewayQuoteV3:
      oneOf:
        - type: object
          required:
            - onramp
          properties:
            onramp:
              $ref: '#/components/schemas/GatewayOnrampQuoteV2'
        - type: object
          required:
            - offramp
          properties:
            offramp:
              $ref: '#/components/schemas/GatewayOfframpQuoteV3'
        - type: object
          required:
            - tokenSwap
          properties:
            tokenSwap:
              $ref: '#/components/schemas/GatewayTokenSwapQuoteV3'
      description: >-
        V3 gateway quote — used for both the get-quote response and the
        create-order body.

        `ownerAddress` is embedded in each variant that carries an owner
        concept.
    GatewayCreateOrderV3:
      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/GatewayTxData'
                  description: Tx data to execute the swap (EVM or Solana)
        - 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/GatewayTxData'
                  description: Tx data to execute the swap (EVM or Solana)
      description: >-
        V3 create-order response; offramp and token-swap carry polymorphic
        `GatewayTxData`.
    GatewayErrorV3:
      type: object
      description: Structured error response for V3 API.
      required:
        - code
        - error
      properties:
        code:
          $ref: '#/components/schemas/GatewayErrorCodeV3'
          description: Stable error code for frontend parsing
        details:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/GatewayErrorDetailsV3'
              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
    GatewayOfframpQuoteV3:
      type: object
      description: 'V3 offramp quote: identical to V2 plus `owner_address`.'
      required:
        - srcChain
        - tokenAddress
        - inputAmount
        - outputAmount
        - totalFeeUsd
        - feeBreakdown
        - recipient
        - slippage
        - txTo
        - ownerAddress
      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'
        ownerAddress:
          type: string
          description: Resolved EVM owner / refund-claimant for the on-chain order.
        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
    GatewayTokenSwapQuoteV3:
      type: object
      description: >-
        V3 token-swap quote: the V2 shape plus a resolved `affiliate`. The quote
        *is*

        the create-order body, so carrying the affiliate here is what stops it
        being

        dropped on the round-trip — the aggregator (Bungee/Velora) charges it on
        the

        source chain. Mirrors how onramp/offramp embed affiliates in their
        quotes.
      required:
        - srcChain
        - dstChain
        - inputAmount
        - outputAmount
        - estimatedTimeInSecs
        - recipient
        - slippage
        - fees
        - txTo
      properties:
        affiliate:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TokenSwapAffiliateV3'
              description: >-
                Affiliate fee applied to this swap, if any. Absent for fee-free
                swaps.
        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
    GatewayTxData:
      oneOf:
        - allOf:
            - $ref: '#/components/schemas/TxInfo'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - evm
        - allOf:
            - $ref: '#/components/schemas/TronTxData'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - tron
        - allOf:
            - $ref: '#/components/schemas/GatewaySolanaTx'
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - solana
      description: >-
        Tagged union of EVM, Tron and Solana transaction data for V3
        create-order responses.
    GatewayErrorCodeV3:
      oneOf:
        - $ref: '#/components/schemas/GatewayErrorCode'
        - $ref: '#/components/schemas/GatewayErrorCodeV2Variants'
        - $ref: '#/components/schemas/GatewayErrorCodeV3Variants'
      description: Error codes for V3 API - includes all V1/V2 codes plus new ones.
    GatewayErrorDetailsV3:
      oneOf:
        - type: object
          required:
            - addresses
          properties:
            addresses:
              type: array
              items:
                type: string
        - 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:
            - max
            - actual
          properties:
            actual:
              type: string
            max:
              type: string
        - type: object
          required:
            - message
          properties:
            message:
              type: string
      description: >-
        Structured details for V3 error types - all V2 variants plus V3-only
        ones.


        Kept as a single flat `oneOf` (not nested under V1/V2/V3 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'
    TokenSwapAffiliateV3:
      type: object
      description: |-
        A single affiliate fee on a token swap: `bps` of the swap input paid to
        `address` by the aggregator on the source chain. Aggregators charge one
        partner fee, so a swap carries at most one.
      required:
        - address
        - bps
      properties:
        address:
          type: string
          description: >-
            Affiliate fee recipient, encoded for the source chain (`0x…` on
            EVM).
        bps:
          type: integer
          format: int32
          description: Affiliate fee size in basis points of the swap input.
          minimum: 0
    TxInfo:
      type: object
      required:
        - to
        - data
        - value
        - chain
      properties:
        chain:
          type: string
        data:
          type: string
        to:
          type: string
        value:
          type: string
    TronTxData:
      type: object
      description: >-
        Tron transaction data: the EVM-style call fields plus `feeLimit`, the
        max TRX

        (in sun) a Tron wallet may burn on energy/bandwidth. EVM chains have no
        such

        concept, so it lives on the dedicated Tron entry rather than every tx.
      required:
        - to
        - data
        - value
        - chain
        - feeLimit
      properties:
        chain:
          type: string
        data:
          type: string
        feeLimit:
          type: string
        to:
          type: string
        value:
          type: string
    GatewaySolanaTx:
      type: object
      description: >-
        Solana transaction returned on V3 create-order (offramp / token-swap).


        `transaction` is base64-encoded bincode serialization of an unsigned
        `VersionedTransaction`.

        Clients must decode, sign, re-serialize, and broadcast — do not sign the
        base64 string directly.
      required:
        - chainId
        - transaction
      properties:
        chainId:
          type: integer
          format: int64
          minimum: 0
        transaction:
          type: string
          example: AgAAA...
    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
    GatewayErrorCodeV3Variants:
      type: string
      description: New error codes for V3.
      enum:
        - BUNGEE_NO_ROUTE
        - MISSING_OWNER_ADDRESS
        - NON_COMPLIANT_ADDRESSES
        - TOO_MANY_AFFILIATES

````