Blog

코인베이스 API 사용법: 단계별 가이드

Rebecca Kovács

Rebecca Kovács

27 May 2025

코인베이스 API 사용법: 단계별 가이드

디지털 자산 거래 분야의 글로벌 리더인 코인베이스는 강력한 애플리케이션 프로그래밍 인터페이스(API) 제품군을 제공합니다. 이 API는 개발자, 알고리즘 트레이더 및 금융 기관이 코인베이스의 거래 및 데이터 서비스와 프로그램적으로 통합하려는 경우의 핵심입니다. 이 가이드에서는 코인베이스 거래소 API에 대한 자세한 기술적 탐색을 제공하며, 실제 구현, 핵심 기능 및 운영 모범 사례에 중점을 둡니다.

💡
멋진 API 테스트 도구를 원하시나요? 이 도구는 아름다운 API 문서를 생성합니다.

개발 팀이 최대한의 생산성을 발휘할 수 있도록 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하시나요?

Apidog는 여러분의 모든 요구 사항을 충족하며, 훨씬 더 저렴한 가격으로 Postman을 대체합니다!
button

초기 설정 및 인증

코인베이스 거래소 API와 성공적으로 상호 작용하려면 계정 준비, 안전한 API 키 관리 및 인증 프로토콜에 대한 정확한 이해가 필요합니다.

계정 필수 조건 및 API 키 생성

일반적으로 코인베이스 Advanced Trade 또는 기관 계정과 같은 인증된 코인베이스 계정이 필요합니다. API 키는 계정 설정 내에서 생성됩니다. 이 과정에서 다음 세 가지 중요한 정보가 생성됩니다.

  1. API 키: 애플리케이션을 식별하는 공개 영숫자 문자열 (예: k7b9f2d7e8h1g3j4).
  2. API 시크릿: 비공개 영숫자 문자열 (예: S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). 이 시크릿은 생성 시 한 번만 표시되므로 안전하게 보관해야 합니다.
  3. 암호: 키 생성 시 직접 생성하는 추가 보안 자격 증명 (예: mySecureP@$$phr@se2024!).

API 키 권한은 세분화되어 있어 작업(예: 보기 전용, 거래 실행, 출금 기능)을 제한할 수 있습니다. 항상 최소 권한 원칙을 준수하십시오.

API 요청 인증

코인베이스 거래소 API는 모든 비공개 인증 엔드포인트에 대해 서명 기반 인증 메커니즘(HMAC-SHA256)을 사용합니다. 각 요청에는 몇 가지 사용자 정의 HTTP 헤더가 필요합니다.

서명(CB-ACCESS-SIGN)은 사전 해시 문자열의 HMAC-SHA256 해시를 생성하여 생성됩니다. 사전 해시 문자열은 다음의 연결입니다.

  1. 타임스탬프(문자열).
  2. 대문자로 된 HTTP 메서드 (예: GET, POST).
  3. 요청 경로 (예: /orders, /products/BTC-USD/book).
  4. 요청 본문 (POST 요청의 경우; 본문이 없으면 빈 문자열).

사전 해시 문자열 구성 예시 (POST 요청의 경우):

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // JSON string, not Python dict
prehash_string = timestamp + method + request_path + body_json_string

// The API Secret needs to be base64-decoded before being used as the HMAC key.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

잘못 구성된 사전 해시 문자열 또는 타임스탬프 불일치(NTP를 통해 서버 시계가 동기화되었는지 확인)는 인증 오류(HTTP 401)의 일반적인 원인입니다.

클라이언트 라이브러리 및 개발 환경

Python(`cbpro`), Node.js(`coinbase-pro-node`), Java, Go와 같은 언어의 공식 및 커뮤니티 개발 클라이언트 라이브러리는 이러한 인증 복잡성을 추상화합니다. 대신 `curl` 또는 표준 HTTP 클라이언트 모듈과 같은 도구를 사용하여 직접 HTTP 요청을 할 수 있으며, 이 경우 서명 프로세스를 수동으로 구현해야 합니다.

테스트를 위한 샌드박스 환경

코인베이스는 실제 시장과 상호 작용하기 전에 중요한 개발 및 테스트를 위한 샌드박스 환경을 제공합니다.

목적 및 기능

샌드박스는 프로덕션 API 기능을 반영하지만, 테스트 자금과 시뮬레이션된 시장 데이터를 사용합니다. 다음과 같은 작업을 수행할 수 있습니다.

프로덕션 환경과의 주요 차이점

프로덕션 환경으로 전환

강력한 배포 전략에는 샌드박스와 프로덕션 환경에 대한 별도의 구성이 포함되며, 주로 API 자격 증명과 기본 URL에서 차이가 납니다. 샌드박스에서 철저한 테스트를 수행하는 것은 실제 자금으로 인한 오류를 방지하는 데 가장 중요합니다.

핵심 API 기능: 엔드포인트 및 데이터 구조

API는 크게 계정 관리, 시장 데이터 검색 및 거래 운영으로 분류됩니다.

계정 관리

계정 상태 및 기록 조회를 위한 엔드포인트.

계정 잔액 가져오기 (`GET /accounts`)
모든 사용자 계정(법정화폐 및 암호화폐) 목록과 해당 잔액을 검색합니다.
BTC 계정에 대한 응답 스니펫 예시:

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "your-profile-id-string"
}

balance는 총 금액, available은 거래에 사용할 수 있는 금액, hold는 미체결 주문에 예약된 자금입니다.

계정 기록 / 원장 (`GET /accounts/{account_id}/ledger`)
특정 계정에 대한 거래(거래, 수수료, 이체)의 페이지별 목록을 제공합니다.
일반적인 쿼리 매개변수: before(페이지네이션 커서), after(커서), limit(최대 100, 기본 100), start_date, end_date.
원장 항목 스니펫 예시:

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

시장 데이터 엔드포인트

실시간 및 과거 시장 정보에 대한 액세스.

상품 / 거래 쌍 (`GET /products`)
사용 가능한 모든 거래 쌍과 해당 속성을 나열합니다.
상품 스니펫 예시 (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // 기본 통화 기준 최소 주문 수량
  "base_max_size": "200.0",  // 기본 통화 기준 최대 주문 수량
  "quote_increment": "0.01", // 견적 통화의 최소 가격 변동 단위
  "base_increment": "0.00000001", // 기본 통화의 최소 수량 변동 단위
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // 시장가 주문의 견적 통화 기준 최소 자금
  "max_market_funds": "1000000", // 시장가 주문의 최대 자금
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

호가창 (`GET /products/{product_id}/book`)
상품의 현재 호가창을 검색합니다.
쿼리 매개변수: level (1, 2 또는 3).
*   레벨 1: 최우선 매수/매도 호가만.
*   레벨 2: 각 가격 수준별 매수/매도 호가 집계 목록. (각 측면당 최대 50개 항목).
*   레벨 3: 개별 비집계 주문을 포함한 전체 호가창 (인증 필요하며 더 엄격한 속도 제한이 있을 수 있습니다).
레벨 2 호가창 스니펫 예시 (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [가격, 수량, 이 가격의 주문 수]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

상품 티커 (`GET /products/{product_id}/ticker`)
최종 거래(틱), 최우선 매수/매도 호가 및 24시간 거래량에 대한 스냅샷 정보.
티커 스니펫 예시 (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // 최종 거래 가격
  "size": "0.005",    // 최종 거래 수량
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 기본 통화 기준 24시간 거래량
  "time": "2023-10-26T10:06:15.234Z"
}

과거 가격 / 캔들 (`GET /products/{product_id}/candles`)
과거 가격 데이터(OHLCV)를 검색합니다.
쿼리 매개변수: start(ISO 8601 타임스탬프), end(ISO 8601), granularity(초 단위: 60, 300, 900, 3600, 21600, 86400). 요청당 최대 300개의 캔들.
캔들 데이터 예시 (1시간 단위):

[
  // [시간, 저가, 고가, 시가, 종가, 거래량]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // 시간은 Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

거래 운영

주문 제출, 관리 및 조회를 위한 엔드포인트.

주문 제출 (`POST /orders`)
매칭 엔진에 새 주문을 제출합니다.
일반적인 요청 본문 매개변수:

{
  "client_oid": "my-unique-client-order-id-001", // 선택 사항: 멱등성을 위한 UUID
  "product_id": "BTC-USD",
  "side": "buy", // "buy" 또는 "sell"
  "type": "limit", // "limit", "market" 또는 "stop" (스톱 주문은 더 복잡함)
  "price": "49500.00", // 지정가 주문에 필수
  "size": "0.0125", // 매수/매도할 기본 통화 수량
  // "funds": "500.00", // 시장가 매수 주문의 경우: 사용할 견적 통화 금액
  "time_in_force": "GTC", // GTC (취소 시까지 유효), GTT (지정 시간까지 유효), IOC (즉시 체결 또는 취소), FOK (전량 체결 또는 취소)
  // "cancel_after": "min" / "hour" / "day" // GTT와 함께 사용
  "post_only": false, // true인 경우 즉시 체결될 주문은 거부됨 (메이커 보장)
  "stp": "dc" // 자가 거래 방지: "dc" (감소 및 취소), "co" (가장 오래된 주문 취소), "cn" (가장 새로운 주문 취소), "cb" (둘 다 취소)
}

주문 제출에 성공하면 서버 할당 id를 포함한 주문 상세 정보가 반환됩니다.

주문 관리

체결 (`GET /fills`)
체결된 거래(체결)의 페이지별 목록을 검색합니다.
쿼리 매개변수: order_id, product_id, before, after, limit.
체결 스니펫 예시:

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // 메이커는 "M", 테이커는 "T"
  "fee": "0.00000250", // API에 따라 견적 통화(BTC-USD의 경우 USD) 또는 기본 통화로 된 수수료.
  "settled": true,
  "side": "buy"
}

매칭 엔진

매칭 엔진은 가격-시간 우선순위 알고리즘에 따라 매수 및 매도 주문을 매칭합니다.

  1. 가격 우선순위: 더 유리한 가격의 주문이 우선순위를 갖습니다 (매수 호가의 경우 높은 가격, 매도 호가의 경우 낮은 가격).
  2. 시간 우선순위: 동일 가격의 주문 중에서는 가장 먼저 제출된 주문이 우선순위를 갖습니다.

이 로직을 이해하는 것은 주문 제출 전략, 슬리피지 관리 및 수수료 최적화에 매우 중요합니다.

속도 제한 및 스로틀링

API 액세스는 플랫폼 안정성과 공정한 사용을 보장하기 위해 속도 제한이 적용됩니다.

유형 및 식별

제한은 일반적으로 API 키별, IP 주소별로 적용되며 엔드포인트별로 다를 수 있습니다 (예: 비공개 서명된 엔드포인트 vs 공개 서명되지 않은 엔드포인트). 공개 엔드포인트는 IP당 초당 3-10회 요청과 같은 제한이 있을 수 있습니다. 비공개(서명된) 엔드포인트는 종종 API 키별로 더 높은 제한이 있습니다.

API 응답에는 현재 속도 제한 상태를 나타내는 헤더가 포함됩니다.

제한을 초과하면 HTTP 429 Too Many Requests 오류가 발생합니다.

처리 전략

  1. 사전 모니터링: 요청하기 전에 CB-RATELIMIT-REMAINING을 확인하십시오.
  2. 효율적인 API 사용:
  1. 지수 백오프: 429 오류를 수신하면 재시도하기 전에 대기하십시오.
  2. 서버 과부하를 방지하기 위해 지수 백오프(예: 1초 대기 후 2초, 4초, 8초 등, 지터 포함)를 구현하십시오.
  3. 실시간 데이터를 위한 WebSocket: 호가창 업데이트, 실시간 거래 및 티커의 경우 WebSocket 연결이 REST 폴링보다 훨씬 효율적입니다.

운영 우수성: 런북 원칙

강력한 운영 관행은 모든 거래 API 통합에 매우 중요합니다.

모니터링 및 알림

로깅

디버깅 및 감사를 위해 필수 정보를 로깅합니다.

보안 모범 사례

고급 주제 및 기술

실시간 데이터를 위한 WebSocket 피드

코인베이스 거래소는 낮은 지연 시간의 실시간 데이터를 위해 WebSocket 피드를 제공합니다.

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // 레벨 2 호가창 업데이트용
        "heartbeat", // 연결 유지 및 상태 모니터링용
        {
            "name": "ticker", // 특정 상품용 티커 채널
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // 상품 거래 상태 업데이트용
    ],
    // 사용자별 업데이트(주문, 잔액)의 경우 WebSocket 핸드셰이크 또는 초기 메시지 내에서 인증이 필요합니다.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." // 특정 채널에 인증이 필요한 경우
}

메시지 유형:

멱등성 및 client_oid

네트워크 문제 또는 재시도로 인한 중복 주문 제출을 방지하기 위해 POST /orders 요청에 client_oid 필드를 포함할 수 있습니다. 이는 클라이언트가 생성한 고유 식별자(예: UUID v4)여야 합니다.

자가 거래 방지 (STP)

주문 제출(`POST /orders`)의 stp 매개변수는 계정의 주문이 서로 매칭되는 것을 방지하는 데 도움이 됩니다. 일반적인 옵션은 다음과 같습니다.

결론

코인베이스 거래소 API는 개발자가 정교한 거래 애플리케이션 및 통합을 구축할 수 있는 포괄적인 툴킷을 제공합니다. 인증 마스터, 데이터 구조 이해, 속도 제한 준수 및 강력한 운영 관행 구현은 잠재력을 최대한 활용하는 데 핵심입니다. 실시간 데이터를 위한 WebSocket 피드 및 멱등성을 위한 client_oid와 같은 기능으로의 전환은 개발자가 빠르게 변화하는 암호화폐 거래 세계에서 탄력적이고 효율적인 시스템을 구축할 수 있도록 더욱 강화합니다. 새로운 기능, 엔드포인트 변경 및 모범 사례에 대한 최신 정보를 얻으려면 코인베이스의 공식 개발자 문서를 지속적으로 확인하는 것이 중요합니다.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드