openapi: 3.0.3
info:
  title: Upbit REST Exchange - Account Exchange - Orders API
  description: Upbit is a leading South Korean cryptocurrency exchange operated by Dunamu Inc., offering REST and WebSocket APIs for market data retrieval, order management, account balances, and transaction history. Developers must register an Upbit account with security level 2 or higher to issue API keys. Authenticated requests use JWT bearer tokens (HS512) generated from an Access Key and Secret Key pair, while public quotation endpoints (market data, tickers, orderbooks, candles) require no authentication. Upbit supports KRW, BTC, and USDT trading markets and complies with travel-rule regulations for digital asset transfers.
  version: 1.3.2
  termsOfService: https://upbit.com/service_center/terms
  contact:
    url: https://global-docs.upbit.com/docs/support
  license:
    name: Upbit Open API Usage Agreement
    url: https://upbit.com/service_center/terms
servers:
- url: https://api.upbit.com/v1
  description: Global API endpoint
security: []
tags:
- name: Exchange - Orders
  description: Order management endpoints — JWT required
paths:
  /orders/chance:
    get:
      operationId: getAvailableOrderInformation
      summary: Get available order information
      description: Returns fee rates and account-level order constraints for the specified market.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: market
        in: query
        required: true
        schema:
          type: string
        description: Market identifier (e.g., KRW-BTC)
      responses:
        '200':
          description: Available order information
          content:
            application/json:
              schema:
                type: object
                properties:
                  bid_fee:
                    type: string
                    description: Bid (buy) fee rate (decimal string)
                  ask_fee:
                    type: string
                    description: Ask (sell) fee rate (decimal string)
                  maker_bid_fee:
                    type: string
                    description: Maker bid fee rate (decimal string)
                  maker_ask_fee:
                    type: string
                    description: Maker ask fee rate (decimal string)
                  market:
                    type: object
                    description: Market details
                  bid_account:
                    type: object
                    description: Bid currency account details
                  ask_account:
                    type: object
                    description: Ask currency account details
        '401':
          description: Unauthorized
  /orders:
    post:
      operationId: createOrder
      summary: Create order
      description: Places a new buy or sell order on the specified market. Order type determines which price and volume fields are required.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - market
              - side
              - ord_type
              properties:
                market:
                  type: string
                  description: Market identifier (e.g., KRW-BTC)
                side:
                  type: string
                  enum:
                  - bid
                  - ask
                  description: Order side (bid=buy, ask=sell)
                volume:
                  type: string
                  description: Order volume (decimal string; required for limit and market ask)
                price:
                  type: string
                  description: Order price (decimal string; required for limit and price bid)
                ord_type:
                  type: string
                  enum:
                  - limit
                  - price
                  - market
                  - best
                  description: 'Order type: limit (limit order), price (market buy by total KRW), market (market sell by volume), best (best price)'
                identifier:
                  type: string
                  description: Client-assigned order identifier (optional, must be unique)
                time_in_force:
                  type: string
                  enum:
                  - ioc
                  - fok
                  description: Time-in-force policy (ioc or fok; only for best or limit orders)
                smp_type:
                  type: string
                  enum:
                  - cancel_newest
                  - cancel_oldest
                  - cancel_both
                  description: Self-Match Prevention type
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /orders/test:
    post:
      operationId: createTestOrder
      summary: Create test order
      description: Validates an order request without actually placing it on the exchange. Same contract as createOrder but does not execute.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - market
              - side
              - ord_type
              properties:
                market:
                  type: string
                side:
                  type: string
                  enum:
                  - bid
                  - ask
                volume:
                  type: string
                price:
                  type: string
                ord_type:
                  type: string
                  enum:
                  - limit
                  - price
                  - market
                  - best
                identifier:
                  type: string
                time_in_force:
                  type: string
                  enum:
                  - ioc
                  - fok
                smp_type:
                  type: string
                  enum:
                  - cancel_newest
                  - cancel_oldest
                  - cancel_both
      responses:
        '201':
          description: Test order validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /orders/cancel_and_new:
    post:
      operationId: cancelAndReplaceOrder
      summary: Cancel and replace order
      description: Atomically cancels an existing order and places a new order. Either prev_order_uuid or prev_order_identifier must be provided (not both).
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - new_ord_type
              properties:
                prev_order_uuid:
                  type: string
                  description: UUID of the order to cancel (mutually exclusive with prev_order_identifier)
                prev_order_identifier:
                  type: string
                  description: Client identifier of the order to cancel (mutually exclusive with prev_order_uuid)
                new_ord_type:
                  type: string
                  enum:
                  - limit
                  - price
                  - market
                  - best
                  description: New order type
                new_volume:
                  type: string
                  description: New order volume (decimal string)
                new_price:
                  type: string
                  description: New order price (decimal string)
                new_identifier:
                  type: string
                  description: New client order identifier
                new_time_in_force:
                  type: string
                  enum:
                  - ioc
                  - fok
                new_smp_type:
                  type: string
                  enum:
                  - cancel_newest
                  - cancel_oldest
                  - cancel_both
      responses:
        '201':
          description: Order cancelled and new order created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OrderResponse'
                - type: object
                  properties:
                    new_order_uuid:
                      type: string
                      description: UUID of the newly created replacement order
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /order:
    get:
      operationId: getOrder
      summary: Get single order
      description: Returns the details of a single order by UUID or client identifier. Either uuid or identifier must be provided.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: uuid
        in: query
        required: false
        schema:
          type: string
        description: Order UUID (mutually exclusive with identifier)
      - name: identifier
        in: query
        required: false
        schema:
          type: string
        description: Client order identifier (mutually exclusive with uuid)
      responses:
        '200':
          description: Order details
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OrderResponse'
                - type: object
                  properties:
                    trades:
                      type: array
                      description: List of individual trade fills
                      items:
                        type: object
                        properties:
                          market:
                            type: string
                          uuid:
                            type: string
                          price:
                            type: string
                          volume:
                            type: string
                          funds:
                            type: string
                          created_at:
                            type: string
                            format: date-time
        '401':
          description: Unauthorized
        '404':
          description: Order not found
    delete:
      operationId: cancelOrder
      summary: Cancel single order
      description: Cancels an order by UUID or client identifier. Either uuid or identifier must be provided.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: uuid
        in: query
        required: false
        schema:
          type: string
        description: Order UUID (mutually exclusive with identifier)
      - name: identifier
        in: query
        required: false
        schema:
          type: string
        description: Client order identifier (mutually exclusive with uuid)
      responses:
        '200':
          description: Cancelled order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
  /orders/uuids:
    get:
      operationId: listOrdersByIds
      summary: List orders by IDs
      description: Returns details for multiple orders identified by UUID or client identifier arrays. Either uuids[] or identifiers[] must be provided.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: market
        in: query
        required: false
        schema:
          type: string
        description: Filter by market identifier
      - name: uuids[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Array of order UUIDs (mutually exclusive with identifiers[])
      - name: identifiers[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Array of client identifiers (mutually exclusive with uuids[])
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Sort order
      responses:
        '200':
          description: List of orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
    delete:
      operationId: cancelOrdersByIds
      summary: Cancel orders by IDs
      description: Cancels multiple orders identified by UUID or client identifier arrays. Either uuids[] or identifiers[] must be provided.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: uuids[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Array of order UUIDs (mutually exclusive with identifiers[])
      - name: identifiers[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        description: Array of client identifiers (mutually exclusive with uuids[])
      responses:
        '200':
          description: Cancellation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: array
                    items:
                      type: string
                    description: UUIDs of successfully cancelled orders
                  failed:
                    type: array
                    items:
                      type: string
                    description: UUIDs of orders that could not be cancelled
        '401':
          description: Unauthorized
  /orders/open:
    get:
      operationId: listOpenOrders
      summary: List open orders
      description: Returns all open (unfilled or partially filled) orders for the authenticated account.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: market
        in: query
        required: false
        schema:
          type: string
        description: Filter by market identifier
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum:
          - wait
          - watch
        description: Filter by order state
      - name: states[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - wait
            - watch
        description: Filter by multiple order states
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
        description: Page number for pagination
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
        description: Number of results per page
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Sort order
      responses:
        '200':
          description: List of open orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
    delete:
      operationId: batchCancelOrders
      summary: Batch cancel open orders
      description: Cancels multiple open orders matching the specified criteria. Up to 300 orders can be cancelled per request.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: quote_currencies
        in: query
        required: false
        schema:
          type: string
        description: Filter by quote currencies
      - name: cancel_side
        in: query
        required: false
        schema:
          type: string
          enum:
          - bid
          - ask
        description: Only cancel orders on this side
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 300
        description: Maximum number of orders to cancel
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Ordering for selecting orders to cancel
      - name: pairs
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of market pairs to include
      - name: exclude_pairs
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of market pairs to exclude
      responses:
        '200':
          description: Batch cancellation results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: array
                    items:
                      type: string
                  failed:
                    type: array
                    items:
                      type: string
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded (1 request per 2 seconds)
  /orders/closed:
    get:
      operationId: listClosedOrders
      summary: List closed orders
      description: Returns completed (done or cancelled) orders for the authenticated account.
      tags:
      - Exchange - Orders
      security:
      - bearerAuth: []
      parameters:
      - name: market
        in: query
        required: false
        schema:
          type: string
        description: Filter by market identifier
      - name: state
        in: query
        required: false
        schema:
          type: string
          enum:
          - done
          - cancel
        description: Filter by order state
      - name: states[]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - done
            - cancel
        description: Filter by multiple order states
      - name: start_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Start of time range
      - name: end_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: End of time range
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        description: Number of results to return
      - name: order_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Sort order
      responses:
        '200':
          description: List of closed orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
components:
  schemas:
    OrderResponse:
      type: object
      properties:
        market:
          type: string
          description: Market identifier
        uuid:
          type: string
          description: Order UUID
        side:
          type: string
          enum:
          - bid
          - ask
          description: Order side (bid=buy, ask=sell)
        ord_type:
          type: string
          enum:
          - limit
          - price
          - market
          - best
          description: Order type
        state:
          type: string
          enum:
          - wait
          - watch
          - done
          - cancel
          description: Order state
        created_at:
          type: string
          format: date-time
          description: Order creation time
        remaining_volume:
          type: string
          description: Remaining volume (decimal string)
        executed_volume:
          type: string
          description: Executed volume (decimal string)
        reserved_fee:
          type: string
          description: Reserved fee (decimal string)
        remaining_fee:
          type: string
          description: Remaining fee (decimal string)
        paid_fee:
          type: string
          description: Paid fee (decimal string)
        locked:
          type: string
          description: Locked amount (decimal string)
        trades_count:
          type: integer
          description: Number of trades
        prevented_volume:
          type: string
          description: Volume prevented by SMP (decimal string)
        prevented_locked:
          type: string
          description: Amount locked by SMP prevention (decimal string)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT HS512 token generated from Access Key and Secret Key. Include query_hash and query_hash_alg=SHA512 in the payload when query parameters or JSON body exist.
externalDocs:
  description: Upbit Developer Center
  url: https://global-docs.upbit.com/reference