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

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."
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."
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."
242: Erro : "Quantidade mínima (0,1 XRP) 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."
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."

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, 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 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

 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

 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

 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.

 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

 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

 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

 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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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

 execution_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 a ser filtrado.

Tipo: String
Domínio de dados:

BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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

 execution_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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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:

false : Pertence ao proprietário da chave TAPI
true : 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:

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 BCash
BRLXRP : Real e XRP (Ripple)

 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, até 8 casas decimais
Valor Mínimo: 0,001 BTC ou 0,009 LTC

 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."
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: Inteiro

 coin_pair: Par de moedas.

Tipo: String
Domínio de dados:

BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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

 execution_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 (BTC)
BRLLTC : Real e Litecoin (LTC)
BRLBCH : Real e BCash
BRLXRP : Real e XRP (Ripple)

 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, até 8 casas decimais
Valor Mínimo: 0,001 BTC ou 0,009 LTC

 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."
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: Inteiro

 coin_pair: Par de moedas.

Tipo: String
Domínio de dados:

BRLBTC : Real e Bitcoin
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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

 execution_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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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
BRLLTC : Real e Litecoin
BRLBCH : Real e BCash
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

 execution_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
BTC : Bitcoin
LTC : Litecoin
BCH : BCash
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
BTC : Bitcoin
LTC : Litecoin
BCH : BCash
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
BTC : Bitcoin
LTC : Litecoin
BCH : BCash
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/Litecoin/BCash/XRP (Ripple) marcado como confiável .

Tipo: String
Tamanho: até 40 caracteres

 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."

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
BTC : Bitcoin
LTC : Litecoin
BCH : BCash
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):

# -*- 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