Serie de artículos sobre la API de Binance, parte 1 — comercio spot con Postman

Introducción

Aprende a entender y usar API para transacciones de criptomonedas, para obtener muchas oportunidades de entrar y salir de posiciones. Incluso un conocimiento básico de codificación es suficiente para conectarse al servidor de la bolsa y automatizar estrategias de trading. Y al navegar por el sitio web, puedes acceder mucho más rápido a la herramienta de coincidencia de órdenes para aplicaciones de alto rendimiento.

El objetivo de esta serie es presentarte y enseñarte a trabajar con la API REST de Binance. Después de leer los artículos, podrás solicitar información sobre mercados y posiciones con confianza, así como realizar diferentes tipos de órdenes.

En este artículo, para conectarnos a la bolsa, utilizaremos Postman. No te preocupes, no arriesgaremos fondos reales.

Requisitos necesarios

Claves de la red de prueba

Para nuestros propósitos, utilizaremos la red de prueba. Esto permitirá experimentar con fondos que no tienen valor en el mundo real. Funcionan de la misma manera que las monedas y tokens reales, por lo que después de leer el artículo, podrás utilizar la API para comerciar con fondos reales.

1. Para comenzar, ve a la red de prueba spot.

2. Para acceder, inicia sesión en tu cuenta de GitHub. Crea una cuenta si no tienes una.

3. Haz clic en Authenticate (Autenticación) e inicia sesión a través de GitHub.

4. En la sección de claves API verás un mensaje indicando que no hay claves registradas. Haz clic en Generate HMAC_SHA256 Key (Generar clave HMAC_SHA256).

5. Luego asigna cualquier etiqueta a las claves y haz clic en Generar.

6. Recibirás una clave API y una clave secreta. Es importante anotarlas de inmediato. De lo contrario, tendrás que comenzar el proceso de creación de la clave nuevamente. Recomendamos guardar la clave API y la clave secreta en una aplicación de notas para poder copiarlas y pegarlas fácilmente.

Nota: al usar la bolsa real, es recomendable etiquetar las claves para gestionar las claves más fácilmente. Puede haber varias claves en la cuenta con diferentes permisos. Si utilizas varios bots de trading, las claves con etiquetas descriptivas facilitan la gestión de permisos y la eliminación de claves sin afectar a todos los bots.

Cargando e instalando Postman

Postman es una plataforma para interactuar con APIs. Es el punto de partida ideal: proporciona acceso a colecciones de solicitudes de Binance que se pueden probar sin escribir código.

El programa está disponible en Mac, Windows y Linux. Visita la página de descarga y descarga el archivo en formato zip.

Después de esto, búscalo en el explorador y instálalo. Inicia la aplicación y ¡puedes comenzar! Puedes optar por crear una cuenta para iniciar sesión. Para omitir este paso, selecciona la opción correspondiente en la parte inferior de la ventana.

Creación de un entorno

En esta etapa, debes tener una interfaz similar a la mostrada.

Primero, es necesario crear un entorno para agregar variables al conjunto de solicitudes con el que trabajaremos. Para ello, necesitas obtener información del repositorio de Binance en GitHub. Ve a este enlace y descarga el archivo en formato zip.

La descarga no tomará mucho tiempo. Encuentra el archivo en el explorador y descomprímelo. Luego, vuelve a Postman.

Haz clic en el icono de configuración en la esquina superior derecha, como se muestra en la imagen anterior. Aparecerá una ventana emergente para gestionar entornos.

1. Haz clic en Importar y ve a la carpeta que acabas de extraer (binance-postman-api).

2. Ábrela y luego abre la carpeta de entornos.

3. Ahí habrá dos archivos (uno para la red principal y uno para la de pruebas). Necesitamos el archivo binance_com_spot_testnet_api.postman_environment.json. Asegúrate de seleccionar el archivo correcto, porque de lo contrario las claves no funcionarán.

Casi listo. Haz clic en Binance Spot Testnet API (API de la red de prueba spot de Binance). Verás las variables, como en la imagen de abajo. Inserta las claves que guardaste anteriormente en los dos parámetros resaltados en rojo. Haz clic en Actualizar y cierra esta ventana.

Deja los campos timestamp (marca de tiempo) y signature (firma) vacíos. Estos valores se generarán automáticamente con cada solicitud.

Queda muy poco. A la derecha del icono de configuración en el que hicimos clic para configurar el entorno, hay un menú desplegable que dice No Environment (Sin entorno). Haz clic en él y selecciona Binance Spot Testnet API (API de la red de prueba spot de Binance).

Importación de la colección

Ahora necesitamos importar una colección: un extenso conjunto de solicitudes que, al enviar la llamada, hará el trabajo pesado por nosotros. Para cargar la colección en el entorno:

1. Haz clic en Importar en la esquina superior izquierda.

2. En la ventana emergente, en la pestaña Archivo, selecciona Subir archivos.

3. Encuentra la carpeta binance-postman-api y ábrela.

4. Esta vez ingresa a la carpeta de colecciones.

5. Ahí habrá dos archivos. Uno es para trabajar con la API de futuros, el otro es para trabajar con la spot. Necesitamos la spot, así que selecciona el archivo binance_spot_api_v1.postman_collection.json.

6. En la pantalla aparecerá una ventana de confirmación que indicará que la importación se está realizando en formato Postman Collection. Haz clic en Importar.

En la pestaña Importar, a la izquierda aparecerá una carpeta con más de 100 solicitudes. ¡Felicidades, ahora puedes empezar! En la siguiente sección, revisaremos diferentes tipos de solicitudes.

Envío de solicitudes

Si expandes las carpetas en la pestaña Colecciones, verás muchas solicitudes disponibles. Tres tipos de métodos, resaltados en diferentes colores, que se pueden usar:

• GET: el método GET se utiliza para obtener datos del servidor. Este método ayudará a encontrar información sobre el saldo de la cuenta, precios de activos, etc.

• POST: por lo general, el método POST se utiliza para crear información en el servidor. Este método es necesario para realizar órdenes, solicitudes de retiro y más.

• DELETE: el método DELETE solicita al servidor que elimine información. Este método será útil para cancelar órdenes.

Búsqueda de pares de negociación y reglas de comercio

¡Es hora de crear la primera solicitud! Necesitamos obtener información sobre los pares de negociación que se pueden negociar en la bolsa y las reglas de comercio:

GET /exchangeInfo

Para esta solicitud no se necesitan parámetros adicionales: se puede copiar y pegar en la barra de direcciones para obtener una respuesta. Sin embargo, si hay varios parámetros en las solicitudes, Postman permite visualizarlos y cambiarlos fácilmente.

Para cargar esta solicitud, selecciona Mercado > Información de la Bolsa (Market > Exchange Information). Se abrirá la siguiente pestaña:

No es necesario hacer nada más, simplemente haz clic en Enviar.

En la parte superior de la sección resaltada hay información importante:

• estado de la respuesta (200 significa éxito, 400–499 significa error);

• tiempo de respuesta (menos de un segundo);

• tamaño de la respuesta (~22 KB).

En la segunda sección resaltada se encuentra la parte principal de la respuesta. El texto se presenta de manera estructurada para que sea más fácil de leer. Contiene información sobre la bolsa, así como sobre los pares que se pueden negociar y sus montos mínimos/máximos.

Parece que hay mucha información, pero este formato facilita mucho el trabajo de los programadores. Al escribir scripts para interactuar, será fácil encontrar propiedades de ciertos elementos.

Verificación del saldo de la cuenta

Vamos a comprobar qué activos tenemos y cuántos hay:

GET /account

La solicitud se puede encontrar en la sección Comercio > Información de la Cuenta (Trade > Account Information). Haz clic en ella: se abrirá una página similar a la anterior. Sin embargo, habrá dos nuevas variables: timestamp (marca de tiempo) y signature (firma). La firma es una medida de seguridad. Dado que estás solicitando información confidencial, es necesario confirmar que eres el propietario de la cuenta.

La marca de tiempo informa al servidor cuándo se envió la solicitud. Debido a problemas de red, el servidor puede recibir la solicitud mucho más tarde de lo previsto. Si pasa demasiado tiempo, la solicitud será rechazada. Se puede especificar un tiempo de espera preferido mediante el parámetro recvWindow, que por defecto es de 5000 milisegundos.

Postman genera ambos campos en nombre del usuario. Haz clic en Enviar para obtener una respuesta. En la sección de saldos habrá seis activos: BNB, BTC, BUSD, ETH, LTC y TRX. El saldo se dividirá en disponible y bloqueado. No hemos bloqueado nada, así que todos los activos deben estar disponibles.

¡Felicidades por la (inexistente) riqueza!

Cómo saber el precio actual del par de negociación

Puedes averiguar el precio actual de un activo de varias maneras. La más simple es usar la siguiente solicitud:

GET /api/v3/ticker/24hr

Esta solicitud proporciona información sobre los precios de los activos en las últimas 24 horas. Encuéntralo en la sección Mercado > Estadísticas de Cambio de Precio de 24 horas (Market > 24hr Ticker Price Change Statistics). Por defecto, el par de negociación es BTCUSDT.

Puedes enviar la solicitud de inmediato para ver información detallada sobre los precios. También puedes cambiar el par de negociación (a BNBBUSD, LTCUSDT y otros) o desmarcar la variable para obtener datos para 40 pares.

También hay una solicitud más simple en Mercado > Ticker de Precio de Símbolo (Market > Symbol Price Ticker) que muestra el precio actual del activo:

GET /api/v3/price

Al igual que en el caso anterior, puedes cambiar la variable del par de negociación o eliminarla completamente y obtener el último precio para todos los pares.

Verificación de la profundidad actual del libro de órdenes

La profundidad del libro de órdenes (también llamada profundidad del mercado o DOM) puede decir mucho sobre el mercado. Para obtener información útil, debes hacer la solicitud:

GET api/v3/depth

Cuando lo enviamos con los valores predeterminados (Mercado > Libro de Órdenes), obtenemos una respuesta con los precios de compra y venta de BTCUSDT. El servidor de la red de prueba no proporciona tantos datos como el servidor de la red real, así que aquí hay una captura de pantalla de lo que se puede ver en un entorno real:

En la sección resaltada arriba se muestra el primer precio de compra. Dado que estamos mirando el libro de BTCUSDT, el número superior es el precio que alguien está dispuesto a pagar por tu BTC. Debajo se indica la cantidad que este usuario desea comprar. Así que la orden solicita 0.999 BTC a un precio de 9704.65 USDT por BTC. Luego, el precio de venta disminuye: más abajo en la lista hay compradores que quieren pagar menos.

La mejor oferta será la más ventajosa. Sin embargo, si intentas vender, por ejemplo, 3 BTC, solo podrás vender 0.999 BTC al mejor precio. Tendrás que aceptar las siguientes (más baratas) ofertas hasta que la orden se ejecute completamente.

A continuación, encontrarás información sobre los precios de venta. Son similares a los precios de compra, excepto que en esta sección se presentan órdenes de venta de BTC por USDT.

Colocación de una orden de prueba

Ahora vamos a colocar una orden de prueba.

POST api/v3/order/test

Aunque estamos utilizando fondos de la red de prueba, esta solicitud en realidad no coloca una orden. Esto permite probar las órdenes antes de su colocación real. La solicitud se encuentra en la sección Comercio > Test New Order (TRADE) (Comercio > Prueba de una nueva orden (TRADE)).

Esta vez hay muchos más parámetros involucrados. Vamos a revisar los marcados:

• symbol (par de negociación) — ya nos hemos encontrado con él anteriormente. Es el par con el que deseas comerciar.

• side (acción) — aquí debes seleccionar BUY (comprar) o SELL (vender). En el par BTCUSDT, BUY permite comprar BTC por USDT y SELL permite vender BTC por USDT.

• type (tipo) — el tipo de orden que deseas colocar. Los valores posibles (más detalles en este enlace):

  • LIMIT

  • MARKET

  • STOP_LOSS

  • STOP_LOSS_LIMIT

  • TAKE_PROFIT

  • TAKE_PROFIT_LIMIT

  • LIMIT_MAKER

• timeInForce — este parámetro determina la forma en que se ejecuta la orden:

  • GTC (vigente hasta cancelación) — la opción más popular. La orden estará vigente hasta que se ejecute o hasta que la canceles.

  • FOK (ejecutar o cancelar) — FOK le indica a la bolsa que ejecute la orden de inmediato y en su totalidad. Si la bolsa no puede hacerlo, la orden se cancela de inmediato.

  • IOC (inmediatamente o cancelar) — la orden debe ejecutarse de inmediato, total o parcialmente. A diferencia de FOK, las órdenes no se cancelan si solo pueden ejecutarse parcialmente.

• quantity (cantidad) — la cantidad de activo que deseas comprar o vender.

• price (precio) — el precio al que deseas vender. Para el par BTCUSDT se expresa en USDT.

• newClientOrderId — identificador de la orden. Este campo es opcional, pero se puede indicar un identificador que facilite la solicitud más adelante. De lo contrario, la bolsa generará un ID aleatorio.

Ahora vamos a crear una orden de prueba. Usaremos valores generados automáticamente: una orden límite para vender 0.1 BTC por USDT a un precio de $9000. Haz clic en Enviar. Si tiene éxito, recibiremos {} como respuesta.

Colocación de una orden real

Es hora de aprender a colocar una orden real.

POST /api/v3/order

Ve a la sección Comercio > Nueva Orden (Trade > New Order). Los parámetros aquí son los mismos que los de las órdenes de prueba. Vamos a dejar todos los valores como están, pero cambiaremos el precio de venta a $40,000. Ajusta el precio y haz clic en Enviar.

Si tiene éxito, recibirás una respuesta con detalles sobre la orden.

Verificación del estado de una orden abierta

En la sección anterior ya recibimos la confirmación de que la orden fue colocada, pero ¿cómo verificarla ahora? Para esto hay varias solicitudes.

GET /api/v3/openOrders

La solicitud se encuentra en la sección Comercio > Órdenes Abiertas Actuales (Trade > Current Open Orders). Por defecto, el par seleccionado es BTCUSDT. Si haces clic en Enviar, recibirás información sobre tus órdenes abiertas de BTCUSDT (en esta etapa solo verás la que colocamos anteriormente). Si no se especifica el par de negociación, se recibirá información sobre todas las órdenes abiertas.

GET /api/v3/allOrders

El comercio > Todas las Órdenes (Trade > All Orders) dará una visión general de todas las órdenes, no solo de las abiertas. Aquí se debe especificar el par de negociación. orderId, startTime, endTime y limit son parámetros opcionales que ayudarán a refinar la búsqueda. Ahora no son necesarios, así que desactívalos. Haz clic en Enviar: aparecerá la misma respuesta que antes. Aquí también se mostrarán las órdenes cerradas y canceladas, si las hay.

Finalmente, puedes solicitar órdenes específicas usando:

GET /api/v3/order

La solicitud se encuentra en la sección Comercio > Consultar Orden (Trade > Query Order). Es necesario especificar orderId u origClientOrderId (la etiqueta opcional "newClientOrderId" que se puede agregar a las órdenes). Desmarca orderId. Para origClientOrderId, pongamos la etiqueta por defecto: "my_order_id_1". Completa el campo y haz clic en Enviar.

Cancelación de una orden

Si después de un tiempo el objetivo de $40,000 parece demasiado optimista, la orden se puede cancelar. En este caso, debes usar:

DELETE /api/v3/order

Esta es una solicitud en la sección Comercio > Cancelar Orden (Trade > Cancel Order), que permitirá seleccionar órdenes para cancelar. Desmarca los parámetros orderId y newClientOrderId y establece el valor "my_order_id_1" para origClientOrderId.

Después de enviar la solicitud, recibirás una respuesta con información sobre la orden. Si desplazas hacia abajo hasta la sección status (estado), podrás ver que realmente está cancelada. Para confirmar esto, usa nuevamente el endpoint GET /api/v3/openOrders (te dará una lista vacía) o GET /api/v3/order con origClientOrderId.

Colocación de una orden con ejecución instantánea

La orden limitada anterior no se ejecutó porque solo se activaría al alcanzar un precio de BTC de $40,000. Una orden de mercado permite comprar/vender a cualquier precio actual. Se ejecuta instantáneamente.

Para ello, volvamos a la sección Comercio > Nueva Orden (Trade > New Order). Demostraremos el tipo de respuesta (newOrderRespType): un parámetro que se ajusta según la respuesta deseada. Hay tres opciones: ACK, RESULT o FULL. Ejemplos de cada solicitud se encuentran en este enlace. Elegiremos ACK, que simplemente confirmará que la orden fue recibida.

A continuación, se puede ver que estamos a punto de enviar una orden de mercado para vender BNB por BUSD al precio de mercado actual.

Ten en cuenta que la respuesta contiene muy poca información:

Puedes asegurarte de que la orden se ejecutó mediante /api/v3/allOrders.

Verificación de transacciones

Ahora revisemos la solicitud para verificar transacciones:

GET /api/v3/myTrades

Se encuentra en la sección Comercio > Lista de Transacciones de la Cuenta (Trade > Account Trade List). Esta solicitud permite verificar cada transacción con un par de negociación específico. Para ver las transacciones con el par de negociación por defecto (BTCUSDT), simplemente desmarca los parámetros startTime, endTime y fromId. La respuesta contendrá hasta 500 transacciones: cambia el parámetro limit (límite) para ver más.

Depuración con Postman

En Postman, puedes desplegar adicionalmente la solicitud HTTP en crudo y la respuesta.

Este menú abrirá la consola de Postman, que mostrará los detalles de cada solicitud.

Resumen

El objetivo de esta guía era mostrarte cómo trabajar con la API de Binance sin escribir código. Ahora sabes cómo solicitar y enviar información.

En las siguientes partes de esta serie, te presentaremos conceptos básicos de codificación que automatizan la compra y venta de criptomonedas y otros activos digitales.

Si tienes alguna pregunta, ve a la comunidad de desarrolladores de Binance o revisa la documentación.