Série Sobre API da Binance Parte I – Spot Trading com Postman

Introdução

Aprender a usar uma API para trading de criptomoedas pode abrir um mundo de possibilidades no que diz respeito a entrada e saída de posições. Com um conhecimento básico de codificação, você pode se conectar ao backend de uma exchange (corretora) e automatizar suas estratégias de trading. Ao ignorar a página da web, você terá uma maneira mais rápida de acessar o mecanismo de correspondência para aplicativos de alto desempenho.

O objetivo desta série é apresentar a API "REST" da Binance e ensiná-lo a interagir com ela. No final, você deve estar pronto para consultar informações sobre os mercados e sua posição e criar vários tipos de ordens.

Neste artigo, usaremos o programa Postman para interagir com a exchange (corretora). Não se preocupe – não precisaremos arriscar nenhum valor em dinheiro.

Pré-requisitos

Chaves de testnet

Para nosso tutorial, usaremos a testnet (rede de testes). Assim, podemos usar fundos sem nenhum valor em nossos experimentos. Eles funcionam exatamente da mesma maneira que moedas e tokens reais, então, quando você se sentir confortável com a API, pode começar a usá-la para trades de verdade.

Primeiro, vamos acessar a rede Spot Test Network.
Para isso, é preciso fazer login com uma conta GitHub. Crie uma nova conta, caso ainda não tenha.
Clique em Autenticar e faça login no GitHub.
Em API Keys (Chaves API), você verá que não tem chaves registradas. Clique em Generate HMAC_SHA256 Key para criar um par.
Na próxima tela, nomeie as chaves. Escolha o nome que preferir e clique em Generate (Gerar).
Você receberá duas chaves: a API Key (Chave API) e a Secret Key (Chave Secreta). É importante que você salve ambas. Se esquecer de salvá-las, você deverá iniciar o processo de criação de chaves novamente. Recomendamos armazená-las em um aplicativo de notas para copiar e colar facilmente.

Observação: ao usar uma exchange (corretora) real, recomendamos que você nomeie as chaves para que possa gerenciar melhor todas as chaves diferentes. Sua conta pode ter várias chaves com permissões diferentes. Se estiver executando vários bots de trading, o uso de chaves separadas com nomes descritivos facilita o gerenciamento de permissões ou a exclusão de chaves, sem precisar alterar todos os seus bots.

Baixando e instalando o Postman

Postman é uma plataforma colaborativa de API. A plataforma é ponto de partida perfeito para nós – teremos acesso a arquivos usados na Binance que testaremos sem precisar escrever nenhum código de programação.

O programa está disponível para Mac,Windows e Linux. Acesse a página de Downloads e baixe o arquivo .zip.

Quando concluir o download, localize-o em seus arquivos e instale-o. Abra o aplicativo e pronto! Se preferir, você pode criar uma conta para fazer login, mas não é necessário. Se quiser pular essa etapa, basta selecionar a opção na parte inferior da janela.

Criando o ambiente

Nesse estágio, você deve ver uma interface semelhante à imagem abaixo.

Primeiro, vamos criar nosso ambiente de trabalho. Esta é apenas uma maneira de adicionar variáveis ao conjunto de solicitações com as quais trabalharemos. Para isso, precisamos de algumas informações do repositório da Binance no GitHub. Acesse este link e faça o download do arquivo .zip.

O download não deve demorar muito. Encontre-o em seus arquivos e descompacte-o. Agora podemos voltar ao Postman.

Clique no ícone de engrenagem no canto superior direito (conforme ilustração acima). Será exibida a janela Manage Environments (Gerenciar Ambientes).

Selecione Import (Importar) e encontre a pasta de destino do arquivo extraído (binance-postman-api).
Abra ela e acesse a pasta environments (ambientes).
Aqui você verá dois arquivos (um para a mainnet e outro para a testnet). O que estamos procurando é o binance_com_spot_testnet_api.postman_environment.json. Certifique-se de selecionar o correto pois as chaves não funcionam com a outra opção.

Quase lá. Clique em Binance Spot Testnet API (API de Testnet da Binance Spot) e você verá as variáveis abaixo. Edite os dois parâmetros destacados em vermelho e cole as chaves que você salvou anteriormente. Clique em atualizar e feche a janela.

Nesta tela, deixe os campos timestamp (registro de data/hora) e signature (assinatura) em branco. Esses dois valores serão criados automaticamente a cada request (solicitação) da API.

Agora, a última etapa. À direita do ícone de engrenagem em que clicamos para configurar o ambiente, você verá um menu suspenso que diz No Environment (Sem Ambiente). Clique nele e selecione Binance Spot Testnet API.

Importando a coleção

Vamos importar a coleção – a coleção é uma ampla variedade de requests (solicitações) que fazem o trabalho pesado quando fazemos as "calls" (chamadas). Para carregá-la em nosso ambiente:

Clique em Import (Importar) no canto superior esquerdo.
Nesta janela (pop-up), na aba File (arquivos), selecione Upload Files (Carregar Arquivos).
Procure novamente pela pasta com o arquivo binance-postman-api. Abra-o.
Desta vez, abra collections (coleções) no subdiretório.
Novamente, você verá dois arquivos. Um deles é para a API de futuros. Mas estamos trabalhando com a API Spot, então selecione o arquivo binance_spot_api_v1.postman_collection.json.
Será exibida uma tela de confirmação que identifica a importação feita no formato Postman Collection. Selecione Import para importar.

Na seção Collections à esquerda da janela, você verá uma pasta com mais de 100 requests. Parabéns! Estamos prontos para prosseguir. Na próxima seção, veremos os tipos de requests que podemos fazer.

Criando requests (solicitações)

Ao expandir as pastas na seção Collections, veremos que podemos fazer muitos requests diferentes. Com base nas cores exibidas, observamos que existem três tipos de métodos disponíveis:

GET: O método GET é usado para extrair elementos de um servidor. Usaremos isso para descobrir informações sobre o saldo da sua conta, preços de ativos, etc.
POST: Geralmente, usamos o método POST para criar informações em um servidor. Ele é necessário para tarefas como criação de ordens, solicitação de saques, etc.
DELETE: O método DELETE é um request usado para excluir informações do servidor. É um método útil para o cancelamento de ordens.

Encontrando a lista de símbolos e as regras de trading

É hora do nosso primeiro request! Agora vamos obter os símbolos que podemos negociar na corretora e as regras de trading:

GET /exchangeInfo

Esta etapa não requer nenhum parâmetro adicional – você poderia copiar e colar isso na sua barra de endereço para obter uma resposta. No entanto, para casos de requests que incluem vários parâmetros, o Postman facilita tanto a visualização quanto a modificação.

Para carregar essa solicitação, selecione Market > Exchange Information. Será exibida a seguinte aba:

Não precisamos fazer mais nada aqui. Clique em Send (Enviar). A seguir, você receberá uma resposta:

A seção destacada na parte superior, mostra algumas informações importantes:

o status da resposta (200 significa que o processo foi bem sucedido, 400-499 quer dizer que houve um problema)
o tempo necessário para receber a resposta (menos de um segundo)
o tamanho da resposta (~22 KB).

Na segunda caixa destacada, estão os detalhes da resposta. A exibição é estruturada de uma forma que fique mais clara e fácil de ler. Contém informações sobre a exchange em si, bem como os pares que você pode negociar e seus valores mínimo/máximo.

Parece muita informação, mas esse formato facilita o trabalho de programação. Ao escrever scripts de interação, podemos facilmente selecionar propriedades específicas de determinados elementos da resposta.

Conferindo os saldos da conta

Vamos verificar quais ativos temos e o saldo de cada um:

GET /account

Este método pode ser encontrado em Trade > Account Information. Clique nele. Será exibido um layout semelhante ao anterior. Veremos, no entanto, que agora temos duas novas variáveis: timestamp (registro de tempo) e signature (assinatura). A assinatura é uma medida de segurança. Como estamos solicitando informações confidenciais, a assinatura é usada para provar a titularidade da conta.

O timestamp informa ao servidor sobre o envio do request (solicitação). Como as redes podem não ser confiáveis ou enfrentar períodos de inatividade, é possível que o servidor receba o request muito mais tarde do que o pretendido. Se passar muito tempo, o servidor rejeitará o request. É possível especificar o tempo limite de espera com o parâmetro recvWindow, cujo padrão é de 5000 milissegundos (5 segundos).

O Postman cuida da geração de ambos os campos para nós. Clique em enviar e você receberá uma resposta. Em saldos, você deve ver seis ativos – BNB, BTC, BUSD, ETH, LTC e TRX. O saldo será classificado como free (livre) e locked (bloqueado). Ainda não bloqueamos nenhum, então seus ativos devem estar todos livres.

Parabéns pela sua riqueza recém-descoberta (inexistente)!

Como obter o preço atual de um símbolo

Existem diferentes maneiras de se obter o preço atual de um ativo. Talvez a mais simples seja com o seguinte request:

GET /api/v3/ticker/24hr

Esse método nos fornecerá informações sobre os preços dos ativos nas últimas 24 horas. Podemos encontrá-lo em Market > 24hr Ticker Price Change Statistics (Mercado > Estatísticas de Variação de Preço do Ticker em 24h). O par padrão para a variável de símbolo é o BTCUSDT.

Você já pode enviar esse método e obter informações detalhadas sobre o preço. Também é possível alterar o símbolo (para BNBBUSD, LTCUSDT, etc.) ou você pode desmarcar a variável para obter dados de 40 pares.

Temos também uma call mais simples (Market > Symbol Price Ticker) que retorna o preço atual pelo qual um ativo está sendo negociado:

GET /api/v3/price

Como na anterior, você pode alterar a variável do símbolo ou removê-la completamente e obter o preço mais recente para todos os símbolos.

Conferindo a profundidade atual do livro de ordens

A profundidade do livro de ordens (também conhecida como profundidade de mercado ou DOM) pode nos dizer muito sobre o mercado. Faremos uma call que retornará algumas informações úteis:

GET api/v3/depth

Quando enviamos isso com os valores padrão (Mercado > Livro de Ordens), recebemos uma resposta que nos informa sobre as ofertas de compra e venda de BTCUSDT. O servidor de testnet não produzirá tantos dados quanto o real. Abaixo, temos uma captura de tela do que geralmente vemos em um ambiente real:

Na seção destacada acima, podemos ver a primeira oferta. Como estamos analisando o livro do par BTCUSDT, o número superior é o preço que alguém está disposto a pagar pelo BTC. O valor abaixo representa a quantia de moedas da proposta de compra. Portanto, essa ordem está pedindo 0,999 BTC ao preço de 9704,65 USDT por BTC. Ao descer a tela, veremos ofertas com preços menores – que representam compradores dispostos a pagar menos.

A oferta do topo será naturalmente a mais atraente em termos de preço. Dito isso, se você está tentando vender, por exemplo, 3 BTC, você só poderá vender 0,999 BTC pelo melhor preço. Será necessário aceitar as ofertas subsequentes (mais baratas) até que a sua ordem de venda de 3 BTC seja totalmente atendida.

Continue descendo e você verá as ofertas de venda. Funcionalmente, elas são semelhantes às ofertas de compra mas, obviamente, representam ordens de venda de BTC por USDT.

Criando uma ordem de teste

Agora vamos criar uma ordem de teste.

POST api/v3/order/test

Mesmo que estejamos usando apenas os fundos da testnet, essa solicitação não criará, de fato, uma ordem no livro de ordens. Esse método é útil para testar ordens antes de realmente enviá-las. Acesse Trade > Test New Order (TRADE).

Você verá que temos muitos outros parâmetros envolvidos. Vamos examinar os parâmetros selecionados:

symbol – Já discutimos sobre o símbolo anteriormente. Este é o par selecionado para o trade.
side – aqui, definimos se queremos comprar (BUY) ou vender (SELL). Para o par BTCUSDT, BUY indica que você deseja comprar BTC por USDT. SELL indica a venda de BTC por USDT.
type – o tipo de ordem que deseja criar. Valores possíveis (detalhes aqui):
- LIMIT
- MARKET
- STOP_LOSS
- STOP_LOSS_LIMIT
- TAKE_PROFIT
- TAKE_PROFIT_LIMIT
- LIMIT_MAKER
timeInForce– este parâmetro define como a ordem deve ser executada:
- GTC (good till canceled) – válida até ser cancelada. Talvez a configuração mais popular, o GTC garante que sua ordem seja válida até ser preenchida ou cancelada.
- FOK (fill or kill) – o FOK instrui que a corretora execute completamente a ordem, de uma só vez. Caso isso não seja possível, a ordem será imediatamente cancelada.
- IOC (immediate or cancel) – a ordem deve ser parcial ou totalmente executada imediatamente ou será cancelada. Ao contrário do FOK, as ordens não são canceladas se puderem ser parcialmente preenchidas.
quantity – simplesmente, a quantidade do ativo que você deseja comprar ou vender.
price – o preço de venda. Para o par BTCUSDT, ele é definido em USDT.
newClientOrderId – um identificador para ordem. Este não é um campo obrigatório, mas você pode defini-lo como um identificador que facilitará consultas posteriores. Caso contrário, ele será gerado aleatoriamente pela corretora.

Ok! Agora vamos criar a ordem de teste. Vamos continuar com os valores gerados automaticamente: uma ordem limite de venda de 0,1 BTC por USDT, ao preço de $9000. Clique em Send para enviar. Se der certo, receberemos {} como resposta.

Criando uma ordem

Agora veremos como criar uma ordem.

POST /api/v3/order

Navegue até Trade > New Order. Você já está familiarizado com as ordens de teste, então os parâmetros aqui não serão nenhuma surpresa. Vamos deixar todos os valores como estão, mas como somos sempre otimistas em relação ao mercado, vamos mudar o preço de venda para $40.000. Ajuste o valor do preço. Em seguida, clique em Send.

Sua resposta retornará vários detalhes sobre a ordem, caso seja bem-sucedida.

Verificando o status de uma ordem em aberto

Na seção anterior, recebemos a confirmação de que a ordem foi criada, mas e se quisermos consultá-la novamente mais tarde? Temos algumas opções de request disponíveis.

GET /api/v3/openOrders

Procure em Trade > Current Open Orders (USER_DATA). BTCUSDT é o par padrão. Ao selecionar Send, você verá todas as suas ordens BTCUSDT em aberto (até o momento só criamos uma). Você tem a opção de não especificar um símbolo, o que retornará todas as suas ordens em aberto.

GET /api/v3/allOrders

Trade > All Orders (USER_DATA) oferece uma visão geral de todas as ordens – não apenas as abertas. Aqui, você deve escolher um símbolo. orderId, startTime, endTime e limit são parâmetros opcionais que podem ajudá-lo a filtrar sua pesquisa. Vamos deixá-los como estão, então você pode desmarcá-los. Clique em Send e você receberá as mesmas respostas da etapa anterior. Se você tivesse ordens fechadas ou cancelados, também as veria aqui.

Por fim, podemos consultar ordens específicas:

GET /api/v3/order

Encontre esse método em: Trade > Query Order (USER_DATA). Você deverá fornecer o orderId ou o origClientOrderId (a tag opcional “newClientOrderId” você pode adicionar às ordens). Desmarque orderId. Para origClientOrderId, forneceremos a tag padrão de antes – ”my_order_id_1”. Preencha o campo e clique em Send para obter a resposta.

Cancelando uma ordem

Vamos supor que, depois de algum tempo, percebemos que o valor alvo de $40.000 é um pouco otimista demais, por isso queremos cancelar a ordem. Neste caso, usaremos:

DELETE /api/v3/order

Em Trade > Cancel Order encontramos a request que nos permitirá selecionar e cancelar ordens. Desmarque orderId e newClientOrderId e use “my_order_id_1” como o valor para origClientOrderId.

Ao enviar esta solicitação (request), a ordem será cancelada. Descendo a tela até "status", você verá que a ordem foi realmente cancelada. Para confirmar, usamos o endpoint GET /api/v3/openOrders novamente (que nos fornecerá uma lista vazia) ou GET /api/v3/order com o origClientOrderId.

Criando uma ordem que é executada imediatamente

A nossa ordem anterior não foi preenchida porque era uma limit order (ordem limite) que seria executada somente se o preço do BTC atingisse $40.000. Com uma market order (ordem a mercado), estamos basicamente dizendo "compre/venda o ativo ao preço disponível no momento". A ordem será executada imediatamente.

Para isso, acesse Trade > New Order. Vamos demonstrar o tipo de resposta (newOrderRespType), que é um parâmetro que podemos ajustar dependendo da resposta que queremos do servidor. Temos três opções: ACK, RESULT ou FULL – você pode ver exemplos de cada resposta aqui. Vamos usar o ACK, que nos dará uma confirmação simples de que a ordem foi recebida.

Abaixo, podemos ver que estamos prestes a enviar uma market order para vender BNB por BUSD ao preço de mercado atual.

Note que a resposta nos fornece poucas informações:

Você pode verificar se a ordem foi preenchida com o endpoint /api/v3/allOrders.

Verificando seus trades

Por último, vamos dar uma olhada no endpoint para verificar seus trades:

GET /api/v3/myTrades

Está localizado em Trade > Account Trade List (USER_DATA). Ele permite a verificação de cada trade para um símbolo específico. Se quiser ver todos os seus trades para o símbolo padrão (BTCUSDT), basta desmarcar startTime, endTime e fromId. A resposta retornará até 500 trades – ajuste o limite se quiser ver mais.

Debugging com Postman

No Postman, é possível revelar mais informações da solicitação e da resposta HTTP não processadas.

Este menu abrirá o console do Postman, que exibe os detalhes de cada solicitação.

Considerações finais

O objetivo deste guia é fornecer uma breve introdução sobre a API da Binance sem precisar escrever as linhas de códigos. Se você conseguiu acompanhar, já deve ter uma ideia de como podemos fazer solicitações (requests) e enviar informações.

Nos próximos capítulos desta série, apresentaremos alguns conceitos básicos de codificação que nos permitem automatizar a compra e a venda de criptomoedas e outros ativos digitais.

Tem dúvidas? Acesse nosso fórum da Comunidade de Desenvolvedores da Binance ou confira a documentação.