# 시세

[← REST API 가이드](../rest_api.md)

## 현재가 조회 {#get-_v2_tickers}

```
GET /v2/tickers
```

하나 또는 여러 거래쌍의 현재가(Ticker) 정보를 조회합니다.

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /**
   * 조회하고자 하는 거래쌍의 심볼을 입력합니다. 여러 거래쌍을 한 번에 조회하고자 한다면 콤마(,)로 구분해 입력합니다.
   * 입력하지 않으면 코빗에서 거래 가능한 모든 거래쌍의 현재가 정보를 응답합니다.
   * Example: "btc_krw,eth_krw"
   */
  symbol?: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 거래쌍. Example: "btc_krw" */
  symbol: string;
  /** 최근 24시간 시가. Example: "361922.23" */
  open: string;
  /** 최근 24시간 고가. Example: "361922.23" */
  high: string;
  /** 최근 24시간 저가. Example: "361922.23" */
  low: string;
  /** 최근 24시간 종가. Example: "361922.23" */
  close: string;
  /** 직전 24시간 종가. Example: "261922.23" */
  prevClose: string;
  /** 직전 종가 대비 가격 변화량. `close - prevClose`으로 계산합니다. Example: "100000" */
  priceChange: string;
  /** 직전 종가 대비 가격 변화율(단위: %). `100 * (close - prevClose) / prevClose`으로 계산합니다. Example: "38.18" */
  priceChangePercent: string;
  /** 최근 24시간 거래량. 단위는 기준자산(base currency, `symbol`의 첫 번째 항목)입니다. Example: "100" */
  volume: string;
  /** 최근 24시간 거래대금. 단위는 상대자산(quote currency, `symbol`의 두 번째 항목)입니다. Example: "1000000000" */
  quoteVolume: string;
  /** 매수 1호가. Example: "5000" */
  bestBidPrice: string;
  /** 매도 1호가. Example: "6000" */
  bestAskPrice: string;
  /** 마지막 체결 시각 (단위: Unix Timestamp (밀리초)). Example: 1700000000000 */
  lastTradedAt: number;
}>;
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/tickers?symbol=btc_krw,eth_krw'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "symbol": "btc_krw",
      "open": "77060000",
      "high": "79650000",
      "low": "76550000",
      "close": "77136000",
      "prevClose": "77060000",
      "priceChange": "76000",
      "priceChangePercent": "0.1",
      "volume": "48.73739983",
      "quoteVolume": "3785149733.32633",
      "bestBidPrice": "77136000",
      "bestAskPrice": "77193000",
      "lastTradedAt": 1725525721041
    },
    {
      "symbol": "eth_krw",
      "open": "3259000",
      "high": "3370000",
      "low": "3222000",
      "close": "3250000",
      "prevClose": "3259000",
      "priceChange": "-9000",
      "priceChangePercent": "-0.28",
      "volume": "161.99278306",
      "quoteVolume": "532827941.01581",
      "bestBidPrice": "3251000",
      "bestAskPrice": "3254000",
      "lastTradedAt": 1725525545630
    }
  ]
}
```

## 호가 조회 {#get-_v2_orderbook}

```
GET /v2/orderbook
```

단일 거래쌍의 호가 정보를 조회합니다.

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 대상 거래쌍의 심볼. Example: "btc_krw" */
  symbol: string;
  /** 오더북 모아보기 단위. 모아보기 단위는 호가 정책 조회 API로 확인할 수 있습니다. 입력하지 않을 경우 모아보기를 적용하지 않습니다. Example: "1000" */
  level?: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = {
  /** 호가 정보의 기준 시각 (단위: Unix Timestamp (밀리초)). Example: 1700000000000 */
  timestamp: number;
  /** 매수 호가 정보 (호가 내림차순 정렬) */
  bids: Array<{
    /** 매수호가. Example: "250000" */
    price: string;
    /** 매수잔량. Example: "10" */
    qty: string;
    /** 호가 금액 (상대자산). 오더북 모아보기를 사용하는 경우에만 세팅되며, 모아보기를 사용하지 않는 경우 `price * qty`로 계산할 수 있습니다. Example: "2500000" */
    amt?: string;
  }>;
  /** 매도 호가 정보 (호가 오름차순 정렬) */
  asks: Array<{
    /** 매도호가. Example: "250000" */
    price: string;
    /** 매도잔량. Example: "10" */
    qty: string;
    /** 호가 금액 (상대자산). 오더북 모아보기를 사용하는 경우에만 세팅되며, 모아보기를 사용하지 않는 경우 `price * qty`로 계산할 수 있습니다. Example: "2500000" */
    amt?: string;
  }>;
};
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/orderbook?symbol=btc_krw'
```
#### 응답
```json
{
  "success": true,
  "data": {
    "timestamp": 1708057740895,
    "bids": [
      {
        "price": "73303000",
        "qty": "0.00898326"
      },
      {
        "price": "73302000",
        "qty": "0.00790837"
      },
      {
        "price": "73301000",
        "qty": "0.00843099"
      },
      {
        "price": "73300000",
        "qty": "0.00054024"
      },
      {
        "price": "73299000",
        "qty": "0.00663446"
      }
    ],
    "asks": [
      {
        "price": "73304000",
        "qty": "0.00985212"
      },
      {
        "price": "73305000",
        "qty": "0.00367505"
      },
      {
        "price": "73306000",
        "qty": "0.0096254"
      },
      {
        "price": "73307000",
        "qty": "0.00502544"
      },
      {
        "price": "73308000",
        "qty": "0.00640584"
      }
    ]
  }
}
```

## 최근 체결 내역 {#get-_v2_trades}

```
GET /v2/trades
```

최근 체결 내역을 조회합니다.

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 대상 거래쌍의 심볼. Example: "btc_krw" */
  symbol: string;
  /** 최대 조회 건수 (범위: 1 - 500). Example: 100 */
  limit?: number;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 체결 시각 (단위: Unix Timestamp (밀리초)). Example: 1700000000000 */
  timestamp: number;
  /** 체결 가격. Example: "250000" */
  price: string;
  /** 체결량. Example: "10" */
  qty: string;
  /** 테이커(Taker)가 매수자인지 여부. Example: true */
  isBuyerTaker: boolean;
  /** 거래 체결 ID (각 거래쌍마다 생성된 개별 거래 체결 건의 ID). 거래쌍별로 단조 증가하지만 연속성은 보장되지 않습니다. Example: 1234 */
  tradeId: number;
}>;
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/trades?symbol=btc_krw&limit=4'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "timestamp": 1708057271149,
      "price": "70507000",
      "qty": "0.00981535",
      "isBuyerTaker": false,
      "tradeId": 1004
    },
    {
      "timestamp": 1708057271035,
      "price": "70508000",
      "qty": "0.00682475",
      "isBuyerTaker": false,
      "tradeId": 1003
    },
    {
      "timestamp": 1708057270922,
      "price": "70509000",
      "qty": "0.00844147",
      "isBuyerTaker": false,
      "tradeId": 1002
    },
    {
      "timestamp": 1708057270809,
      "price": "70510000",
      "qty": "0.00553963",
      "isBuyerTaker": false,
      "tradeId": 1001
    }
  ]
}
```

## 캔들스틱 조회 {#get-_v2_candles}

```
GET /v2/candles
```

시세 캔들스틱 정보를 조회합니다.

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 대상 거래쌍의 심볼. Example: "btc_krw" */
  symbol: string;
  /**
   * 각 캔들 주기(단위)
   * 허용되는 값:
   */
  interval:
    | "1"  // 1분
    | "5"  // 5분
    | "15"  // 15분
    | "30"  // 30분
    | "60"  // 1시간
    | "240"  // 4시간
    | "1D"  // 1일
    | "1W"  // 1주
    ;
  /** 조회 시작 시각(timestamp). 입력하지 않으면 거래쌍 상장 시점부터 조회합니다. Example: 1600000000000 */
  start?: number;
  /** 조회 종료 시각(timestamp). `start`보다 큰 값을 입력해야 합니다. 입력하지 않으면 현재 시점까지 조회합니다. Example: 1700000000000 */
  end?: number;
  /** 최대 조회 건수 (범위: 1 - 200). Example: 100 */
  limit: number;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 캔들 시작 시각(timestamp). Example: 1619244573612 */
  timestamp: number;
  /** 시가. Example: "361922.23" */
  open: string;
  /** 고가. Example: "361922.23" */
  high: string;
  /** 저가. Example: "361922.23" */
  low: string;
  /** 종가. Example: "361922.23" */
  close: string;
  /** 거래량 (기준자산). Example: "100" */
  volume: string;
}>;
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/candles?symbol=btc_krw&interval=60&limit=5&end=1700000000000'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "timestamp": 1708041600000,
      "open": "71211000",
      "high": "9999990000",
      "low": "300000",
      "close": "71392000",
      "volume": "1.932320026577213946"
    },
    {
      "timestamp": 1708045200000,
      "open": "73510000",
      "high": "74605000",
      "low": "300000",
      "close": "72315000",
      "volume": "2.418698679231323743"
    },
    {
      "timestamp": 1708048800000,
      "open": "72315000",
      "high": "9999990000",
      "low": "300000",
      "close": "72380000",
      "volume": "1.947520219976227299"
    },
    {
      "timestamp": 1708052400000,
      "open": "70267000",
      "high": "74777000",
      "low": "300000",
      "close": "74049000",
      "volume": "2.254855048982521506"
    },
    {
      "timestamp": 1708056000000,
      "open": "68304000",
      "high": "74834000",
      "low": "68241000",
      "close": "74825000",
      "volume": "0.630193755379195341"
    }
  ]
}
```

## 거래지원 목록 조회 {#get-_v2_currencyPairs}

```
GET /v2/currencyPairs
```

거래지원 거래쌍 목록을 각 거래쌍의 통화 구성 및 주문금액 한도와 함께 조회합니다.

### 스키마

```ts
// 요청 파라미터 없음

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 거래쌍 심볼. Example: "btc_krw" */
  symbol: string;
  /** 거래 가능 상태 */
  status:
    | "launched"  // 거래 가능
    | "stopped"  // 거래 중단
    ;
  /** 해당 거래쌍의 기준자산. 거래 대상이 되는 자산이며 `symbol`의 첫 번째 항목입니다. Example: "btc" */
  baseCurrency: string;
  /** 해당 거래쌍의 상대자산. 가격이 표시되는 자산이며 `symbol`의 두 번째 항목입니다. `price`, `amt`, `minOrderValue`, `maxOrderValue`가 모두 이 자산 단위입니다. Example: "krw" */
  quoteCurrency: string;
  /** 해당 거래쌍의 최소 주문금액(`quoteCurrency` 단위). 수량*가격(시장가 매수는 `amt`)이 이 값보다 작은 주문은 `ORDER_VALUE_TOO_SMALL`로 거절됩니다. 이 거래쌍이 최소 주문금액을 공개하지 않으면 생략되며, 이때는 클라이언트 검증을 건너뛰고 서버 판단에 맡기세요. 생략되었다고 해서 주문금액에 제한이 없다는 뜻은 아닙니다. Example: "5000" */
  minOrderValue?: string;
  /** 해당 거래쌍의 최대 주문금액(`quoteCurrency` 단위). 이 값을 초과하는 주문은 `ORDER_VALUE_TOO_LARGE`로 거절됩니다. 이 거래쌍이 최대 주문금액을 공개하지 않으면 생략되며, 이때는 클라이언트 검증을 건너뛰고 서버 판단에 맡기세요. 생략되었다고 해서 주문금액에 제한이 없다는 뜻은 아닙니다. Example: "1000000000" */
  maxOrderValue?: string;
}>;
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/currencyPairs'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "symbol": "btc_krw",
      "status": "launched",
      "baseCurrency": "btc",
      "quoteCurrency": "krw",
      "minOrderValue": "5000",
      "maxOrderValue": "1000000000"
    },
    {
      "symbol": "eth_krw",
      "status": "launched",
      "baseCurrency": "eth",
      "quoteCurrency": "krw",
      "minOrderValue": "5000",
      "maxOrderValue": "1000000000"
    },
    {
      "symbol": "xrp_krw",
      "status": "stopped",
      "baseCurrency": "xrp",
      "quoteCurrency": "krw",
      "minOrderValue": "5000",
      "maxOrderValue": "1000000000"
    }
  ]
}
```

## 호가 정책 조회 {#get-_v2_tickSizePolicy}

```
GET /v2/tickSizePolicy
```

지정한 거래쌍의 호가 정책 및 오더북 모아보기 단위를 조회합니다.

### 스키마

```ts
// URL 쿼리 파라미터
type RequestQuery = {
  /** 거래쌍 심볼. Example: "xrp_krw" */
  symbol: string;
};

// JSON 응답 (`{ success: true, data }` 형태로 래핑되며, 아래는 `data` 필드의 구조)
type Response = Array<{
  /** 거래쌍 심볼. Example: "xrp_krw" */
  symbol: string;
  /**
   * 호가 정책 목록.
   * 배열에서 `주문가격 >= priceGte` 조건을 만족하는 항목 중 가장 큰 `priceGte` 값을 가진 항목의 `tickSize`를 사용합니다.
   * 예: 주문가격이 150원이라면, `priceGte`가 "100"인 항목의 `tickSize`를 사용합니다.
   */
  tickSizePolicy: Array<{
    /** 가격 범위 시작값 (이상). Example: "0.1" */
    priceGte: string;
    /** 해당 가격 범위의 호가 단위. Example: "0.0001" */
    tickSize: string;
  }>;
  /** 오더북 모아보기 단위 목록 */
  orderbookLevels: string[];
}>;
```

### 예시

#### 요청
```sh
curl 'https://api.korbit.co.kr/v2/tickSizePolicy?symbol=xrp_krw'
```
#### 응답
```json
{
  "success": true,
  "data": [
    {
      "symbol": "xrp_krw",
      "tickSizePolicy": [
        {
          "priceGte": "0",
          "tickSize": "0.0001"
        },
        {
          "priceGte": "1",
          "tickSize": "0.001"
        },
        {
          "priceGte": "10",
          "tickSize": "0.01"
        },
        {
          "priceGte": "100",
          "tickSize": "0.1"
        },
        {
          "priceGte": "1000",
          "tickSize": "1"
        },
        {
          "priceGte": "5000",
          "tickSize": "5"
        },
        {
          "priceGte": "10000",
          "tickSize": "10"
        },
        {
          "priceGte": "50000",
          "tickSize": "50"
        },
        {
          "priceGte": "100000",
          "tickSize": "100"
        },
        {
          "priceGte": "500000",
          "tickSize": "500"
        },
        {
          "priceGte": "1000000",
          "tickSize": "1000"
        }
      ],
      "orderbookLevels": [
        "10",
        "100",
        "1000"
      ]
    }
  ]
}
```