Blog

Cómo Usar la API de Coinbase: Guía Paso a Paso

Rebecca Kovács

Rebecca Kovács

27 May 2025

Cómo Usar la API de Coinbase: Guía Paso a Paso

Coinbase, líder global en el panorama de intercambio de activos digitales, ofrece un sólido conjunto de Interfaces de Programación de Aplicaciones (APIs). Estas APIs son la columna vertebral para desarrolladores, traders algorítmicos e instituciones financieras que buscan integrarse programáticamente con los servicios de trading y datos de Coinbase. Esta guía proporciona una exploración técnica detallada de la API de Intercambio de Coinbase (Coinbase Exchange API), centrándose en la implementación práctica, las funcionalidades principales y las mejores prácticas operativas.

💡
¿Quieres una excelente herramienta de Pruebas de API que genere documentación de API hermosa?

¿Quieres una plataforma integrada Todo en Uno para que tu Equipo de Desarrolladores trabaje en conjunto con máxima productividad?

¡Apidog cumple todas tus demandas y reemplaza a Postman a un precio mucho más asequible!
button

Configuración Inicial y Autenticación

La interacción exitosa con la API de Intercambio de Coinbase comienza con la preparación de la cuenta, la gestión segura de las claves de API y una comprensión precisa del protocolo de autenticación.

Prerrequisitos de la Cuenta y Generación de Claves de API

Se requiere una cuenta verificada de Coinbase, típicamente una cuenta de Coinbase Advanced Trade o institucional. Las claves de API se generan dentro de la configuración de tu cuenta. Este proceso produce tres piezas de información críticas:

  1. Clave de API: Una cadena alfanumérica pública (por ejemplo, k7b9f2d7e8h1g3j4) que identifica tu aplicación.
  2. Secreto de API: Una cadena alfanumérica privada (por ejemplo, S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). Este secreto se muestra solo una vez al generarlo y debe almacenarse de forma segura.
  3. Frase de Contraseña (Passphrase): Una credencial de seguridad adicional (por ejemplo, mySecureP@$$phr@se2024!) creada por ti durante la generación de la clave.

Los permisos de la clave de API son granulares, lo que te permite restringir acciones (por ejemplo, solo vista, ejecución de operaciones, capacidades de retiro). Siempre adhiérete al principio de mínimo privilegio.

Autenticación de Solicitudes de API

La API de Intercambio de Coinbase emplea un mecanismo de autenticación basado en firma (HMAC-SHA256) para todos los endpoints privados y autenticados. Cada solicitud requiere varios encabezados HTTP personalizados:

La firma (CB-ACCESS-SIGN) se genera creando un hash HMAC-SHA256 de una cadena pre-hash. La cadena pre-hash es una concatenación de:

  1. La marca de tiempo (como cadena).
  2. El método HTTP en mayúsculas (por ejemplo, GET, POST).
  3. La ruta de la solicitud (por ejemplo, /orders, /products/BTC-USD/book).
  4. El cuerpo de la solicitud (para solicitudes POST; una cadena vacía si no hay cuerpo).

Ejemplo de construcción de cadena pre-hash (para una solicitud 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"}' // Cadena JSON, no un diccionario Python
prehash_string = timestamp + method + request_path + body_json_string

// El Secreto de API necesita ser decodificado en base64 antes de ser usado como clave HMAC.
// 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)

Las cadenas pre-hash construidas incorrectamente o las discrepancias en la marca de tiempo (asegúrate de que el reloj de tu servidor esté sincronizado vía NTP) son fuentes comunes de errores de autenticación (HTTP 401).

Bibliotecas Cliente y Entorno de Desarrollo

Las bibliotecas cliente oficiales y desarrolladas por la comunidad para lenguajes como Python (cbpro), Node.js (coinbase-pro-node), Java y Go abstraen estas complejidades de autenticación. Alternativamente, se pueden realizar solicitudes HTTP directas utilizando herramientas como curl o módulos cliente HTTP estándar, lo que requiere la implementación manual del proceso de firma.

El Entorno Sandbox para Pruebas

Coinbase proporciona un entorno Sandbox para desarrollo y pruebas, crucial antes de interactuar con mercados reales.

Propósito y Funcionalidad

El Sandbox refleja la funcionalidad de la API de producción, pero utiliza fondos de prueba y datos de mercado simulados. Permite:

Diferencias Clave con la Producción

Transición a Producción

Una estrategia de despliegue robusta incluye configuraciones distintas para Sandbox y Producción, que difieren principalmente en las credenciales de API y las URLs base. Las pruebas exhaustivas en el Sandbox son primordiales para prevenir errores con fondos reales.

Funcionalidades Principales de la API: Endpoints y Estructuras de Datos

La API se categoriza ampliamente en gestión de cuentas, recuperación de datos de mercado y operaciones de trading.

Gestión de Cuentas

Endpoints para consultar estados e historial de cuentas.

Obtención de Saldos de Cuentas (GET /accounts)
Recupera una lista de todas las cuentas de usuario (fiat y cripto) con sus saldos.
Fragmento de Respuesta de Ejemplo para una cuenta 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 es la cantidad total, available es lo que se puede usar para trading, y hold son fondos reservados para órdenes abiertas.

Historial de Cuenta / Libro Mayor (GET /accounts/{account_id}/ledger)
Proporciona una lista paginada de transacciones (operaciones, tarifas, transferencias) para una cuenta específica.
Parámetros de Consulta Típicos: before (cursor para paginación), after (cursor), limit (máximo 100, por defecto 100), start_date, end_date.
Fragmento de Ejemplo de Entrada del Libro Mayor:

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

Endpoints de Datos de Mercado

Acceso a información de mercado en tiempo real e histórica.

Productos / Pares de Trading (GET /products)
Lista todos los pares de trading disponibles y sus propiedades.
Fragmento de Ejemplo de Producto (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Tamaño mínimo de orden en moneda base
  "base_max_size": "200.0",  // Tamaño máximo de orden en moneda base
  "quote_increment": "0.01", // Unidad de cambio de precio más pequeña para la moneda de cotización
  "base_increment": "0.00000001", // Unidad de cambio de tamaño más pequeña para la moneda base
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Fondos mínimos para una orden de mercado en moneda de cotización
  "max_market_funds": "1000000", // Fondos máximos para una orden de mercado
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

Libros de Órdenes (GET /products/{product_id}/book)
Recupera el libro de órdenes actual para un producto.
Parámetros de Consulta: level (1, 2, o 3).
*   Nivel 1: Solo la mejor oferta de compra (bid) y venta (ask).
*   Nivel 2: Lista agregada de bids y asks en cada nivel de precio. (Máximo 50 entradas por lado).
*   Nivel 3: Libro de órdenes completo con órdenes individuales, no agregadas (requiere autenticación y puede tener límites de tasa más estrictos).
Fragmento de Ejemplo de Libro de Órdenes Nivel 2 (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [precio, tamaño, número de órdenes a este precio]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

Ticker del Producto (GET /products/{product_id}/ticker)
Información de instantánea sobre la última operación (tick), mejor bid/ask, y volumen de 24 horas.
Fragmento de Ejemplo de Ticker (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // Precio de la última operación
  "size": "0.005",    // Tamaño de la última operación
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // Volumen de trading de 24 horas en moneda base
  "time": "2023-10-26T10:06:15.234Z"
}

Tasas Históricas / Velas (GET /products/{product_id}/candles)
Recupera datos históricos de precios (OHLCV).
Parámetros de Consulta: start (marca de tiempo ISO 8601), end (ISO 8601), granularity (en segundos: 60, 300, 900, 3600, 21600, 86400). Máximo 300 velas por solicitud.
Datos de Ejemplo de Velas (granularidad de 1 hora):

[
  // [hora, bajo, alto, apertura, cierre, volumen]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // La hora es Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

Operaciones de Trading

Endpoints para colocar, gestionar y consultar órdenes.

Colocación de Órdenes (POST /orders)
Envía nuevas órdenes al motor de emparejamiento.
Parámetros Comunes del Cuerpo de la Solicitud:

{
  "client_oid": "my-unique-client-order-id-001", // Opcional: UUID para idempotencia
  "product_id": "BTC-USD",
  "side": "buy", // "buy" (compra) o "sell" (venta)
  "type": "limit", // "limit" (límite), "market" (mercado), o "stop" (stop) (las órdenes stop son más complejas)
  "price": "49500.00", // Requerido para órdenes límite
  "size": "0.0125", // Cantidad de moneda base a comprar/vender
  // "funds": "500.00", // Para órdenes de compra a mercado: cantidad de moneda de cotización a gastar
  "time_in_force": "GTC", // GTC (Válida hasta Cancelación), GTT (Válida hasta Hora), IOC (Inmediata o Cancelar), FOK (Ejecutar o Matar)
  // "cancel_after": "min" / "hour" / "day" (usado con GTT)
  "post_only": false, // Si es verdadero, la orden es rechazada si se emparejaría inmediatamente (asegura que sea maker)
  "stp": "dc" // Prevención de auto-negociación: "dc" (Disminuir y Cancelar), "co" (Cancelar la más Antigua), "cn" (Cancelar la más Nueva), "cb" (Cancelar Ambas)
}

Una colocación de orden exitosa devuelve los detalles de la orden, incluyendo el id asignado por el servidor.

Gestión de Órdenes

Ejecuciones (Fills) (GET /fills)
Recupera una lista paginada de tus operaciones ejecutadas (fills).
Parámetros de Consulta: order_id, product_id, before, after, limit.
Fragmento de Ejemplo de Ejecución:

{
  "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" para Maker, "T" para Taker
  "fee": "0.00000250", // Tarifa en moneda de cotización (USD para BTC-USD) o moneda base dependiendo de la API.
  "settled": true,
  "side": "buy"
}

El Motor de Emparejamiento

El motor de emparejamiento empareja órdenes de compra y venta basándose en un algoritmo de Prioridad Precio-Tiempo:

  1. Prioridad de Precio: Las órdenes con precios más favorables son priorizadas (precio más alto para bids, precio más bajo para asks).
  2. Prioridad de Tiempo: Entre órdenes al mismo precio, la orden enviada más temprano es priorizada.

Comprender esta lógica es vital para las estrategias de colocación de órdenes, la gestión del deslizamiento y la optimización de tarifas.

Límites de Tasa y Throttling

El acceso a la API está sujeto a límites de tasa para asegurar la estabilidad de la plataforma y el uso justo.

Tipos e Identificación

Los límites se aplican típicamente por clave de API, por dirección IP, y pueden variar por endpoint (por ejemplo, endpoints privados firmados vs. endpoints públicos sin firmar). Los endpoints públicos pueden tener límites como 3-10 solicitudes/segundo por IP. Los endpoints privados (firmados) a menudo tienen límites más altos, también por clave de API.

Las respuestas de la API incluyen encabezados que indican el estado actual del límite de tasa:

Exceder los límites resulta en un error HTTP 429 Too Many Requests.

Estrategias de Manejo

  1. Monitoreo Proactivo: Verifica CB-RATELIMIT-REMAINING antes de hacer solicitudes.
  2. Uso Eficiente de la API:
  1. Retroceso Exponencial (Exponential Backoff): Al recibir un error 429, espera antes de reintentar. Implementa un retroceso exponencial (por ejemplo, espera 1s, luego 2s, 4s, 8s, etc., con jitter) para evitar sobrecargar el servidor.
  2. WebSockets para Datos en Tiempo Real: Para actualizaciones del libro de órdenes, operaciones en vivo y tickers, las conexiones WebSocket son significativamente más eficientes que el sondeo REST.

Excelencia Operacional: Principios del Runbook

Las prácticas operacionales robustas son críticas para cualquier integración de API de trading.

Monitoreo y Alertas

Registro (Logging)

Registra información esencial para depuración y auditoría:

Mejores Prácticas de Seguridad

Temas y Técnicas Avanzadas

Feeds de WebSocket para Datos en Tiempo Real

Coinbase Exchange proporciona feeds de WebSocket para datos en tiempo real de baja latencia.

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // Para actualizaciones del libro de órdenes Nivel 2
        "heartbeat", // Para mantener la conexión viva y monitorear el estado
        {
            "name": "ticker", // Canal de ticker para productos específicos
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // Para actualizaciones sobre estados de trading de productos
    ],
    // Para actualizaciones específicas del usuario (órdenes, saldos), se requiere autenticación dentro del handshake de WebSocket o mensajes iniciales.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (si se necesita autenticación para ciertos canales)
}

Tipos de Mensaje:

Idempotencia y client_oid

Para prevenir envíos de órdenes duplicados debido a problemas de red o reintentos, las solicitudes POST /orders pueden incluir un campo client_oid. Este debe ser un identificador único (por ejemplo, UUID v4) generado por tu cliente.

Prevención de Auto-Negociación (STP)

El parámetro stp en la colocación de órdenes (POST /orders) ayuda a prevenir que las órdenes de una cuenta se emparejen entre sí. Las opciones típicamente incluyen:

Conclusión

La API de Intercambio de Coinbase proporciona un conjunto de herramientas completo para que los desarrolladores construyan aplicaciones e integraciones de trading sofisticadas. Dominar su autenticación, comprender sus estructuras de datos, respetar los límites de tasa e implementar prácticas operacionales robustas son clave para aprovechar todo su potencial. El cambio hacia los feeds de WebSocket para datos en tiempo real y características como client_oid para idempotencia empoderan aún más a los desarrolladores para crear sistemas resilientes y eficientes en el mundo acelerado del trading de criptomonedas. La atención continua a la documentación oficial para desarrolladores de Coinbase es crucial para mantenerse actualizado sobre nuevas características, cambios en los endpoints y mejores prácticas.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar