Blog

Hướng Dẫn Từng Bước Sử Dụng Coinbase API

Rebecca Kovács

Rebecca Kovács

27 tháng 5 2025

Hướng Dẫn Từng Bước Sử Dụng Coinbase API

Coinbase, một công ty hàng đầu toàn cầu trong lĩnh vực sàn giao dịch tài sản kỹ thuật số, cung cấp bộ giao diện lập trình ứng dụng (API) mạnh mẽ. Các API này là xương sống cho các nhà phát triển, nhà giao dịch thuật toán và các tổ chức tài chính muốn tích hợp theo chương trình với các dịch vụ giao dịch và dữ liệu của Coinbase. Hướng dẫn này cung cấp một khám phá kỹ thuật chi tiết về API Sàn giao dịch Coinbase, tập trung vào triển khai thực tế, các chức năng cốt lõi và các phương pháp vận hành tốt nhất.

💡
Bạn muốn một công cụ kiểm thử API tuyệt vời tạo ra tài liệu API đẹp mắt?

Bạn muốn một nền tảng tích hợp, All-in-One cho nhóm phát triển của bạn để làm việc cùng nhau với năng suất tối đa?

Apidog đáp ứng mọi yêu cầu của bạn, và thay thế Postman với mức giá hợp lý hơn nhiều!
nút

Thiết lập ban đầu và Xác thực

Tương tác thành công với API Sàn giao dịch Coinbase bắt đầu bằng việc chuẩn bị tài khoản, quản lý khóa API an toàn và hiểu rõ chính xác giao thức xác thực.

Các điều kiện tiên quyết về tài khoản và Tạo khóa API

Cần có một tài khoản Coinbase đã xác minh, thường là tài khoản Coinbase Advanced Trade hoặc tài khoản tổ chức. Khóa API được tạo trong cài đặt tài khoản của bạn. Quá trình này tạo ra ba thông tin quan trọng:

  1. Khóa API (API Key): Một chuỗi chữ và số công khai (ví dụ: k7b9f2d7e8h1g3j4) xác định ứng dụng của bạn.
  2. Bí mật API (API Secret): Một chuỗi chữ và số riêng tư (ví dụ: S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). Bí mật này chỉ hiển thị một lần duy nhất khi tạo và phải được lưu trữ an toàn.
  3. Mật khẩu truy cập (Passphrase): Một thông tin xác thực bảo mật bổ sung (ví dụ: mySecureP@$$phr@se2024!) do bạn tạo trong quá trình tạo khóa.

Quyền của khóa API là chi tiết, cho phép bạn hạn chế các hành động (ví dụ: chỉ xem, thực hiện giao dịch, khả năng rút tiền). Luôn tuân thủ nguyên tắc đặc quyền tối thiểu.

Xác thực yêu cầu API

API Sàn giao dịch Coinbase sử dụng cơ chế xác thực dựa trên chữ ký (HMAC-SHA256) cho tất cả các điểm cuối riêng tư, được xác thực. Mỗi yêu cầu cần một số tiêu đề HTTP tùy chỉnh:

Chữ ký (CB-ACCESS-SIGN) được tạo bằng cách tạo một băm HMAC-SHA256 của một chuỗi tiền băm (prehash string). Chuỗi tiền băm là sự nối tiếp của:

  1. Dấu thời gian (dưới dạng chuỗi).
  2. Phương thức HTTP viết hoa (ví dụ: GET, POST).
  3. Đường dẫn yêu cầu (ví dụ: /orders, /products/BTC-USD/book).
  4. Nội dung yêu cầu (đối với yêu cầu POST; một chuỗi rỗng nếu không có nội dung).

Ví dụ về cấu trúc chuỗi tiền băm (đối với yêu cầu 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)

Chuỗi tiền băm được cấu trúc không chính xác hoặc sự khác biệt về dấu thời gian (đảm bảo đồng hồ máy chủ của bạn được đồng bộ hóa qua NTP) là những nguồn phổ biến gây ra lỗi xác thực (HTTP 401).

Thư viện máy khách và Môi trường phát triển

Các thư viện máy khách chính thức và do cộng đồng phát triển cho các ngôn ngữ như Python (cbpro), Node.js (coinbase-pro-node), Java và Go giúp trừu tượng hóa những phức tạp về xác thực này. Ngoài ra, các yêu cầu HTTP trực tiếp có thể được thực hiện bằng các công cụ như curl hoặc các mô-đun máy khách HTTP tiêu chuẩn, yêu cầu triển khai thủ công quy trình ký.

Môi trường Sandbox để Kiểm thử

Coinbase cung cấp môi trường Sandbox để phát triển và kiểm thử, rất quan trọng trước khi tương tác với thị trường thực.

Mục đích và Chức năng

Sandbox phản ánh chức năng API sản xuất nhưng sử dụng quỹ thử nghiệm và dữ liệu thị trường mô phỏng. Nó cho phép:

Sự khác biệt chính so với Môi trường sản xuất

Chuyển đổi sang Môi trường sản xuất

Một chiến lược triển khai mạnh mẽ bao gồm các cấu hình riêng biệt cho Sandbox và Sản xuất, chủ yếu khác nhau về thông tin xác thực API và URL cơ sở. Kiểm thử kỹ lưỡng trong Sandbox là điều tối quan trọng để ngăn ngừa lỗi với quỹ thực.

Các chức năng cốt lõi của API: Điểm cuối và Cấu trúc dữ liệu

API được phân loại rộng rãi thành quản lý tài khoản, truy xuất dữ liệu thị trường và hoạt động giao dịch.

Quản lý tài khoản

Các điểm cuối để truy vấn trạng thái tài khoản và lịch sử.

Truy xuất Số dư tài khoản (GET /accounts)
Truy xuất danh sách tất cả các tài khoản người dùng (tiền pháp định và tiền mã hóa) với số dư của chúng.
Đoạn phản hồi ví dụ cho tài khoản 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 là tổng số tiền, available là số tiền có thể sử dụng để giao dịch, và hold là quỹ được giữ cho các lệnh mở.

Lịch sử tài khoản / Sổ cái (GET /accounts/{account_id}/ledger)
Cung cấp danh sách các giao dịch được phân trang (giao dịch, phí, chuyển khoản) cho một tài khoản cụ thể.
Các tham số truy vấn điển hình: before (con trỏ cho phân trang trước), after (con trỏ cho phân trang sau), limit (tối đa 100, mặc định 100), start_date, end_date.
Đoạn mục nhập Sổ cái ví dụ:

{
  "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"
  }
}

Các điểm cuối dữ liệu thị trường

Truy cập vào thông tin thị trường thời gian thực và lịch sử.

Sản phẩm / Cặp giao dịch (GET /products)
Liệt kê tất cả các cặp giao dịch có sẵn và các thuộc tính của chúng.
Đoạn sản phẩm ví dụ (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Minimum order size in base currency
  "base_max_size": "200.0",  // Maximum order size in base currency
  "quote_increment": "0.01", // Smallest price change unit for quote currency
  "base_increment": "0.00000001", // Smallest size change unit for base currency
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Minimum funds for a market order in quote currency
  "max_market_funds": "1000000", // Maximum funds for a market order
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

Sổ lệnh (GET /products/{product_id}/book)
Truy xuất sổ lệnh hiện tại cho một sản phẩm.
Các tham số truy vấn: level (1, 2, hoặc 3).
*   Level 1: Chỉ giá bid và ask tốt nhất.
*   Level 2: Danh sách tổng hợp các lệnh bid và ask ở mỗi mức giá. (Tối đa 50 mục nhập mỗi bên).
*   Level 3: Toàn bộ sổ lệnh với các lệnh riêng lẻ, không tổng hợp (yêu cầu xác thực và có thể có giới hạn tốc độ nghiêm ngặt hơn).
Đoạn sổ lệnh Level 2 ví dụ (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [price, size, num-orders-at-this-price]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

Ticker sản phẩm (GET /products/{product_id}/ticker)
Thông tin ảnh chụp nhanh về giao dịch cuối cùng (tick), giá bid/ask tốt nhất và khối lượng 24h.
Đoạn Ticker ví dụ (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // Last trade price
  "size": "0.005",    // Last trade size
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // 24-hour trading volume in base currency
  "time": "2023-10-26T10:06:15.234Z"
}

Tỷ giá lịch sử / Nến (GET /products/{product_id}/candles)
Truy xuất dữ liệu giá lịch sử (OHLCV).
Các tham số truy vấn: start (dấu thời gian ISO 8601), end (ISO 8601), granularity (theo giây: 60, 300, 900, 3600, 21600, 86400). Tối đa 300 nến mỗi yêu cầu.
Ví dụ dữ liệu nến (độ chi tiết 1 giờ):

[
  // [time, low, high, open, close, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // time is Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

Hoạt động giao dịch

Các điểm cuối để đặt, quản lý và truy vấn các lệnh.

Đặt lệnh (POST /orders)
Gửi các lệnh mới đến công cụ khớp lệnh.
Các tham số nội dung yêu cầu phổ biến:

{
  "client_oid": "my-unique-client-order-id-001", // Optional: UUID for idempotency
  "product_id": "BTC-USD",
  "side": "buy", // "buy" or "sell"
  "type": "limit", // "limit", "market", or "stop" (stop orders are more complex)
  "price": "49500.00", // Required for limit orders
  "size": "0.0125", // Amount of base currency to buy/sell
  // "funds": "500.00", // For market buy orders: amount of quote currency to spend
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (used with GTT)
  "post_only": false, // If true, order is rejected if it would immediately match (ensures maker)
  "stp": "dc" // Self-trade prevention: "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

Việc đặt lệnh thành công trả về chi tiết lệnh bao gồm id được gán bởi máy chủ.

Quản lý lệnh

Khớp lệnh (Fills) (GET /fills)
Truy xuất danh sách các giao dịch đã thực hiện (fills) của bạn được phân trang.
Các tham số truy vấn: order_id, product_id, before, after, limit.
Đoạn khớp lệnh ví dụ:

{
  "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" for Maker, "T" for Taker
  "fee": "0.00000250", // Fee in quote currency (USD for BTC-USD) or base currency depending on API.
  "settled": true,
  "side": "buy"
}

Công cụ khớp lệnh

Công cụ khớp lệnh ghép các lệnh mua và bán dựa trên thuật toán Ưu tiên Giá-Thời gian:

  1. Ưu tiên Giá: Các lệnh có giá ưu đãi hơn được ưu tiên (giá cao hơn cho lệnh bid, giá thấp hơn cho lệnh ask).
  2. Ưu tiên Thời gian: Trong số các lệnh cùng giá, lệnh được gửi sớm nhất được ưu tiên.

Hiểu rõ logic này là rất quan trọng cho các chiến lược đặt lệnh, quản lý trượt giá và tối ưu hóa phí.

Giới hạn tốc độ và Điều tiết

Truy cập API tuân theo giới hạn tốc độ để đảm bảo sự ổn định của nền tảng và việc sử dụng công bằng.

Các loại và Nhận dạng

Giới hạn thường được áp dụng cho mỗi khóa API, mỗi địa chỉ IP, và có thể thay đổi tùy theo điểm cuối (ví dụ: điểm cuối riêng tư được ký so với điểm cuối công khai không được ký). Các điểm cuối công khai có thể có giới hạn như 3-10 yêu cầu/giây cho mỗi IP. Các điểm cuối riêng tư (được ký) thường có giới hạn cao hơn, cũng áp dụng cho mỗi khóa API.

Các phản hồi API bao gồm các tiêu đề cho biết trạng thái giới hạn tốc độ hiện tại:

Vượt quá giới hạn sẽ dẫn đến lỗi HTTP 429 Too Many Requests.

Các chiến lược xử lý

  1. Giám sát chủ động: Kiểm tra CB-RATELIMIT-REMAINING trước khi thực hiện yêu cầu.
  2. Sử dụng API hiệu quả:
  1. Lùi lại theo cấp số nhân (Exponential Backoff): Khi nhận được lỗi 429, hãy đợi trước khi thử lại. Triển khai lùi lại theo cấp số nhân (ví dụ: đợi 1s, sau đó 2s, 4s, 8s, v.v., với jitter) để tránh làm quá tải máy chủ.
  2. WebSocket cho dữ liệu thời gian thực: Đối với cập nhật sổ lệnh, giao dịch trực tiếp và ticker, kết nối WebSocket hiệu quả hơn đáng kể so với thăm dò REST.

Vận hành xuất sắc: Nguyên tắc Sổ tay vận hành

Các thực hành vận hành mạnh mẽ là rất quan trọng đối với bất kỳ tích hợp API giao dịch nào.

Giám sát và Cảnh báo

Ghi nhật ký

Ghi nhật ký thông tin cần thiết để gỡ lỗi và kiểm tra:

Các phương pháp bảo mật tốt nhất

Các chủ đề và Kỹ thuật nâng cao

Nguồn cấp dữ liệu WebSocket cho dữ liệu thời gian thực

Sàn giao dịch Coinbase cung cấp nguồn cấp dữ liệu WebSocket cho dữ liệu thời gian thực, độ trễ thấp.

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // For Level 2 order book updates
        "heartbeat", // To keep connection alive and monitor status
        {
            "name": "ticker", // Ticker channel for specific products
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // For updates on product trading statuses
    ],
    // For user-specific updates (orders, balances), authentication is required within the WebSocket handshake or initial messages.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (if auth needed for certain channels)
}

Các loại tin nhắn:

Tính bất biến (Idempotency) và client_oid

Để ngăn chặn việc gửi lệnh trùng lặp do sự cố mạng hoặc thử lại, các yêu cầu POST /orders có thể bao gồm trường client_oid. Đây phải là một mã định danh duy nhất (ví dụ: UUID v4) được tạo bởi máy khách của bạn.

Ngăn chặn tự giao dịch (STP)

Tham số stp trong việc đặt lệnh (POST /orders) giúp ngăn các lệnh của một tài khoản khớp với nhau. Các tùy chọn thường bao gồm:

Kết luận

API Sàn giao dịch Coinbase cung cấp bộ công cụ toàn diện cho các nhà phát triển để xây dựng các ứng dụng và tích hợp giao dịch tinh vi. Nắm vững xác thực của nó, hiểu cấu trúc dữ liệu của nó, tôn trọng giới hạn tốc độ và triển khai các thực hành vận hành mạnh mẽ là chìa khóa để tận dụng tối đa tiềm năng của nó. Việc chuyển sang nguồn cấp dữ liệu WebSocket cho dữ liệu thời gian thực và các tính năng như client_oid cho tính bất biến tiếp tục trao quyền cho các nhà phát triển tạo ra các hệ thống bền vững và hiệu quả trong thế giới giao dịch tiền mã hóa đầy biến động. Việc liên tục chú ý đến tài liệu dành cho nhà phát triển chính thức của Coinbase là rất quan trọng để cập nhật các tính năng mới, thay đổi điểm cuối và các phương pháp tốt nhất.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống