Serie sobre Binance API Parte 1 - Spot Trading con Postman
Serie sobre Binance API Parte 1 - Spot Trading con Postman
InicioArtículos

Serie sobre Binance API Parte 1 - Spot Trading con Postman

Avanzado
Published Jul 13, 2020Updated Jun 1, 2021
13m

Introducción

Comprender y utilizar una API para trading de criptomonedas puede abrir un mundo de posibilidades en lo referente a entradas y salidas de posiciones. Con un conocimiento simple de programación, podrás conectarte al backend de un exchange para automatizar tus estrategias de trading. Al esquivar la pagina web, tendrás una vía más rápida para acceder al motor de emparejamiento de órdenes (matching engine) para aplicaciones de alto rendimiento.

El propósito de esta serie es presentarte la REST API de Binance y enseñarte como interactuar con ella. Al concluir, deberías tener la confianza necesaria para hacer "queries" (consultas) de información sobre los mercados y tus posiciones, así como colocar un abanico de distintos tipos de órdenes.

En este artículo, utilizaremos Postman para comunicarnos con el exchange. Y no te preocupes: no arriesgaremos fondos reales.


Prerrequisitos

Claves de la Testnet

Para nuestro propósito, utilizaremos la testnet. Ésta nos brindará unos fondos sin valor real, para así poder experimentar con ellos. Éstos funcionan igual que las monedas y tokens reales, por lo que una vez que te sientas cómodo con la API, podrás empezar a usarla para tradear fondos de verdad.


  1. Para empezar, dirígete a la Spot Test Network.
  2. Para obtener acceso a la misma, deberás iniciar sesión con una cuenta de GitHub. Crea una si todavía no lo has hecho.
  3. Clica en Authenticate (autenticar) e inicia sesión a través de GitHub.
  4. Debajo de API Keys (claves API), se te informará de que todavía no tienes claves registradas. Clica en Generate HMAC_SHA256 Key para crear un par.
  5. En la siguiente pantalla, etiqueta las claves. Ponles el nombre que quieras y pulsa Generate (generar)
  6. Se te presentarán dos llaves: la API Key (clave API) y la Secret Key (clave secreta). Es importante que registres ambas. De lo contrario, deberás empezar el proceso de creación de claves de nuevo. Te recomendamos almacenarlas en la app de notas de tu equipo para poder copiar-pegar con facilidad después.
Nota: etiquetar tus claves es algo que vale la pena al utilizar el exchange real, para así poder gestionar claves distintas. Tu cuenta puede disponer de múltiples claves con diferentes permisos. Si estás manejando varios bots de trading, utilizar claves separadas con etiquetas descriptivas hace que resulte más fácil gestionar permisos o eliminar claves individuales sin cambiar todos tus bots.


Descargar e instalar Postman

Postman es una plataforma de Colaboración API. Es un punto de partida perfecto para nosotros –tendremos acceso a colecciones de requests en Binance, sin necesidad de escribir una sola línea de código.

El programa está disponible para Mac, Windows y Linux. Dirígete a la página de Descargas y descarga el archivo .zip.

Una vez se complete la descarga, localízalo en tu explorador de archivos e instálalo. Abre la aplicación, ¡y ya estás listo para arrancar! Ten en cuenta que puedes crear una cuenta para iniciar sesión, pero no es algo necesario. Si deseas saltarte ese paso, selecciona la opción que te permite hacerlo, al fondo de la ventana.


Crear el entorno

Llegado a este punto, deberías disponer de una interfaz que se parezca a la siguiente.



Lo primero será crear nuestro entorno. Se trata simplemente de una manera de añadir variables al conjunto de requests (peticiones) con los que trabajaremos. Para ello, primero deberemos obtener algunos datos del repositorio de GitHub de Binance. Dirígete aquí y descarga el archivo .zip.



La descarga no debería prolongarse mucho. Localízala con tu explorador de archivos y descomprímela. A continuación, dirígete de vuelta a Postman.



Clica en el icono del engranaje en la esquina superior derecha (tal como se muestra arriba). Entonces serás recibido por la ventana emergente Manage Environments (Administrar Entornos)
  1. Selecciona Import (importar), y navega hacia la carpeta que acabas de extraer (binance-postman-api). 
  2. Accede a ella, y a continuación entra en la carpeta "environments" (entornos).
  3. Te encontrarás con dos archivos (uno para la mainnet y otro para la testnet). El que nos interesa es binance_com_spot_testnet_api.postman_environment.json. Asegúrate de haber seleccionado el correcto, porque nuestras claves no funcionarán con el otro.



Ya casi estamos. Clica en Binance Spot Testnet API (API de la Testnet de Binance Spot), y podrás ver las variables debajo. Edita los dos parámetros subrayados en rojo, pegando en ellos las claves que has guardado antes. Clica en update (actualizar) y sal de la ventana emergente.



En esta pantalla, deja los campos de "timestamp" (sello de tiempo) y "signature" (firma) en blanco. Ambos valores se generarán de manera automática con cada "request" (solicitud).

Queda por hacer una cosa más. A la derecha del icono del engranaje que hemos clicado antes para configurar el entorno, encontrarás un menú desplegable que actualmente dice No Environment (sin entorno). Clica en él y selecciona Binance Spot Testnet API.


Importar la colección

Ahora nos dispondremos a importar la colección –la cual se trata de una extensa variedad de "requests" que hacen por nosotros el trabajo pesado cuando realizamos "calls" (llamadas). Los pasos para poder cargarla en nuestro entorno son:

  1. Clica Import (importar) en la esquina superior izquierda.
  2. En la ventana emergente, debajo de la pestaña File (archivo), selecciona Upload Files (cargar archivos).
  3. De nuevo, buscamos la carpeta binance-postman-api. Localízala y ábrela.
  4. Esta vez, en el subdirectorio, entra en "collections".
  5. De nuevo, encontrarás ahí dos archivos. Uno es para trabajar con la API de los futuros. Pero nosotros estamos operando con el del mercado spot, por lo que deberás seleccionar el archivo binance_spot_api_v1.postman_collection.json.
  6. Ahora, deberías ver una pantalla de confirmación que identifica que la importación presenta el formato de la Postman Collection.

Bajo la pestaña "Collections" (colecciones) a la izquierda de la ventana, advertirás que hay una carpeta con más de 100 "requests". ¡Felicidades! Ya estamos listos para arrancar. En la próxima sección, nos fijaremos en los tipos de "requests" que podemos realizar.


Realizar Requests (solicitudes)

Si amplías las carpetas que hay bajo la pestaña "Collections" (colecciones), verás que hay un montón de "requests" distintos que podemos realizar. Por el código de color, constatarás que existen tres tipos de métodos que podemos utilizar:


  • GET: El método GET se emplea para extraer elementos de un servidor. Lo utilizaremos para encontrar información sobre el balance de tu cuenta, precios de activos, etc.
  • POST: Generalmente, utilizamos el método POST para crear información en un servidor. Ésto es necesario para cosas como colocar órdenes, solicitar retiros, etc.
  • DELETE: El método DELETE es un "request" (solicitud) para que servidor elimine información. Resulta apropiado para la cancelación de órdenes.


Encuentra la lista de claves de cotización y reglas de trading

¡Ha llegado el momento de hacer nuestro primer request! Procederemos a obtener las claves de cotización que podemos negociar en el exchange y las reglas de trading:

GET /exchangeInfo


Para éste no se necesitan parámetros adicionales –podrías simplemente copiar y pegar el citado elemento en tu barra de direcciones, y obtendrías una respuesta. Pero en el caso de los requests que incluyen diversos parámetros, Postman facilita tanto su visión como modificación.

Para cargar este request, selecciona Market > Exchange Information. Entonces emergerá una pestaña como la siguiente:



Aquí no tendremos que hacer nada más, así que sigue adelante y dale a Send (enviar). A continuación, recibirás una respuesta:



En la sección subrayada superior, podrás ver algunos datos importantes:

  • el estado de la respuesta (200 significa que hemos tenido éxito, 400-499 significa que nos hemos encontrado con algún problema).
  • el tiempo transcurrido hasta recibir la respuesta (menos de un segundo)

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


En el segundo cuadro se halla el grueso de la respuesta. Al formato se le ha aplicado sangría (pretty-printing) para que resulte más cómodo a la vista. Éste contiene información sobre el propio exchange, así como los pares que puedes tradear y sus cantidades mínimas/máximas.

Puede parecer mucha información, pero el formato hace que resulte muy fácil trabajar con él programáticamente. Al escribir scripts para interactuar con el mismo, podrás escoger fácilmente propiedades específicas de elementos concretos de la respuesta.


Consulta los balances de la cuenta

Vamos a comprobar qué activos, y cuánta cantidad de cada uno, tenemos:

GET /account
Este elemento puede encontrarse debajo de Trade > Account Information. Clica en él, y te encontrarás con un esquema similar al anterior. También advertirás, sin embargo, que disponemos de dos nuevas variables: timestamp (sello temproal) y signature (firma). La firma es una medida de seguridad. Dado que ahora estamos solicitando información sensible, la misma demostrará que somos los dueños de la cuenta. 
El sello temporal informa al servidor del momento en que se realizó la solicitud (request). Debido a que las redes pueden ser inestables o sufrir paradas, el servidor podría recibir nuestra solicitud mucho después de lo esperado. En caso de que haya pasado demasiado tiempo, la solicitud será rechazada. Puedes especificar cuánto tiempo deseas esperar mediante el parámetro recvWindow, que por defecto se sitúa en 5000 milisegundos.
Postman se encarga por nosotros de generar ambos campos. Clica en "send" (enviar), y recibirás una respuesta. Debajo de "balances", deberías poder ver seis activos – BNB, BTC, BUSD, ETH, LTC y TRX. El balance se distribuirá entre free (libre) y locked (bloqueado). Todavía no hemos bloqueado nada, por lo que tus activos deberían aparecer todos como libres.

¡Felicidades por tu recién descubierta (no existente) riqueza!


Cómo obtener el precio actual de una clave de cotización

Podemos proceder a obtener el precio actual de un activo de distintas maneras. Tal vez, la más simple sea mediante la siguiente petición (request):

GET /api/v3/ticker/24hr
Como puedes imaginar, esto nos dará información sobre los precios de los activos de las últimas veinticuatro horas. Encuéntralo en Mercado > Estadísticas de cambio de precio de cotización 24 horas. El par predeterminado con el que nos saludan como variable de símbolo es BTCUSDT
Puedes enviarlo de inmediato para ver un desglose de la información de precios. También puedes cambiar el símbolo (a BNBUSD, LTCUSDT, etc.), o puedes desmarcar la variable para devolver datos para 40 pares.
También tenemos una llamada más simple (Market> Symbol Price Ticker) que devuelve el precio actual al que se tradea un activo:
GET /api/v3/price

Al igual que con el anterior, puedes cambiar la variable de símbolo o eliminarla por completo y obtener el último precio para todos los símbolos.


Comprobar la profundidad del libro de órdenes actual

La profundidad del libro de órdenes (también conocida como profundidad de mercado o DOM) puede decirnos mucho sobre el mercado. Vamos a hacer una llamada que devolverá información útil:

GET api/v3/depth

Cuando enviamos esto con los valores predeterminados (Mercado > Libro de órdenes), se nos envía una respuesta que nos informa sobre las ofertas y solicita BTCUSDT. El servidor de testnet no producirá tantos datos como el real, por lo que a continuación se muestra una captura de pantalla de lo que esperarías ver en un entorno real:



En la sección resaltada arriba, podemos ver la primera oferta. Dado que estamos viendo el libro de BTCUSDT, el número superior es el precio que alguien está dispuesto a pagar por tu BTC. A continuación se muestra la cantidad que están dispuestos a comprar. Lo que esto dice, por lo tanto, es que esta orden pide 0.999 BTC a una tasa de 9704.65 USDT por BTC. Si continuamos desplazándonos hacia abajo, veríamos disminuir el precio de oferta, lo que representa compradores que pagarían menos.

La oferta superior será, naturalmente, la más atractiva si estás buscando una buena inversión. Dicho esto, si estás tratando de vender en el mercado, digamos, 3 BTC, solo podrás vender 0.999 BTC al mejor precio. Deberás aceptar las ofertas posteriores (más baratas) hasta que se complete la totalidad de tu orden.



Sigue desplazándote y verás las demandas. Son funcionalmente similares a las ofertas, excepto que representan órdenes para vender BTC por USDT. 


Realiza una orden de prueba

Ahora vamos a publicar una orden de prueba.

POST api/v3/order/test
Aunque solo estamos usando fondos de Testnet, esta solicitud en realidad no realizará una orden. Puede resultar útil para probar órdenes antes de enviarlas. Encuéntrela en Trade > Probar nueva orden (TRADE).



Puedes ver que tenemos muchos más parámetros involucrados. Repasemos los marcados:


  • symbol: nos hemos encontrado con este anteriormente. Este es el par que deseas tradear.
  • side - aquí, estipularás si quieres COMPRAR o VENDER. Con el par BTCUSDT, BUY indica que deseas comprar BTC por USDT, mientras que con SELL venderás BTC por USDT.
  • type: el tipo de orden que deseas enviar. Valores posibles (detallados aquí):
    • LIMIT
    • MARKET
    • STOP_LOSS
    • STOP_LOSS_LIMIT
    • TAKE_PROFIT
    • TAKE_PROFIT_LIMIT
    • LIMIT_MAKER
  • timeInForce: este parámetro expresa cómo deseas que se ejecute la orden:
    • GTC (válida hasta que se cancele): quizás la configuración más popular, GTC se asegurará de que tu orden sea válida hasta que se complete o hasta que la canceles.
    • FOK (llenar o matar): FOK indica al exchange que ejecute una orden de una vez. Si el exchange no puede hacerlo, la orden se cancela inmediatamente.
    • IOC (inmediato o cancelado): todo o parte de la orden debe ejecutarse inmediatamente o se cancelará. A diferencia de FOK, las órdenes no se cancelan si se pueden completar parcialmente.
  • quantity: simplemente, la cantidad del activo que deseas comprar o vender.
  • prece: el precio al que deseas vender. Para el par BTCUSDT, esto se expresa en USDT.
  • newClientOrderId: un identificador de la orden. Este no es un campo obligatorio, pero puedes establecerlo en un identificador que facilitará la consulta más adelante. De lo contrario, el exchange lo genera aleatoriamente.
¡Bueno! Creemos ua orden de prueba ahora. Vamos a optar por los valores generados automáticamente: una orden límite para vender 0.1 BTC por USDT a $9000. Presiona Enviar. Si esto tuvo éxito, simplemente obtendremos {} como respuesta. 

 

Haz una orden real

Es hora de realizar una orden falsa real.

POST /api/v3/order
Ve a Trade > Nueva orden. Ya estás familiarizado con las ordenes de prueba, por lo que los parámetros aquí no te sorprenderán. Dejemos todos los valores como están, pero como somos permabulls, cambiaremos el precio al que estamos vendiendo a $40,000. Modifica el valor del precio para reflejar esto. Luego, presione Enviar.

Tu respuesta devuelve un montón de detalles sobre la orden si tiene éxito.


Verificar el estado de una orden abierta

Recibimos la confirmación de que la orden se realizó en la sección anterior, pero ¿qué pasa si queremos verificarla nuevamente más tarde? Tenemos algunas solicitudes a nuestra disposición.

GET /api/v3/openOrders
Lo encontrarás en Trade > Órdenes abiertas actuales (USER_DATA). BTCUSDT está seleccionado de forma predeterminada. Si presionas Enviar, obtendrás todas tus órdenes BTCUSDT abiertas (hasta ahora, solo deberías ver la que establecimos anteriormente). Puedes optar por no especificar un símbolo, que devolverá todas tus órdenes abiertas en su lugar.
GET /api/v3/allOrders
Trade > Todos los pedidos (USER_DATA) te brinda una descripción general de todos las órdenes, no solo las abiertas. Aquí, debes proporcionar un símbolo. orderId, startTime, endTime y limit son parámetros opcionales que pueden ayudarte a refinar tu búsqueda. Los dejaremos aquí, así que puedes desmarcarlos. Presiona Enviar y verás la misma respuesta que antes. Si tenías órdenes cerradas o canceladas, también los verás aquí. 


Por último, podemos consultar órdenes específicas con:

GET /api/v3/order
Consíguelo en Trade > Consulta de pedido (USER_DATA). Deberás proporcionar el orderId o el origClientOrderId (la etiqueta opcional "newClientOrderId" que puedes agregar a las órdenes). Desmarca orderId. Para origClientOrderId, proporcionaremos la etiqueta predeterminada anterior: "my_order_id_1". Completa el campo y presiona Enviar para obtener la respuesta.


Cancelar una orden

Después de un tiempo, podríamos decidir que el objetivo de $40,000 es demasiado optimista, por lo que queremos cancelarlo. En ese caso, usaríamos:

DELETE /api/v3/order
En Trade > Cancelar orden hay una solicitud que nos permitirá seleccionar órdenes para su cancelación. Desmarca orderId y newClientOrderId y pase "my_order_id_1" como el valor de origClientOrderId.
Cuando envíes esta solicitud, se devolverá la orden. Si te desplaza hacia abajo hasta "status", verás que de hecho está cancelada. Para confirmar esto, usa el endpoint GET / api / v3 / openOrders nuevamente (lo que te brinda una lista vacía) o GET / api / v3 / order con origClientOrderId.


Realiza una orden que se complete al instante

Nuestra orden anterior no se completó porque era una orden límite que solo se activaría cuando el precio de BTC alcanzara los $40,000. Con una orden de mercado, básicamente estamos diciendo "comprar / vender a cualquier precio al que se cotice actualmente el activo". Esta se llenará instantáneamente.

Para eso, volvamos a Trade > Nueva orden. Vamos a demostrar el tipo de respuesta (newOrderRespType), que es un parámetro que podemos modificar dependiendo de la respuesta que queramos obtener del servidor. Aquí hay tres opciones: ACK, RESULT o FULL; puedes ver ejemplos de cada respuesta aquí. Vamos a optar por ACK, que nos dará un simple reconocimiento de que se recibió la orden.

A continuación, puedes 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 nos da información mínima:



Puedes verificar que la orden se haya completado con el endpoint / api / v3 / allOrders.


Comprobando tus trades

Por último, veamos el endpoint para verificar tus trades:

GET /api/v3/myTrades
Se encuentra en Trade > Lista de trades de la cuenta (USER_DATA). Te permite verificar cada trade para un símbolo en particular. Si deseas ver todas tus operaciones para el símbolo predeterminado (BTCUSDT), simplemente desmarca startTime, endTime y fromId. La respuesta devolverá hasta 500 trades; simplemente ajusta el límite si deseas ver más.


Debugging con Postman

En Postman, es posible revelar más la solicitud y respuesta HTTP sin procesar.



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



Conclusión

El propósito de esta guía era presentarte suavemente la API de Binance sin escribir una sola línea de código. Si lo has seguido, ahora deberías tener una idea de cómo podemos solicitar y enviar información.

En las próximas entregas de esta serie, presentaremos algunos conceptos básicos de codificación que nos permiten automatizar la compra y venta de criptomonedas y otros activos digitales. 
¿Preguntas mientras tanto? Dirígete a nuestro creciente foro de la comunidad de desarrolladores de Binance o echa un vistazo a la documentación.