Korbit Deposit/Withdrawal (KRW) API

openapi: 3.1.0
info:
  title: Korbit Open API v2 Asset Deposit/Withdrawal (KRW) API
  version: 2.0.0
  description: 'REST API for the Korbit cryptocurrency exchange (Korea''s first virtual-asset exchange). Covers market data (quotation), trading, balances, crypto deposits and withdrawals, and KRW deposit/withdrawal push notifications.


    All responses use the envelope `{"success": true, "data": ...}`; errors use `{"success": false, "error": {"message": "<CODE>"}}`.


    Private endpoints require the `X-KAPI-KEY` header plus `timestamp` and `signature` parameters. Signatures are HMAC-SHA256 (hex) or ED25519 (Base64, URL-encoded) over the exact encoded request string. See the timestamp-window rules: `recvWindow` defaults to 5000 ms, maximum 60000 ms, and the future bound is a fixed +1000 ms.


    This document was generated by the API Evangelist enrichment pipeline from Korbit''s own published agent documentation bundle (https://docs.korbit.co.kr/llms-full.txt). Korbit does not publish an OpenAPI document; this is a faithful transcription of the published reference, not an official artifact.'
  contact:
    name: Korbit Developers
    url: https://developers.korbit.co.kr
  x-generated-by: API Evangelist enrichment pipeline
  x-source: https://docs.korbit.co.kr/llms-full.txt
servers:
- url: https://api.korbit.co.kr
  description: Production
- url: http://127.0.0.1:9999
  description: Local sandbox (korbit-sandbox.mjs) — mock, not the production server
tags:
- name: Deposit/Withdrawal (KRW)
paths:
  /v2/krw/sendKrwDepositPush:
    post:
      operationId: createKrwSendKrwDepositPush
      summary: Request Deposit
      description: "Send a notification for KRW deposit requests to your Korbit mobile app. \nAfter receiving the notification, you must complete the verification process for the deposit to proceed.\nTo receive notifications, ensure that push notifications are enabled in the app settings."
      tags:
      - Deposit/Withdrawal (KRW)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                accountSeq:
                  type: number
                  description: Account sequence number. Deposit/withdrawal APIs only operate on the main account, so only `1` is accepted. Defaults to 1.
                  examples:
                  - 1
                amount:
                  type: string
                  description: Amount of KRW to deposit.
                  examples:
                  - '50000'
              required:
              - amount
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                    - true
                required:
                - success
              example:
                success: true
        '400':
          description: Bad request — see the error envelope and error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key lacks the required permission or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - KorbitApiKey: []
      x-korbit-permission: writeDeposits
  /v2/krw/sendKrwWithdrawalPush:
    post:
      operationId: createKrwSendKrwWithdrawalPush
      summary: Request Withdrawal
      description: "Send a notification for KRW withdrawal requests to your Korbit mobile app. \nAfter receiving the notification, you must complete the verification process for the withdrawal to proceed.\nTo receive notifications, ensure that push notifications are enabled in the app settings."
      tags:
      - Deposit/Withdrawal (KRW)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                accountSeq:
                  type: number
                  description: Account sequence number. Deposit/withdrawal APIs only operate on the main account, so only `1` is accepted. Defaults to 1.
                  examples:
                  - 1
                amount:
                  type: string
                  description: Amount of KRW to withdraw.
                  examples:
                  - '50000'
              required:
              - amount
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                    - true
                required:
                - success
              example:
                success: true
        '400':
          description: Bad request — see the error envelope and error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key lacks the required permission or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - KorbitApiKey: []
      x-korbit-permission: writeWithdrawals
  /v2/krw/recentDeposits:
    get:
      operationId: getKrwRecentDeposits
      summary: Get Recent Deposits
      description: Get recent KRW deposit history.
      tags:
      - Deposit/Withdrawal (KRW)
      parameters:
      - name: accountSeq
        in: query
        description: Account sequence number. Deposit/withdrawal APIs only operate on the main account, so only `1` is accepted. Defaults to 1.
        schema:
          type: number
          examples:
          - 1
      - name: limit
        in: query
        description: 'Maximum number of queries (range: 1 to 100).'
        schema:
          type: number
          examples:
          - 100
      - name: includeAll
        in: query
        description: Retrieve all transaction history. `false` — Only regular KRW deposits (default) / `true` — Includes additional items such as deposit fees, event rewards, etc.
        schema:
          type: string
          enum:
          - 'false'
          - 'true'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                    - true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: KRW deposit ID.
                          examples:
                          - 1234
                        type:
                          type: string
                          enum:
                          - general
                          - depositInterest
                          - makerIncentive
                          - reward
                          - etc
                          description: Deposit type (when includeAll=true) `general` — Regular KRW deposit / `depositInterest` — Deposit fee / `makerIncentive` — Maker incentive / `reward` — Event reward / `etc` — Other
                        status:
                          type: string
                          enum:
                          - pending
                          - processing
                          - reviewing
                          - done
                          - canceling
                          - canceled
                          - failed
                          description: KRW deposit status `pending` — Deposit request received. / `processing` — Processing deposit. / `reviewing` — Reviewing deposit. / `done` — Deposit done. / `canceling` — Deposit cancel requested. / `canceled` — Deposit canceled. / `failed` — Deposit failed.
                        quantity:
                          type: string
                          description: deposit quantity.
                          examples:
                          - '1.234'
                        createdAt:
                          type: number
                          description: deposit timestamp (ms).
                          examples:
                          - 1700000000000
                      required:
                      - id
                      - status
                      - quantity
                      - createdAt
                required:
                - success
              example:
                success: true
                data:
                - id: 1234
                  status: done
                  quantity: '50000'
                  createdAt: 1700000000000
        '400':
          description: Bad request — see the error envelope and error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key lacks the required permission or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - KorbitApiKey: []
      x-korbit-permission: readDeposits
  /v2/krw/recentWithdrawals:
    get:
      operationId: getKrwRecentWithdrawals
      summary: Get Recent Withdrawals
      description: Get recent KRW withdrawal history.
      tags:
      - Deposit/Withdrawal (KRW)
      parameters:
      - name: accountSeq
        in: query
        description: Account sequence number. Deposit/withdrawal APIs only operate on the main account, so only `1` is accepted. Defaults to 1.
        schema:
          type: number
          examples:
          - 1
      - name: limit
        in: query
        description: 'Maximum number of queries (Range: 1 to 100).'
        schema:
          type: number
          examples:
          - 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    examples:
                    - true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: KRW withdrawal ID.
                          examples:
                          - 1234
                        quantity:
                          type: string
                          description: Withdrawn KRW quantity excluding fees.
                          examples:
                          - '50000'
                        fee:
                          type: string
                          description: withdrawal fee.
                          examples:
                          - '1000'
                        status:
                          type: string
                          enum:
                          - processing
                          - done
                          - failed
                          - canceled
                          description: KRW withdrawal status `processing` — Processing withdrawal. / `done` — Withdrawal done. / `failed` — Withdrawal failed. / `canceled` — Withdrawal canceled.
                        createdAt:
                          type: number
                          description: withdrawal request timestamp (ms).
                          examples:
                          - 1700000000000
                      required:
                      - id
                      - quantity
                      - fee
                      - status
                      - createdAt
                required:
                - success
              example:
                success: true
                data:
                - id: 1234
                  quantity: '50000'
                  fee: '1000'
                  status: done
                  createdAt: 1700000000000
        '400':
          description: Bad request — see the error envelope and error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key / signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API key lacks the required permission or the IP is not allowlisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - KorbitApiKey: []
      x-korbit-permission: readWithdrawals
components:
  schemas:
    ErrorResponse:
      type: object
      description: Korbit error envelope. `error.message` carries the symbolic error code.
      properties:
        success:
          type: boolean
          examples:
          - false
        error:
          type: object
          properties:
            message:
              type: string
              description: Symbolic error code, e.g. `NO_BALANCE`.
              examples:
              - NO_BALANCE
      required:
      - success
  securitySchemes:
    KorbitApiKey:
      type: apiKey
      in: header
      name: X-KAPI-KEY
      description: API key issued in the Korbit Developers portal (https://developers.korbit.co.kr). Keys carry permissions (readOrders, writeOrders, readBalances, readDeposits, writeDeposits, readWithdrawals, writeWithdrawals), may be pinned to an IP allowlist, and are valid for one year. Every signed request additionally carries `timestamp` and `signature` parameters (HMAC-SHA256 hex or ED25519 base64).