Acesso à API de Negociações
Para utilizar a API de negociações do Mercado Bitcoin são necessários:.
1. Criar uma conta
Caso não possua uma conta, crie uma agora mesmo clicando aqui.
2. Gerar o PIN de Segurança
O recurso PIN de segurança é um código numérico de quatro dígitos obrigatório. É um recurso para aumentar a segurança de sua conta. Ao solicitar um PIN de segurança, o sistema enviará um email contendo esse código. A solicitação pode ser feita em aqui.
3. Gerar uma chave da API
Para a comunicação com a API é necessário criar um par identificador/segredo. O identificador é também chamado de TAPI ID e é utilizado para referenciar a conta e chave do usuário. O segredo é utilizado para autenticar a requisição. A utilização detalhada será abordada em Comunicação com a TAPI.
Para gerar sua chave entre aqui. Digite um nome que identificará a chave a ser gerada e aperte "Criar nova". Para exibir as existentes, é necessário digitar seu PIN. As chaves são criadas no status Acesso Total, porém podem ser modificadas para Apenas Leitura.
Acesso Total
Provê acesso a todos os métodos da API.
Apenas Leitura
Provê acesso somente aos métodos de leitura da API, ou seja, não é possível modificar o estado da conta, apenas acompanhar sua movimentação. Recurso útil para utilizar análise de dados, de terceiros ou não, sem permitir a execução de operações.
Comunicação com a API
De posse da chave API, a próxima etapa é realizar a comunicação com a API, composta por uma requisição e uma resposta.
Taxa limite de requisições
O acesso à API é limitado por padrão ao máximo de 60 requisições a cada 60 segundos, por usuário e não por chave (os limites podem ser reduzidos caso o sistema esteja sobrecarregado, no momento está em 15/60s). Em caso de exceder o limite, é retornado como resposta o erro #429 (ver tabela de erros). Em caso de abuso, como realizar uma quantidade de chamadas significativamente maior do que o estipulado, o usuário pode sofrer um bloqueio temporário, por padrão definido em 10 minutos. Em casos de reincidência, bloqueios mais longos ou desativação da conta podem ser aplicados.
Requisição (Request)
A estrutura da requisição tem como elementos principais: URL, Parâmetros e Cabeçalho.
URL
É necessário fazer uma chamada HTTP, método POST, para a URL https://www.mercadobitcoin.net/tapi/v3/.
Parâmetros
Os dados são codificados no formato Form URL Encoded (
Content-Type: application/x-www-form-urlencoded
). Importante não confundir o método da chamada (request method) com o método da TAPI (tapi_metod). Dois parâmetros são obrigatórios e presentes em todas as requisições:tapi_method
: Nome do método em letras minúsculas.
tapi_nonce
: Número arbitrário utilizado uma única vez por requisição ao servidor. Assim, é obrigatório o uso de um valor maior na requisição seguinte.Tipo: Inteiro
Valor inicial sugerido: 1IMPORTANTE: devido às características da arquitetura web, ocorrem casos em que as requisições são processadas em ordem diferente da ordem de envio. Isso pode causar problemas com a validação do tapi-nonce e bloquear requisições. Por esse motivo serão aceitos valores ainda não utilizados, desde que atendam o limite de até 30 números menores e estejam em um intervalo de tempo de até 10 segundos após o último processado.
Os demais parâmetros diferem de acordo com o método da TAPI utilizado.
Exemplo de lista de parâmetros em application/x-www-form-urlencoded:
tapi_method=list_orders&tapi_nonce=1450897683
Exemplo de lista de parâmetros (Python):
params = { 'tapi_method': 'list_orders', 'tapi_nonce': 1 }
Cabeçalho (Header)
O cabeçalho é composto pelos itens:
TAPI-ID
: Identificador da TAPI, utilizado para referenciar a conta e chave TAPI do usuário.Tipo: String
Tamanho: 32 caracteresExemplo:
TAPI-ID: b493d48364afe44d11c0165cf470a4164d1e2609911ef998be868d46ade3de4e
TAPI-MAC
: Código MAC , utilizado para autenticar os dados da requisição. Com isso garante a segurança da informação transmitida e assim evita ataques MITM .Tipo: String
Tamanho: Até 128 caracteresGeração passo a passo
A informação ou mensagem a ser autenticada é composta pelo path da requisição concatenado com o caracter ? (interrogação) e com a lista de parâmetros codificada no formato de código HMAC . Exemplo:# Path: /tapi/v3/ # Lista de parâmetros codificada no formato url-encoded: tapi_method=list_orders&tapi_nonce=1 # Mensagem concatenada e formatada: /tapi/v3/?tapi_method=list_orders&tapi_nonce=1
IMPORTANTE: De acordo com a linguagem de programação, os parâmetros no formato url-encoded pode ter ordem diferente, o que vai gerar um TAPI-MAC diferente do exemplo abaixo.
A mensagem então deve ser autenticada com algoritmo HMAC-SHA-512 usando como senha o segredo da chave TAPI. Resultado do exemplo acima:# Segredo da chave TAPI desse exemplo: 1ebda7d457ece1330dff1c9e04cd62c4e02d1835968ff89d2fb2339f06f73028 # TAPI-MAC: 7f59ea8749ba596d5c23fa242a531746b918e5e61c9f6c8663a699736db503980f3a507ff7e2ef1336f7888d684a06c9a460d18290e7b738a61d03e25ffdeb76
Exemplo de geração de TAPI-MAC (Python):
import urllib import hashlib import hmac # Constantes e Parâmetros # Do exemplo acima, '1ebda7d457ece1330dff1c9e04cd62c4e02d1835968ff89d2fb2339f06f73028' MB_TAPI_SECRET = '<user_tapi_secret>' REQUEST_PATH = '/tapi/v3/' # Parâmetros (variam de acordo com o método) params = { # Do exemplo acima, 'list_orders' 'tapi_method': '<tapi_method>', # Do exemplo acima, 1 'tapi_nonce': <next_nonce> } # Parâmetros formatados # Utilizado no request params = urllib.urlencode(params) # Utilizado apenas para gerar o MAC params_string = REQUEST_PATH + '?' + params # Gerar MAC H = hmac.new(MB_TAPI_SECRET, digestmod=hashlib.sha512) H.update(params_string) tapi_mac = H.hexdigest()
Resposta (Response)
Descrição
O conteúdo das respostas é no formato JSON . A estrutura é formada por 3 elementos principais: status_code, server_unix_timestamp e response_data.
Os elementos da resposta JSON obedecem a ordem descrita nesse documento, entretanto é recomendado sempre que se trabalhar com JSON obter elementos pelo nome da chave, o que evita ser afetado por bugs ou mudanças da TAPI.
Elementos
response_data
: Resposta do método requisitado. A estrutura JSON varia para cada um dos métodos de Métodos da TAPI.Tipo: String
Formato: JSON
Tamanho: indefinidostatus_code
: Código que indica sucesso ou um erro na chamada.Tipo: Inteiro
Formato: detalhes abaixo na Tabela de status da chamadaerror_message
[opcional]: Quando o código status_code for respectivo a um erro, retorna a descrição do erro.Tipo: String
Tamanho: até 150 caracteresserver_unix_timestamp
: Data/hora do servidor. Esse valor não deve ser utilizado para sincronia. Apesar de , pode parecer que sim, mas é um falso positivo, já que as chamadas de diferentes métodos não são executadas em uma fila única. Dessa forma, o timestamp serve simplesmente para ter uma estimativa de data/hora em que o servidor respondeu e relacionar a chamada a um determinado momento no tempo. Na descrição do método list_orderbook é descrito como obter sincronia na criação de ordens.Exemplo da estrutura de resposta de sucesso
Exemplo da estrutura de resposta de erro
Tabela de status da chamada
Algumas descrições irão variar, porém tratam do mesmo contexto de erro descrito acima. Exemplo: pode ser retornado o erro 206 com a descrição "Valor de *order_type* deve ser 0 ou 1.". Ou seja, não deixa de ser um erro 206 que indica parâmetro inválido, mas a mensagem é modificada para ajudar a identificar qual parâmetro e o motivo de ter sido considerado inválido.
aplicáveis a todos os métodos
100: Sucesso 199: Erro : "API de Negociações desativada temporariamente." 200: Erro : "Requisição precisa ser feita com método *POST*." 201: Erro : "Valor de *TAPI-ID* inválido." 202: Erro : "Valor de *TAPI-MAC* inválido." 203: Erro : "Valor do *tapi_nonce* inválido." 204: Erro : "Valor de *tapi_method* inválido." 206: Erro : "Valor de parâmetro inválido." 429: Erro : "Taxa de requisições excedeu o limite de requisições no intervalo." 430: Erro : "Requisição negada: taxa de requisições elevada ou requisição inválida." 431: Erro : "Requisições bloqueadas temporariamente." 500: Erro : "Erro interno, favor acessar a central de ajuda."
aplicáveis a métodos específicos
detalhes na documentação de cada método205: Erro : "Valor do *coin_pair* inválido." 207: Erro : "Saldo de Reais insuficiente para realizar a operação." 208: Erro : "Ordem inválida. O *order_id* informado não existe ou pertence a outro usuário." 209: Erro : "Endereço não cadastrado ou não marcado como *confiável*." 210: Erro : "Problema na transferência da moeda digital *[coin]*. Favor acessar a central de ajuda." 211: Erro : "Tentativa de acesso a um método de persistência com chave *apenas leitura*." 212: Erro : "Não foi possível cancelar a ordem. Já foi processada ou cancelada." 213: Erro : "Conta bancária não cadastrada ou não marcada como *confiável*." 214: Erro : "Saque para conta poupança deve ser menor do que R$ 5000,00." 215: Erro : "Saldo de Bitcoin insuficiente para realizar a operação." 216: Erro : "Saldo de Litecoin insuficiente para realizar a operação." 232: Erro : "Saldo de BCash insuficiente para realizar a operação." 217: Erro : "Esse valor excede o limite de saque de Reais para as últimas 24 horas." 218: Erro : "Esse valor excede o limite de saque da moeda digital para as últimas 24 horas." 219: Erro : "Valor mínimo para saques de Reais é R$ 50,00." 220: Erro : "Valor mínimo de transferências de Bitcoin para endereço externo é 0,001 BTC." 221: Erro : "Valor mínimo de transferências de Litecoin para endereço externo é 0,009 LTC." 233: Erro : "Valor mínimo de transferências de BCash para endereço externo é 0,001 BCH." 222: Erro : "Quantidade mínima (0,001 BTC) ou máxima excedida." 223: Erro : "Quantidade mínima (0,009 LTC) ou máxima excedida." 234: Erro : "Quantidade mínima (0,001 BCH) ou máxima excedida." 224: Erro : "Preço unitário mínimo (R$ 0,01) ou máximo excedido." 225: Erro : "Status em *status_list* duplicado." 226: Erro : "Valor de *status_list* inválido." 227: Erro : "Número de casas decimais informado inválido." 228: Erro : "Tamanho de *[parameter]* maior do que o permitido: [size] caracteres." 229: Erro : "Transferência inválida. O *withdrawal_id* informado não existe em sua conta." 230: Erro : "Valor mínimo da taxa de transferências de Bitcoin é 0,00001 BTC." 231: Erro : "Valor máximo da taxa de transferências de Bitcoin é 0,01 BTC." 235: Erro : "Valor mínimo da taxa de transferências de BCash é 0,00005 BCH." 236: Erro : "Valor máximo da taxa de transferências de BCash é 0,008 BCH."
Métodos da TAPI
Os métodos e campos seguem um padrão de nomenclatura, assim são formados por "verbo + substantivo" em inglês, separados por underline.
Para que não ocorram erros de arredondamento na comunicação, todos os valores são serializados em Strings.
Ainda, é importante respeitar maiúsculas e minúsculas, principalmente nos domínios de dados e nomes de parâmetros.
list_system_messages
Descrição
Método para comunicação de eventos do sistema relativos à TAPÌ, entre eles bugs, correções, manutenção programada e novas funcionalidades e versões. O conteúdo muda a medida que os eventos ocorrem. A comunicação externa, feita via Twitter e e-mail aos usuários da TAPI, continuará ocorrendo. Entretanto, essa forma permite ao desenvolvedor tratar as informações juntamente ao seus logs ou até mesmo automatizar comportamentos.
Parâmetros adicionais
level
[opcional]: Filtro por criticidade das mensagens.Tipo: String
Domínio de dados:INFO : Informações do sistema
WARNING : Alertas do sistema
ERROR : Erros do sistemaErros aplicáveis
Somente se aplicam a esse método os erros aplicáveis a todos os métodos.
Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'list_system_messages', 'tapi_nonce': '1' }
params = { 'tapi_method': 'list_system_messages', 'tapi_nonce': '1', 'level': 'INFO' }
Resultado
messages
: Lista de mensagens da TAPI.msg_date
: Data e hora em que a mensagem foi publicada.level
: Criticidade da mensagem.Tipo: String
Domínio de dados:INFO : Informações do sistema
WARNING : Alertas do sistema
ERROR : Erros do sistemaevent_code
: Número indicando o tipo da mensagem.Tipo: Inteiro
Domínio de dados:msg_content
: Conteúdo da mensagem.Tipo: String
Tamanho: até 250 caracteresExemplo de Resposta
get_account_info
Descrição
Retorna dados da conta, como saldos das moedas (Real, Bitcoin, Litecoin e BCash), saldos considerando retenção em ordens abertas, quantidades de ordens abertas por moeda digital, limites de saque/transferências das moedas.
Erros aplicáveis
Somente se aplicam a esse método os erros aplicáveis a todos os métodos.
Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'get_account_info', 'tapi_nonce': '1' }
Resultado
balance
: Saldos das moedas.brl
: Saldo de Reais.available
: Saldo de reais disponível para operações.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Saldo de reais available mais valores em ordens de compra abertas.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharbtc
: Saldo de Bitcoin.available
: Saldo de Bitcoin disponível para operações.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Saldo de Bitcoin available mais valores em ordens de venda abertas e transferências não autorizadas.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharamount_open_orders
: Quantidade de ordens de compra ou venda de Bitcoin abertas.Tipo: Inteiroltc
: Saldo de Litecoin.available
: Saldo de Litecoin disponível para operações.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Saldo de Litecoin available mais valores em ordens de venda abertas e transferências não autorizadas.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharamount_open_orders
: Quantidade de ordens de compra ou venda de Litecoin abertas.Tipo: Inteirobch
: Saldo de BCash.available
: Saldo de BCash disponível para operações.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Saldo de BCash available mais valores em ordens de venda abertas e transferências não autorizadas.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharamount_open_orders
: Quantidade de ordens de compra ou venda de BCash abertas.Tipo: Inteirowithdrawal_limits
: Limites de saques e transferências.brl
: Limite de saque de Reais.available
: Limite de saque em Reais disponível.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Limite de saque em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharbtc
: Limite de transferência de Bitcoin.available
: Limite de transferência de Bitcoin disponível.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Limite de transferência de Bitcoin.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharltc
: Limite de transferência de Litecoin.available
: Limite de transferência de Litecoin disponível.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Limite de transferência de Litecoin.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharbch
: Limite de transferência de BCash.available
: Limite de transferência de BCash disponível.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhartotal
: Limite de transferência de BCash.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharExemplo de Resposta
get_order
Descrição
Retorna os dados da ordem de acordo com o ID informado. Dentre os dados estão as informações das Operações executadas dessa ordem. Apenas ordens que pertencem ao proprietário da chave da TAPI pode ser consultadas. Erros específicos são retornados para os casos onde o order_id informado não seja de uma ordem válida ou pertença a outro usuário.
Parâmetros adicionais
coin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_id
: Número de identificação único da ordem por coin_pair.Tipo: InteiroErros aplicáveis
205: Erro : "Valor do *coin_pair* inválido." 208: Erro : "Ordem inválida. O *order_id* informado não existe ou pertence a outro usuário."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'get_order', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC', 'order_id': 94661 }
Resultado
order
: Dados da ordem de compra ou venda.order_id
: Número de identificação da ordem, único por coin_pair.Tipo: Inteirocoin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus
: Estado da ordem.Tipo: Inteiro
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : canceled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
: Indica se a ordem tem uma ou mais execuções. Auxilia na identificação de ordens parcilamente executadas.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.quantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_quantity
: Quantidade da moeda digital executada.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_price_avg
: Preço unitário médio de execução.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharfee
: Comissão da ordem, para ordens de compra os valores são em moeda digital, para ordens de venda os valores são em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharcreated_timestamp
: Data e hora de criação da ordem.updated_timestamp
: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).operations
: Lista de operações ou execuções realizadas por essa ordem.operation_id
: Número de identificação da operação, único por coin_pairTipo: Inteiroquantity
: Quantidade de moeda digital da operação.Tipo: Stringprice
: Preço unitário da operação.Tipo: Stringfee_rate
: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.Tipo: Stringexecution_timestamp
: Data e hora de execução da operação.Exemplo de Resposta
list_orders
Descrição
Retorna uma lista de até 200 ordens, de acordo com os filtros informados, ordenadas pela data de última atualização. As operações executadas de cada ordem também são retornadas. Apenas ordens que pertencem ao proprietário da chave da TAPI são retornadas. Caso nenhuma ordem seja encontrada, é retornada uma lista vazia.
Parâmetros adicionais
coin_pair
: Par de moedas a ser filtrado.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
[opcional]: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus_list
[opcional]: Estado(s) da ordem a filtrarTipo: String
Formato: Lista JSON de Inteiros, ex.:"[2,3]"
ou"[2]"
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : cancelled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
[opcional]: Filtro para ordens com ou sem execução.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.from_id
[opcional]: Filtro para orders a partir do ID informado (inclusive).Tipo: Inteiroto_id
[opcional]: Filtro para orders até do ID informado (inclusive).Tipo: Inteirofrom_timestamp
[opcional]: Filtro para orders criadas a partir do timestamp informado (inclusive).to_timestamp
[opcional]: Filtro para orders criadas até do timestamp informado (inclusive).Erros aplicáveis
205: Erro : "Valor do *coin_pair* inválido." 225: Erro : "Status em *status_list* duplicado." 226: Erro : "Valor de *status_list* inválido."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplo
params = { 'tapi_method': 'list_orders', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC', 'status_list': '[2, 3]', 'has_fills': 1 }
Resultado
orders
: Lista de ordens com base nos filtros aplicados.order_id
: Número de identificação da ordem, único por coin_pair.Tipo: Inteirocoin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus
: Estado da ordem.Tipo: Inteiro
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : canceled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
: Indica se a ordem tem uma ou mais execuções. Auxilia na identificação de ordens parcilamente executadas.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.quantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_quantity
: Quantidade da moeda digital executada.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_price_avg
: Preço unitário médio de execução.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharfee
: Comissão da ordem, para ordens de compra os valores são em moeda digital, para ordens de venda os valores são em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharcreated_timestamp
: Data e hora de criação da ordem.updated_timestamp
: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).operations
: Lista de operações ou execuções realizadas por essa ordem.operation_id
: Número de identificação da operação, único por coin_pairTipo: Inteiroquantity
: Quantidade de moeda digital da operação.Tipo: Stringprice
: Preço unitário da operação.Tipo: Stringfee_rate
: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.Tipo: Stringexecution_timestamp
: Data e hora de execução da operação.Exemplo de Resposta
list_orderbook
Descrição
Retorna informações do livro de negociações (orderbook) do Mercado Bitcoin para o par de moedas (coin_pair) informado. Diferente do método orderbook público descrito em /api/#2.2., aqui são fornecidas informações importantes para facilitar a tomada de ação de clientes TAPI e sincronia das chamadas. Dentre elas, o número da última ordem contemplada (latest_order_id) e número das ordens do livro (order_id), descritos abaixo. Importante salientar que nesse método ordens de mesmo preço não são agrupadas como feito no método público.
Parâmetros adicionais
coin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashfull
[opcional]: Indica quantidades de ordens retornadas no livro. Utilizar uma quantidade menor acarreta em menos carga no servidor e no cliente, assim a resposta e seu tratamento serão mais rápidos, o que pode resultar em vantagem competitiva para o cliente TAPI.Tipo: Booleano
Valor padrão: False
Domínio de dados:false : Retorna até 20 ordens de compra e 20 ordens de venda
true : Retorna até 500 ordens de compra e 500 ordens de vendaErros aplicáveis
205: Erro : "Valor do *coin_pair* inválido."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplo
params = { 'tapi_method': 'list_orderbook', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC' }
Resultado
orderbook
: Livro de negociações.bids
ouasks
: Lista de ordens de compra (bid) ou venda (ask) abertas, ordenadas pelo maior preço.order_id
: Número de identificação único da ordem.Tipo: Inteirois_owner
: Informa se ordem pertence ao proprietário da chave TAPI.Tipo: Booleano
Domínio de dados:false : Pertence ao proprietário da chave TAPI
true : Não pertence ao proprietário da chave TAPIquantity
: Quantidade disponível para compra/venda ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário de compra/venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlatest_order_id
: Última ordem contemplada no resultado de orderbook. Entende-se como ordem contemplada a última ordem criada e confrotada ao livro de acordo com o resultado retornado deste método. Assim, essa ordem pode ter sido executada ou não. A última ordem contemplada pode não estar presente no livro, ou por ter sido executada em sua totalidade ou por já ter sido cancelada em ação posterior a sua criação. Assim, é importante salientar que uma ordem cancelada, apesar de alterar o livro, não altera o valor deste campo.
Sincronização: Esse campo é útil para sincronia com chamadas de criação de ordens de compra ou venda. Isso permite a análise do livro para saber se uma ordem criada já está no resultado que será analisado, dado que o order_id é sempre crescente.ExemplificaçãoConsidere a seguinte sequência de eventos:
Evento Usuário ID da ordem
(order_id)Última ordem contemplada
(latest_order_id)Criação ordem de compra antonio_gomes 1001 1001 Criação ordem de compra jose_silva 1002 1002 Criação ordem de venda jose_silva 1003 1003 Cancelamento de ordem jose_silva 1002 1003 Caso o retorno de latest_order_id seja 1003, interpreta-se que as ordens com order_id menor ou igual a 1003 foram contempladas no livro. Porém, não é possível saber se o resultado do livro contempla ou não o cancelamento da ordem 1002 apenas com base nesse valor, para isso é necessário verificar se o order_id 1002 está presente no resultado do livro (caso não esteja, a ordem foi cancelada ou não está entre as primeiras 500 da listagem, o que pode ser inferido pelo preço da ordem) ou também consultar a ordem no método list_orders caso seja o proprietário dessa ordem.
Exemplo de Resposta
place_buy_order
Descrição
Abre uma ordem de compra (buy ou bid) do par de moedas, quantidade de moeda digital e preço unitário limite informados. A criação contempla o processo de confrontamento da ordem com o livro de negociações. Assim, a resposta pode informar se a ordem foi executada (parcialmente ou não) imediatamente após sua criação e, assim, se segue ou não aberta e ativa no livro.
Parâmetros adicionais
coin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin (BTC)
BRLLTC : Real e Litecoin (LTC)
BRLBCH : Real e BCashquantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 8 casas decimais
Valor Mínimo: 0,001 BTC ou 0,009 LTClimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 5 casas decimais
Valor Mínimo: R$ 0,01Erros aplicáveis
211: Erro : "Tentativa de acesso a um método de persistência com chave *apenas leitura*." 205: Erro : "Valor do *coin_pair* inválido." 207: Erro : "Saldo de Reais insuficiente para realizar a operação." 215: Erro : "Saldo de Bitcoin insuficiente para realizar a operação." 216: Erro : "Saldo de Litecoin insuficiente para realizar a operação." 232: Erro : "Saldo de BCash insuficiente para realizar a operação." 222: Erro : "Quantidade mínima (0,001 BTC) ou máxima excedida." 223: Erro : "Quantidade mínima (0,009 LTC) ou máxima excedida." 234: Erro : "Quantidade mínima (0,001 BCH) ou máxima excedida." 224: Erro : "Preço unitário mínimo (R$ 0,01) ou máximo excedido." 227: Erro : "Número de casas decimais informado inválido."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'place_buy_order', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC', 'quantity': '0.01', 'limit_price': '1200.001' }
Resultado
order_id
: Número de identificação da ordem, único por coin_pair.Tipo: Inteirocoin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus
: Estado da ordem.Tipo: Inteiro
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : canceled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
: Indica se a ordem tem uma ou mais execuções. Auxilia na identificação de ordens parcilamente executadas.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.quantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_quantity
: Quantidade da moeda digital executada.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_price_avg
: Preço unitário médio de execução.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharfee
: Comissão da ordem, para ordens de compra os valores são em moeda digital, para ordens de venda os valores são em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharcreated_timestamp
: Data e hora de criação da ordem.updated_timestamp
: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).operations
: Lista de operações ou execuções realizadas por essa ordem.operation_id
: Número de identificação da operação, único por coin_pairTipo: Inteiroquantity
: Quantidade de moeda digital da operação.Tipo: Stringprice
: Preço unitário da operação.Tipo: Stringfee_rate
: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.Tipo: Stringexecution_timestamp
: Data e hora de execução da operação.Exemplo de Resposta
place_sell_order
Descrição
Abre uma ordem de venda (sell ou ask) do par de moedas, quantidade de moeda digital e preço unitário limite informados. A criação contempla o processo de confrontamento da ordem com o livro de negociações. Assim, a resposta pode informar se a ordem foi executada (parcialmente ou não) imediatamente após sua criação e, assim, se segue ou não aberta e ativa no livro.
Parâmetros adicionais
coin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin (BTC)
BRLLTC : Real e Litecoin (LTC)
BRLBCH : Real e BCashquantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 8 casas decimais
Valor Mínimo: 0,001 BTC ou 0,009 LTClimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 5 casas decimais
Valor Mínimo: R$ 0,01Erros aplicáveis
211: Erro : "Tentativa de acesso a um método de persistência com chave *apenas leitura*." 205: Erro : "Valor do *coin_pair* inválido." 207: Erro : "Saldo de Reais insuficiente para realizar a operação." 215: Erro : "Saldo de Bitcoin insuficiente para realizar a operação." 216: Erro : "Saldo de Litecoin insuficiente para realizar a operação." 232: Erro : "Saldo de BCash insuficiente para realizar a operação." 222: Erro : "Quantidade mínima (0,001 BTC) ou máxima excedida." 223: Erro : "Quantidade mínima (0,009 LTC) ou máxima excedida." 234: Erro : "Quantidade mínima (0,001 BCH) ou máxima excedida." 224: Erro : "Preço unitário mínimo (R$ 0,01) ou máximo excedido." 227: Erro : "Número de casas decimais informado inválido."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'place_sell_order', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC', 'quantity': '1.0333', 'limit_price': '1300.00001' }
Resultado
order_id
: Número de identificação da ordem, único por coin_pair.Tipo: Inteirocoin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus
: Estado da ordem.Tipo: Inteiro
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : canceled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
: Indica se a ordem tem uma ou mais execuções. Auxilia na identificação de ordens parcilamente executadas.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.quantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_quantity
: Quantidade da moeda digital executada.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_price_avg
: Preço unitário médio de execução.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharfee
: Comissão da ordem, para ordens de compra os valores são em moeda digital, para ordens de venda os valores são em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharcreated_timestamp
: Data e hora de criação da ordem.updated_timestamp
: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).operations
: Lista de operações ou execuções realizadas por essa ordem.operation_id
: Número de identificação da operação, único por coin_pairTipo: Inteiroquantity
: Quantidade de moeda digital da operação.Tipo: Stringprice
: Preço unitário da operação.Tipo: Stringfee_rate
: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.Tipo: Stringexecution_timestamp
: Data e hora de execução da operação.Exemplo de Resposta
cancel_order
Descrição
Cancela uma ordem, de venda ou compra, de acordo com o ID e par de moedas informado. O retorno contempla o sucesso ou não do cancelamento, bem como os dados e status atuais da ordem. Somente ordens pertencentes ao próprio usuário podem ser canceladas.
Parâmetros adicionais
coin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_id
: Número de identificação único da ordem.Tipo: InteiroErros aplicáveis
211: Erro : "Tentativa de acesso a um método de persistência com chave *apenas leitura*." 205: Erro : "Valor do *coin_pair* inválido." 208: Erro : "Ordem inválida. O *order_id* informado não existe ou pertence a outro usuário." 212: Erro : "Não foi possível cancelar a ordem. Já foi processada ou cancelada."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'cancel_order', 'tapi_nonce': '1', 'coin_pair': 'BRLBTC', 'order_id': 94661 }
Resultado
order
: Dados da ordem de compra ou venda.order_id
: Número de identificação da ordem, único por coin_pair.Tipo: Inteirocoin_pair
: Par de moedas.Tipo: String
Domínio de dados:BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCashorder_type
: Tipo da ordem a ser filtrado.Tipo: Inteiro
Domínio de dados:1 : Ordem de compra
2 : Ordem de vendastatus
: Estado da ordem.Tipo: Inteiro
Domínio de dados:2 : open : Ordem aberta, disponível no livro de negociações. Estado intermediário.
3 : canceled : Ordem cancelada, executada parcialmente ou sem execuções. Estado final.
4 : filled : Ordem concluída, executada em sua totalidade. Estado final.has_fills
: Indica se a ordem tem uma ou mais execuções. Auxilia na identificação de ordens parcilamente executadas.Tipo: Booleanofalse : Sem execuções.
true : Com uma ou mais execuções.quantity
: Quantidade da moeda digital a comprar/vender ao preço de limit_price.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharlimit_price
: Preço unitário máximo de compra ou mínimo de venda.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_quantity
: Quantidade da moeda digital executada.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharexecuted_price_avg
: Preço unitário médio de execução.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharfee
: Comissão da ordem, para ordens de compra os valores são em moeda digital, para ordens de venda os valores são em Reais.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharcreated_timestamp
: Data e hora de criação da ordem.updated_timestamp
: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).operations
: Lista de operações ou execuções realizadas por essa ordem.operation_id
: Número de identificação da operação, único por coin_pairTipo: Inteiroquantity
: Quantidade de moeda digital da operação.Tipo: Stringprice
: Preço unitário da operação.Tipo: Stringfee_rate
: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.Tipo: Stringexecution_timestamp
: Data e hora de execução da operação.Exemplo de Resposta
get_withdrawal
Descrição
Retorna os dados de uma transferência de moeda digital (BTC, LTC) ou de um saque de Real (BRL).
Parâmetros adicionais
coin
: Moeda a ser feita transferência/saque.Tipo: String
Domínio de dados:BRL : Real
BTC : Bitcoin
LTC : Litecoin
BCH : BCashwithdrawal_id
: Número de identificação da transferência/saque, único por coin.Tipo: InteiroErros aplicáveis
229: Erro : "Transferência inválida. O *withdrawal_id* informado não existe em sua conta."
Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'get_withdrawal', 'tapi_nonce': '1', 'coin': 'BTC', 'withdrawal_id': 10012 }
Resultado
withdrawal
: Dados da transferência/saque.id
: Número de identificação da transferência/saque, único por coin.Tipo: Inteirocoin
: Moeda da transferência/saque.Tipo: String
Domínio de dados:BRL : Real
BTC : Bitcoin
LTC : Litecoin
BCH : BCashfee
: Taxa paga pela transferência/saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharstatus
: Estado da transferência/saque.Tipo: Inteiro1 : open, pedido de transferência/saque recebido mas não processado
2 : done, pedido de transferência/saque realizado
3 : canceled, pedido de transferência/saque canceladodescription
[opcional]: Texto para descrever a transferência ou saque.Tipo: String
Tamanho: até 30 caracterescreated_timestamp
: Data e hora de registro do pedido de transferência/saque.updated_timestamp
: Data e hora da última atualização no pedido de transferência/saque.Campos específicosPara coin igual a BRL:quantity
: Valor bruto do saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharnet_quantity
: Valor líquido do saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharaccount
: Texto com código do banco, agência e conta bancária de destino.Tipo: String
Tamanho: até 40 caracteresSe coin for uma moeda digital:quantity
: Quantidade da transferência.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharaddress
: Endereço de moeda digital de destino.Tipo: String
Tamanho: até 40 caracterestx
: Transação da moeda digital.Tipo: String
Tamanho: 64 caracteresExemplo de Resposta
withdraw_coin
Descrição
Requisita pedido de transferência de moeda digital ou saque de Real. Assim, caso o valor de coin seja BRL, então realiza um saque para a conta bancária informada. Caso o valor seja BTC ou LTC, realiza uma transação para o endereço de moeda digital informado.
IMPORTANTE: Só é permitida a transferência para destinos 'confiáveis'. A necessidade de marcar um endereço ou conta bancária como 'confiável' é uma medida de segurança, bem como transferência de moedas digitais necessitam de posterior autorização da transferência por email. Para marcar um endereço ou conta bancária como 'confiável', é necessário ter ativa a "Autenticação em dois passos" e possuir um "PIN de segurança". Essa funcionalidade só está disponível para usuários que possuem uma chave de Trade API ativa. Configure destinos confiáveis em "Cadastro de Endereços" e "Contas bancárias".
Parâmetros adicionais
coin
: Moeda a ser feita transferência/saque.Tipo: String
Domínio de dados:BRL : Real
BTC : Bitcoin
LTC : Litecoin
BCH : BCashdescription
[opcional]: Texto para descrever a transferência ou saque.Tipo: String
Tamanho: até 30 caracteresCampos específicosPara coin igual a BRL:quantity
: Valor bruto do saque. Os limites e taxas se aplicam conforme descrito em "comissões, prazos e limites". As taxas, quando aplicáveis, são debitadas do valor informado.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar. Até 2 casas decimais.
Valor Mínimo: R$ 50,00account_ref
: ID de uma conta bancária já cadastrada e marcada como confiável .Tipo: String
Tamanho: até 7 caracteresPara coin igual a BTC ou LTC ou BCH:address
: Endereço Bitcoin/Litecoin/BCash marcado como confiável .Tipo: String
Tamanho: até 40 caracteresquantity
: Valor líquido da transferência.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar. Até 8 casas decimais.
Valor Mínimo: 0,001 BTCtx_fee
: Valor da taxa paga aos mineradores para processamento da transação. O site 21.co é especializado em cálculo de taxas e possui uma API que pode ser útil para Bitcoin.Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar. Até 8 casas decimais.
Valor Mínimo: 0,00001 BTC
Valor Máximo: 0,01 BTCtx_aggregate
[opcional]: transferência pode ser feita junto de outras transferências em uma mesma transação no Blockchain.Tipo: Booleano
Valor padrão: Truevia_blockchain
[opcional]: transferência para endereço no Mercado Bitcoin pode ser feita via blockchain para gerar uma transação na rede Bitcoin/BCash.Tipo: Booleano
Valor padrão: FalseErros aplicáveis
211: Erro : "Tentativa de acesso a um método de persistência com chave *apenas leitura*." 207: Erro : "Saldo de Reais insuficiente para realizar a operação." 209: Erro : "Endereço não cadastrado ou não marcado como *confiável*." 210: Erro : "Problema na transferência da moeda digital *[coin]*. Favor acessar a central de ajuda." 213: Erro : "Conta bancária não cadastrada ou não marcada como *confiável*." 214: Erro : "Saque para conta poupança deve ser menor do que R$ 5000,00." 215: Erro : "Saldo de Bitcoin insuficiente para realizar a operação." 216: Erro : "Saldo de Litecoin insuficiente para realizar a operação." 232: Erro : "Saldo de BCash insuficiente para realizar a operação." 217: Erro : "Esse valor excede o limite de saque de Reais para as últimas 24 horas." 218: Erro : "Esse valor excede o limite de saque da moeda digital para as últimas 24 horas." 219: Erro : "Valor mínimo para transferências de Reais é de R$ 50,00." 220: Erro : "Valor mínimo de transferências de Bitcoin para endereço externo é de 0,001 BTC." 221: Erro : "Valor mínimo de transferências de Litecoin para endereço externo é de 0,009 LTC." 233: Erro : "Valor mínimo de transferências de BCash para endereço externo é 0,001 BCH." 227: Erro : "Número de casas decimais informado inválido." 228: Erro : "Tamanho de *[parameter]* maior do que o permitido: [size] caracteres." 229: Erro : "Transferência inválida. O *withdrawal_id* informado não existe em sua conta." 230: Erro : "Valor mínimo da taxa de transferências de Bitcoin é de 0,00001 BTC." 231: Erro : "Valor máximo da taxa de transferências de Bitcoin é de 0,01 BTC." 235: Erro : "Valor mínimo da taxa de transferências de BCash é 0,00005 BCH." 236: Erro : "Valor máximo da taxa de transferências de BCash é 0,008 BCH."
237: Erro : "Valor mínimo da taxa de transferências de Litecoin é 0,00005 LTC." 238: Erro : "Valor máximo da taxa de transferências de Litecoin é 0,008 LTC."Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status
Exemplos
params = { 'tapi_method': 'withdraw_coin', 'tapi_nonce': '1', 'coin': 'BTC', 'address': '18d2ogsrMXsspcxzz3DgecePNdxcZUpaUX', 'quantity': '0.678', 'tx_fee': '0.0005' }
params = { 'tapi_method': 'withdraw_coin', 'tapi_nonce': '1', 'coin': 'BRL', 'account_ref': '23449', 'quantity': '2000.00' }
Resultado
withdrawal
: Dados da transferência/saque.id
: Número de identificação da transferência/saque, único por coin.Tipo: Inteirocoin
: Moeda da transferência/saque.Tipo: String
Domínio de dados:BRL : Real
BTC : Bitcoin
LTC : Litecoin
BCH : BCashfee
: Taxa paga pela transferência/saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharstatus
: Estado da transferência/saque.Tipo: Inteiro1 : open, pedido de transferência/saque recebido mas não processado
2 : done, pedido de transferência/saque realizado
3 : canceled, pedido de transferência/saque canceladodescription
[opcional]: Texto para descrever a transferência ou saque.Tipo: String
Tamanho: até 30 caracterescreated_timestamp
: Data e hora de registro do pedido de transferência/saque.updated_timestamp
: Data e hora da última atualização no pedido de transferência/saque.Campos específicosPara coin igual a BRL:quantity
: Valor bruto do saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharnet_quantity
: Valor líquido do saque.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharaccount
: Texto com código do banco, agência e conta bancária de destino.Tipo: String
Tamanho: até 40 caracteresSe coin for uma moeda digital:quantity
: Quantidade da transferência.Tipo: String
Formato: Ponto como separador decimal, sem separador de milharaddress
: Endereço de moeda digital de destino.Tipo: String
Tamanho: até 40 caracterestx
: Transação da moeda digital.Tipo: String
Tamanho: 64 caracteresExemplo de Resposta
Exemplo completo (Python):
# -*- coding: utf-8 -*-
import hashlib
import hmac
import httplib
import json
import urllib
from collections import OrderedDict
# Constantes
MB_TAPI_ID = '<user_tapi_id>'
MB_TAPI_SECRET = '<user_tapi_secret>'
REQUEST_HOST = 'www.mercadobitcoin.net'
REQUEST_PATH = '/tapi/v3/'
# Nonce
# Para obter variação de forma simples
# timestamp pode ser utilizado:
# import time
# tapi_nonce = str(int(time.time()))
tapi_nonce = 1
# Parâmetros
params = {
'tapi_method': 'list_orders',
'tapi_nonce': tapi_nonce,
'coin_pair': 'BRLBTC'
}
params = urllib.urlencode(params)
# Gerar MAC
params_string = REQUEST_PATH + '?' + params
H = hmac.new(MB_TAPI_SECRET, digestmod=hashlib.sha512)
H.update(params_string)
tapi_mac = H.hexdigest()
# Gerar cabeçalho da requisição
headers = {
'Content-type': 'application/x-www-form-urlencoded',
'TAPI-ID': MB_TAPI_ID,
'TAPI-MAC': tapi_mac
}
# Realizar requisição POST
try:
conn = httplib.HTTPSConnection(REQUEST_HOST)
conn.request("POST", REQUEST_PATH, params, headers)
# Print response data to console
response = conn.getresponse()
response = response.read()
# É fundamental utilizar a classe OrderedDict para preservar a ordem dos elementos
response_json = json.loads(response, object_pairs_hook=OrderedDict)
print "status: %s" % response_json['status_code']
print(json.dumps(response_json, indent=4))
finally:
if conn:
conn.close()
Glossário
API - Conjunto de rotinas e padrões para acesso a um aplicativo ou plataforma, leia mais em: https://en.wikipedia.org/wiki/Application_programming_interface.
Cliente TAPI - Sistema que consome os serviços de outro sistema. Nesse contexto, é um cliente a aplicação que utiliza a Trade API do Mercado Bitcoin para consultar informações ou realizar transações, leia mais em: https://en.wikipedia.org/wiki/Client_%28computing%29
Domínio de dados - Conjunto de valores possíveis para um determinado campo, leia mais em: https://en.wikipedia.org/wiki/Data_domain.
Era Unix - Sistema de calendário utilizado pelo sistema operacional UNIX representado por um número inteiro de até 32 bits. É útil para comunicação e cálculos em sistemas devido a sua simplicidade. Seus valores representam a quantidade de segundos a partir do dia 1 de janeiro de 1970. É um horário sem variações de fuso horário ou horário de verão, assim utiliza apenas UTC/GMT, leia mais em: https://pt.wikipedia.org/wiki/Era_Unix. Veja exemplos de código em diversas linguagens em: http://www.epochconverter.com.
HMAC - Em criptografia, HMAC (Hash-based Message Authentication Code) é uma construção específica para calcular o código de autenticação de mensagem (MAC) envolvendo uma função hash criptográfica em combinação com uma chave secreta, leia mais em: https://pt.wikipedia.org/wiki/HMAC.
JSON - Formato leve para intercâmbio de dados computacionais, leia mais em: https://pt.wikipedia.org/wiki/JSON.
MAC - Em criptografia, MAC (Message Authentication Code) é um pequeno pedaço de informação utilizado para autenticar uma mensagem, confirmando que a integridade da mensagem, ou seja, que essa não foi modificada durante seu trânsito, leia mais em: https://en.wikipedia.org/wiki/Message_authentication_code.
MITM - Em criptografia e segurança da computação, um ataque man-in-the-middle (Homem no meio) é quando o ocorre uma tentativa de interceptar a comunicação entre duas partes, geralmente modificando a informação transmitida ou fazendo uso dela para uso posterior. Essa é a razão de ser fundamental a transmissão dos dados criptografados via HTTPS, entretanto, como já ocorreu no passado, confiar apenas no HTTPS não é seguro pois embora raro, podem ocorrer falhas, dessa forma outras técnicas são utilizadas em conjunto para evitar esse tipo de ataque, como envio de MAC e tonce único, leia mais em: https://en.wikipedia.org/wiki/Man-in-the-middle_attack.
Nonce - Em criptografia e segurança da computação, nonce é um número arbitrário que pode ser utilizado uma única vez. Ele garante que comunicações prévias não podem ser utilizadas em replay attacks, leia mais em: https://en.wikipedia.org/wiki/Cryptographic_nonce.
Python - Linguagem de programação (1991) com foco em produtividade e legibilidade, leia mais em: https://pt.wikipedia.org/wiki/Python.
SHA-512 - Algoritmo de criptografia, leia mais em: https://en.wikipedia.org/wiki/SHA-2.
String - Tipo de dado texto, cadeia de caracteres, leia mais em: https://en.wikipedia.org/wiki/String_(computer_science).
TAPI - API de Negociações, abreviação do inglês Trade API.