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 60/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 (Body)

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_method). Dois parâmetros são obrigatórios e presentes em todas as requisições:

 tapi_method: Nome do método em letras minúsculas.
Tipo: String 

 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: 1

IMPORTANTE: 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 caracteres

Exemplo:

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 caracteres

Geraçã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 3):
from urllib.parse import urlencode
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 = urlencode(params)
# Utilizado apenas para gerar o MAC
params_string = REQUEST_PATH + '?' + params

# Gerar MAC
H = hmac.new(MB_TAPI_SECRET.encode(), digestmod=hashlib.sha512)
H.update(params_string.encode())
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: indefinido
 status_code: Código que indica sucesso ou um erro na chamada.
Tipo: Inteiro
Formato: detalhes abaixo na Tabela de status da chamada
 error_message [opcional]: Quando o código status_code for respectivo a um erro, retorna a descrição do erro.
Tipo: String
Tamanho: até 150 caracteres
 server_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.
Tipo: String
Formato: Era Unix
Tamanho: até 25 caracteres
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étodo
205: 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."
240: Erro : "Saldo de XRP (Ripple) insuficiente para realizar a operação."
243: Erro : "Saldo de Ethereum 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."
241: Erro : "Valor mínimo de transferências de XRP (Ripple) para endereço externo é 20 XRP."
244: Erro : "Valor mínimo de transferência de Ethereum para endereço externo é 0,001 ETH."
222: Erro : "Quantidade mínima ou máxima de Bitcoin excedida."
223: Erro : "Quantidade mínima ou máxima de Litecoin excedida."
234: Erro : "Quantidade mínima ou máxima de BCash excedida."
242: Erro : "Quantidade mínima ou máxima de XRP excedida."
245: Erro : "Quantidade mínima ou máxima de Ethereum 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."
239: Erro : "Endereço *address* inválido para transferência."
230: Erro : "Valor mínimo da taxa de transferências de Bitcoin é 0,000001 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."
432: Erro : "Sua ordem está em processamento, caso ocorra algum problema seu saldo será extornado."

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 sistema
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': '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.
Tipo: String
Formato: Era Unix 
 level: Criticidade da mensagem.
Tipo: String
Domínio de dados:
INFO : Informações do sistema
WARNING : Alertas do sistema
ERROR : Erros do sistema
 event_code: Número indicando o tipo da mensagem.
Tipo: Inteiro
Domínio de dados:
7000 : Manutenção programada
7001 : Anúncios relacionados a bugs
7002 : Anúncios relacionados a melhorias
7003 : Anúncios relacionados a novas versões
7004 : Anúncios relacionados a clientes TAPI
 msg_content: Conteúdo da mensagem.
Tipo: String
Tamanho: até 250 caracteres
Exemplo de Resposta

get_account_info

Descrição

Retorna dados da conta, como saldos das moedas (Real, BCash, Bitcoin, Ethereum, Litecoin e XRP), 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.
 bch: Saldo de BCash.
 available: Saldo de BCash disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: 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 milhar
 amount_open_orders: Quantidade de ordens de compra ou venda de BCash abertas.
Tipo: Inteiro
 brl: Saldo de Reais.
 available: Saldo de reais disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Saldo de reais available mais valores em ordens de compra abertas.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 btc: Saldo de Bitcoin.
 available: Saldo de Bitcoin disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: 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 milhar
 amount_open_orders: Quantidade de ordens de compra ou venda de Bitcoin abertas.
Tipo: Inteiro
 eth: Saldo de Ethereum.
 available: Saldo de Ethereum disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Saldo de Ethereum available mais valores em ordens de venda abertas e transferências não autorizadas.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 amount_open_orders: Quantidade de ordens de compra ou venda de Ethereum abertas.
Tipo: Inteiro
 ltc: Saldo de Litecoin.
 available: Saldo de Litecoin disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: 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 milhar
 amount_open_orders: Quantidade de ordens de compra ou venda de Litecoin abertas.
Tipo: Inteiro
 xrp: Saldo de XRP (Ripple).
 available: Saldo de XRP (Ripple) disponível para operações.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Saldo de XRP (Ripple) available mais valores em ordens de venda abertas e transferências não autorizadas.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 amount_open_orders: Quantidade de ordens de compra ou venda de XRP (Ripple) abertas.
Tipo: Inteiro
 withdrawal_limits: Limites de saques e transferências.
 bch: 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 milhar
 total: Limite de transferência de BCash.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 brl: Limite de saque de Reais.
 available: Limite de saque em Reais disponível.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Limite de saque em Reais.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 btc: 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 milhar
 total: Limite de transferência de Bitcoin.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 eth: Limite de transferência de Ethereum.
 available: Limite de transferência de Ethereum disponível.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Limite de transferência de Ethereum.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 ltc: 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 milhar
 total: Limite de transferência de Litecoin.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 xrp: Limite de transferência de XRP (Ripple).
 available: Limite de transferência de XRP (Ripple) disponível.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 total: Limite de transferência de XRP Ripple.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
Exemplo 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
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_id: Número de identificação único da ordem por coin_pair.
Tipo: Inteiro
Erros 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: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: 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: Booleano
false : 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 milhar
 limit_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
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
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.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type [opcional]: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status_list [opcional]: Estado(s) da ordem a filtrar
Tipo: 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: Booleano
false : Sem execuções.
true : Com uma ou mais execuções.
 from_id [opcional]: Filtro para orders a partir do ID informado (inclusive).
Tipo: Inteiro
 to_id [opcional]: Filtro para orders até do ID informado (inclusive).
Tipo: Inteiro
 from_timestamp [opcional]: Filtro para orders criadas a partir do timestamp informado (inclusive).
Tipo: String
Formato: Era Unix 
 to_timestamp [opcional]: Filtro para orders criadas até do timestamp informado (inclusive).
Tipo: String
Formato: Era Unix 
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: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: 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: Booleano
false : 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 milhar
 limit_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
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
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-doc/#method_trade_api_orderbook, 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
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 full [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 venda
Erros 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 ou asks: 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: Inteiro
 is_owner: Informa se ordem pertence ao proprietário da chave TAPI.
Tipo: Booleano
Domínio de dados:
true : Pertence ao proprietário da chave TAPI
false : Não pertence ao proprietário da chave TAPI
 quantity: Quantidade disponível para compra/venda ao preço de limit_price.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 limit_price: Preço unitário de compra/venda.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 latest_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ção

Considere a seguinte sequência de eventos:

EventoUsuárioID da ordem
(order_id)		Última ordem contemplada
(latest_order_id)
Criação ordem de compraantonio_gomes10011001
Criação ordem de comprajose_silva10021002
Criação ordem de vendajose_silva10031003
Cancelamento de ordemjose_silva10021003

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
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 quantity: Quantidade da moeda digital a comprar/vender.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 8 casas decimais
Valor Mínimo:
BTC: 0.001
BCH: 0.001
ETH: 0.01
LTC: 0.01
XRP: 0.1
 limit_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,01
Erros 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."
240: Erro : "Saldo de XRP (Ripple) insuficiente para realizar a operação."
243: Erro : "Saldo de Ethereum insuficiente para realizar a operação."
222: Erro : "Quantidade mínima ou máxima de Bitcoin excedida."
223: Erro : "Quantidade mínima ou máxima de Litecoin excedida."
234: Erro : "Quantidade mínima ou máxima de BCash excedida."
242: Erro : "Quantidade mínima ou máxima de XRP excedida."
245: Erro : "Quantidade mínima ou máxima de Ethereum 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."
432: Erro : "Sua ordem está em processamento, caso ocorra algum problema seu saldo será extornado."

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: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: 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: Booleano
false : 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 milhar
 limit_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
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
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
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 quantity: Quantidade da moeda digital a comprar/vender.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 8 casas decimais
Valor Mínimo:
BTC: 0.001
BCH: 0.001
ETH: 0.01
LTC: 0.01
XRP: 0.1
 limit_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,01
Erros 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."
240: Erro : "Saldo de XRP (Ripple) insuficiente para realizar a operação."
243: Erro : "Saldo de Ethereum insuficiente para realizar a operação."
222: Erro : "Quantidade mínima ou máxima de Bitcoin excedida."
223: Erro : "Quantidade mínima ou máxima de Litecoin excedida."
234: Erro : "Quantidade mínima ou máxima de BCash excedida."
242: Erro : "Quantidade mínima ou máxima de XRP excedida."
245: Erro : "Quantidade mínima ou máxima de Ethereum 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."
432: Erro : "Sua ordem está em processamento, caso ocorra algum problema seu saldo será extornado."

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: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: 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: Booleano
false : 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 milhar
 limit_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
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
Exemplo de Resposta

place_market_buy_order

Descrição

Abre uma ordem de compra (buy ou bid) do par de moedas com volume em reais limite informado. A criação contempla o processo de bloqueio do saldo para execução da ordem e 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. Caso não seja possível executá-la totalmente por restrições no saldo disponível do usuário, o montante não executado é cancelado.

Parâmetros adicionais
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 cost: Volume em reais a ser bloqueado /utilizado para realizar a compra.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 5 casas decimais
Valor Mínimo: R$ 0.01
Erros 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."
222: Erro : "Quantidade mínima ou máxima de Bitcoin excedida."
223: Erro : "Quantidade mínima ou máxima de Litecoin excedida."
234: Erro : "Quantidade mínima ou máxima de BCash excedida."
242: Erro : "Quantidade mínima ou máxima de XRP excedida."
245: Erro : "Quantidade mínima ou máxima de Ethereum excedida."
227: Erro : "Número de casas decimais informado inválido."
432: Erro : "Sua ordem está em processamento, caso ocorra algum problema seu saldo será extornado."

Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status

Exemplo
params = {
    'tapi_method': 'place_market_buy_order',
    'tapi_nonce': '1',
    'coin_pair': 'BRLBTC',
    'cost': '50000.00',
}
Resultado
 order_id: Número de identificação da ordem, único por coin_pair.
Tipo: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: Estado da ordem.
Tipo: Inteiro
Domínio de dados:
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: Booleano
false : Sem execuções.
true : Com uma ou mais execuções.
 quantity: Quantidade da moeda digital a comprar/vender.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 cost: Custo total em reais máximo para realizar a compra.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
Exemplo de Resposta

place_market_sell_order

Descrição

Abre uma ordem de venda (sell ou ask) do par de moeda com quantidade da moeda digital informado. 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.

Parâmetros adicionais
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 quantity: Quantidade da moeda digital a comprar/vender.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar, até 8 casas decimais
Valor Mínimo:
BTC: 0.001
BCH: 0.001
ETH: 0.01
LTC: 0.01
XRP: 0.1
Erros 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."
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."
240: Erro : "Saldo de XRP (Ripple) insuficiente para realizar a operação."
243: Erro : "Saldo de Ethereum insuficiente para realizar a operação."
234: Erro : "Quantidade mínima ou máxima de BCash excedida."
222: Erro : "Quantidade mínima ou máxima de Bitcoin excedida."
245: Erro : "Quantidade mínima ou máxima de Ethereum excedida."
223: Erro : "Quantidade mínima ou máxima de Litecoin excedida."
242: Erro : "Quantidade mínima ou máxima de XRP excedida."
227: Erro : "Número de casas decimais informado inválido."
432: Erro : "Sua ordem está em processamento, caso ocorra algum problema seu saldo será extornado."

Além dos erros aplicáveis a todos os métodos. Detalhes em: Tabela de status

Exemplo
params = {
    'tapi_method': 'place_market_sell_order',
    'tapi_nonce': '1',
    'coin_pair': 'BRLBTC',
    'quantity': '1.03',
}
Resultado
 order_id: Número de identificação da ordem, único por coin_pair.
Tipo: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: Estado da ordem.
Tipo: Inteiro
Domínio de dados:
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: Booleano
false : Sem execuções.
true : Com uma ou mais execuções.
 quantity: Quantidade da moeda digital a comprar/vender.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
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
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_id: Número de identificação único da ordem.
Tipo: Inteiro
Erros 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: Inteiro
 coin_pair: Par de moedas.
Tipo: String
Domínio de dados:
BRLBTC : Real e Bitcoin
BRLBCH : Real e BCash
BRLETH : Real e Ethereum
BRLLTC : Real e Litecoin
BRLXRP : Real e XRP (Ripple)
 order_type: Tipo da ordem a ser filtrado.
Tipo: Inteiro
Domínio de dados:
1 : Ordem de compra
2 : Ordem de venda
 status: 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: Booleano
false : 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 milhar
 limit_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
 executed_quantity: Quantidade da moeda digital executada.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 executed_price_avg: Preço unitário médio de execução.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 fee: 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 milhar
 created_timestamp: Data e hora de criação da ordem.
Tipo: String
Format: Era Unix 
 updated_timestamp: Data e hora da última atualização da ordem. Não é alterado caso a ordem esteja em um estado final (ver status).
Tipo: String
Format: Era Unix 
 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_pair
Tipo: Inteiro
 quantity: Quantidade de moeda digital da operação.
Tipo: String
 price: Preço unitário da operação.
Tipo: String
 fee_rate: Comissão cobrada pelo serviço de intermediação. A comissão varia para ordens executadas e executoras.
Tipo: String
 executed_timestamp: Data e hora de execução da operação.
Tipo: String
Format: Era Unix 
Exemplo de Resposta

get_withdrawal

Descrição

Retorna os dados de uma transferência de moeda digital 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
BCH : BCash
BTC : Bitcoin
ETH : Ethereum
LTC : Litecoin
XRP : XRP (Ripple)
 withdrawal_id: Número de identificação da transferência/saque, único por coin.
Tipo: Inteiro
Erros 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: Inteiro
 coin: Moeda da transferência/saque.
Tipo: String
Domínio de dados:
BRL : Real
BCH : BCash
BTC : Bitcoin
ETH : Ethereum
LTC : Litecoin
XRP : XRP (Ripple)
 fee: Taxa paga pela transferência/saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 status: Estado da transferência/saque.
Tipo: Inteiro
1 : 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 cancelado
 description [opcional]: Texto para descrever a transferência ou saque.
Tipo: String
Tamanho: até 30 caracteres
 created_timestamp: Data e hora de registro do pedido de transferência/saque.
Tipo: String
Formato: Era Unix 
 updated_timestamp: Data e hora da última atualização no pedido de transferência/saque.
Tipo: String
Formato: Era Unix 
Campos específicos
Para coin igual a BRL:
 quantity: Valor bruto do saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 net_quantity: Valor líquido do saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 account: Texto com código do banco, agência e conta bancária de destino.
Tipo: String
Tamanho: até 40 caracteres
Se coin for uma moeda digital:
 quantity: Quantidade da transferência.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 address: Endereço de moeda digital de destino.
Tipo: String
Tamanho: até 40 caracteres
 tx: Transação da moeda digital.
Tipo: String
Tamanho: 64 caracteres
Para coin igual a XRP:
 destination_tag: Número que, junto ao endereço, remete a um destinatário de XRP. É necessário informar esse campo junto ao endereço para enviar XRP para uma exchange.
Tipo: Inteiro
Exemplo 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 uma criptomoeda, 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
BCH : BCash
BTC : Bitcoin
LTC : Litecoin
ETH : Ethereum
XRP : XRP (Ripple)
 description [opcional]: Texto para descrever a transferência ou saque.
Tipo: String
Tamanho: até 30 caracteres
Campos específicos
Para 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,00
 account_ref: ID de uma conta bancária já cadastrada e marcada como confiável .
Tipo: String
Tamanho: até 7 caracteres
Se coin for uma criptomoeda:
 address: Endereço Bitcoin/Ethereum/Litecoin/BCash/XRP (Ripple) marcado como confiável .
Tipo: String
 quantity: 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 BTC
 tx_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,000001 BTC
Valor Máximo: 0,01 BTC
 tx_aggregate [opcional]: transferência pode ser feita junto de outras transferências em uma mesma transação no Blockchain.
Tipo: Booleano
Valor padrão: True
 via_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: False
Para coin igual a XRP:
 destination_tag: Número que, junto ao endereço, remete a um destinatário de XRP. É necessário informar esse campo junto ao endereço para enviar XRP para uma exchange.
Tipo: Inteiro
Erros 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,000001 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."
239: Erro : "Endereço *[address]* inválido para transferência."
241: Erro : "Valor mínimo de transferência de XRP para endereço externo é 20 XRP."
244: Erro : "Valor mínimo de transferência de Ethereum para endereço externo é 0,001 ETH."

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: Inteiro
 coin: Moeda da transferência/saque.
Tipo: String
Domínio de dados:
BRL : Real
BCH : BCash
BTC : Bitcoin
ETH : Ethereum
LTC : Litecoin
XRP : XRP (Ripple)
 fee: Taxa paga pela transferência/saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 status: Estado da transferência/saque.
Tipo: Inteiro
1 : 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 cancelado
 description [opcional]: Texto para descrever a transferência ou saque.
Tipo: String
Tamanho: até 30 caracteres
 created_timestamp: Data e hora de registro do pedido de transferência/saque.
Tipo: String
Formato: Era Unix 
 updated_timestamp: Data e hora da última atualização no pedido de transferência/saque.
Tipo: String
Formato: Era Unix 
Campos específicos
Para coin igual a BRL:
 quantity: Valor bruto do saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 net_quantity: Valor líquido do saque.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 account: Texto com código do banco, agência e conta bancária de destino.
Tipo: String
Tamanho: até 40 caracteres
Se coin for uma moeda digital:
 quantity: Quantidade da transferência.
Tipo: String
Formato: Ponto como separador decimal, sem separador de milhar
 address: Endereço de moeda digital de destino.
Tipo: String
Tamanho: até 40 caracteres
 tx: Transação da moeda digital.
Tipo: String
Tamanho: 64 caracteres
Para coin igual a XRP:
 destination_tag: Número que, junto ao endereço, remete a um destinatário de XRP. É necessário informar esse campo junto ao endereço para enviar XRP para uma exchange.
Tipo: Inteiro
Exemplo de Resposta

Exemplo completo (Python 3):


import hashlib
import hmac
import json

from http import client
from urllib.parse import urlencode


# 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 = urlencode(params)

# Gerar MAC
params_string = REQUEST_PATH + '?' + params
H = hmac.new(bytes(MB_TAPI_SECRET, encoding='utf8'), digestmod=hashlib.sha512)
H.update(params_string.encode('utf-8'))
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 = client.HTTPSConnection(REQUEST_HOST)
    conn.request("POST", REQUEST_PATH, params, headers)

    # Print response data to console
    response = conn.getresponse()
    response = response.read()

    response_json = json.loads(response)
    print('status: {}'.format(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.