Trade API v1/v2
VERSÃO 3 - V3 - DA TRADE API ESTÁ DISPONÍVEL:
documentação mais consistente, melhorias de padronização, sincronia e novos métodos.

MIGRE PARA USUFRUIR DOS BENEFÍCIOS.
>> veja mais aqui
Conheça nossa página no
APIs: clients com exemplos para Desenvolvedores

Trade API v1/v2

Mercado Bitcoin

Essa página é direcionada a pessoas com conhecimento em programação que desejam lidar com negociações de forma automatizada. Abaixo estão disponíveis métodos para manipulação de chamadas à API de trade do Mercado Bitcoin. Esse código permite a criação de requisições para obtenção de informações sobre negociações, manipulação de ordens de compra e venda, entre outros.




1. Geração de Chaves

voltar ao índice

Para utilizar a API de trading do Mercado Bitcoin é necessário possuir uma conta no site. Caso não possua, crie uma agora mesmo clicando aqui.

Para gerar sua chave, vá em Configurações e clique em "Trade API (chaves)", no menu lateral. Digite um nome que identificará a chave a ser gerada e aperte "Criar nova". Para exibir as existentes, é necessário digitar seu PIN.


2. Estrutura das requisições

voltar ao índice

As requisições devem ser feitas para a URL:

https://www.mercadobitcoin.net/tapi/v2/

Taxa limite de requisições: O acesso à TAPI é limitado ao máximo de 60 requisições por usuário a cada 60 segundos.
Em caso de exceder esse limite, é retornado o erro "Taxa de requests acima do permitido.".


2.1. Formatos

voltar ao índice

2.1.1. Requisição

voltar ao índice

O corpo da requisição deve possuir os campos codificados em formato Form URL Encoded (Content-Type: application/x-www-form-urlencoded).
Todas as requisições possuem, pelo menos, dois campos:

method O nome do método desejado.

tonce Data e hora em formato Era Unix.

Exemplo

{ "method": "getInfo", "tonce": 1230989541 }

Transforma-se em:

method=getInfo&tonce=1230989541

2.1.2. Resposta

voltar ao índice

Todas as respostas são em formato JSON.


2.2. Cabeçalho

voltar ao índice

As requisições devem possuir dois cabeçalhos específicos:

Key
  • O identificador da chave TAPI gerada.
Sign
  • Código HMAC, utilizando SHA-512 como algoritmo e o segredo da chave TAPI como senha, deve ser codificada a lista de parâmetros da requisição POST para fins de autenticação.

2.3. Exemplo de requisição

voltar ao índice
          Key: b493d48364afe44d11c0165cf470a4164d1e2609911ef998be868d46ade3de4e
          Sign: f8e3183d38e6c51889582cb2...20205f1d850f87045f4420ad2271c8fd5f0cd8944be3
          Content-Type: application/x-www-form-urlencoded
          method=getInfo&tonce=1230989541
        


3. Requisições

voltar ao índice

3.1. Método getInfo

voltar ao índice

Retorna as informações de saldo da conta.

Campos:
Nenhum campo é necessário.

Campos de retorno:

  • success
    Inteiro: Retorna 1 caso tenha tido sucesso na requisição ou 0, caso contrário.
  • return
    Dicionário com os dados de retorno.
    • funds
      Dicionário com os saldos.
      • brl
        String: Saldo de Reais.
      • btc
        String: Saldo de Bitcoin.
      • ltc
        String: Saldo de Litecoin.
      • bch
        String: Saldo de BCash.
      • brl_with_open_orders
        String: Saldo de Reais, incluindo saldo em ordens abertas de compra de Bitcoin e Litecoin.
      • btc_with_open_orders
        String: Saldo de Bitcoin, incluindo saldo em ordens abertas de venda de Bitcoin.
      • ltc_with_open_orders
        String: Saldo de litecoin, incluindo saldo em ordens abertas de venda de Litecoin.
  • server_time
    Inteiro: Hora atual do servidor em Era Unix.
  • open_orders
    Inteiro: Quantidade total de ordens abertas de compra e venda.

Exemplo de retorno:

{
    'success': 1,
    'return': {
    'funds': {
    'ltc': '35.54820000',
    'brl': '50.00032',
    'btc': '22.14016638',
    'ltc_with_open_orders': '35.54820000',
    'brl_with_open_orders': '2050.00032',
    'btc_with_open_orders': '25.14016638'
  },
  'server_time': '1312174800',
  'open_orders': 0
}                        
}


3.2. Método OrderList

voltar ao índice

Retorna uma lista de ordens.

Campos

  • pair
    String (Obrigatório): Indica o par de moedas das ordens. Pode ser btc_brl, para bitcoin, ou ltc_brl, para litecoin.
  • type
    String: Tipo da ordem: buy, para ordens de compra, ou sell, para ordens de venda.
  • status
    String: Status das ordens.
    • active: Ordens ativas.
    • canceled: Ordens canceladas.
    • completed: Ordens executadas ou preenchidas.
  • from_id
    Inteiro: ID inicial da consulta.
  • end_id
    Inteiro: ID final da consulta.
  • since
    Inteiro: Data e hora em Era Unix das ordens a serem listadas, iniciando por este valor.
  • end
    Inteiro: Data e hora em Era Unix das ordens a serem listadas, terminando por este valor.

Campos de Retorno

  • success
    Inteiro: Retorna 1 caso tenha tido sucesso na requisição ou 0, caso contrário.
  • return
    Dicionário com os dados de retorno.
    • id:
      String: ID da ordem em questão.
      • status
        String: Status da ordem, com valores idênticos aos do campo de mesmo nome da requisição.
      • created
        Inteiro: Data e hora em Era Unix da criação da ordem.
      • price
        String: Preço unitário em reais.
      • volume
        String: Volume de compra ou venda da moeda digital em questão.
      • pair
        String: Indica o par de moedas da ordem. Pode ser btc_brl, para bitcoin, ou ltc_brl, para litecoin.
      • type
        String: Tipo da ordem: buy para ordens de compra, ou sell para ordens de venda.
      • operations
        Lista de operações referentes à ordem.
        • volume: Volume da operação.
        • price: Preço unitário, em reais, da operação.
        • rate: Taxa em percentual aplicada à operação.
        • created: Data e hora em Era Unix da operação.
  • server_time
    Inteiro: Hora atual do servidor em Era Unix.
  • open_orders
    Inteiro: Quantidade total de ordens abertas de compra e venda.

Exemplo de retorno:

{
  'success': 1,
  'return': {
  '1212': {
  'status': 'completed',
  'created': '1378929161',
  'price': '6.00000',
  'volume': '165.47309607',
  'pair': 'ltc_brl',
  'type': 'sell',
  'operations': {
  '443': {
  'volume': '20.00000000',
  'price': '6.00000',
  'rate': '0.70',
  'created': '1378929161'
},
'442': {
'volume': '30.00000000',
'price': '6.00000',
'rate': '0.70',
'created': '1378929161'
},
'441': {
'volume': '24.90600000',
'price': '6.01000',
'rate': '0.70',
'created': '1378929161'
}
}
},
'51': {
'status': 'canceled',
'created': '1377265355',
'price': '6.85000',
'volume': '17.82000000',
'pair': 'ltc_brl',
'type': 'buy',
'operations': {}
}
}
}


3.3. Método Trade

voltar ao índice

Cria uma ordem para um determinado par de moedas.

Campos

  • pair
    String (Obrigatório): Par de moedas: btc_brl ou ltc_brl.
  • type
    String (Obrigatório): Tipo da ordem: buy ou sell.
  • volume
    String (Obrigatório): Volume para compra ou venda.
  • price
    String (Obrigatório): Preço unitário em reais.

Campos de Retorno

  • success
    Inteiro: Retorna 1 caso tenha tido sucesso na requisição ou 0, caso contrário.
  • return
    Dicionário com os dados de retorno.
    • id:
      String: ID da ordem em questão.
      • status
        String: Status da ordem, com valores idênticos aos do campo de mesmo nome da requisição.
      • created
        Inteiro: Data e hora em Era Unix da criação da ordem.
      • price
        String: Preço unitário em reais.
      • volume
        String: Volume de compra ou venda da moeda digital em questão.
      • pair
        String: Indica o par de moedas da ordem. Pode ser btc_brl, para bitcoin, ou ltc_brl, para litecoin.
      • type
        String: Tipo da ordem: buy para ordens de compra, ou sell para ordens de venda.
      • operations
        Lista vazia de operações referentes à ordem.

Exemplo de retorno:

{
  'success': 1,
  'return': {
  '27176': {
  'status': 'canceled',                            
  'created': '1381414719',
  'price': '400.00000',
  'volume': '0.50000000',
  'pair': 'btc_brl',
  'type': 'sell',
  'operations': {}
}
}
}


3.4. Método CancelOrder

voltar ao índice

Cancela ordens em aberto.

Campos

  • pair
    String (Obrigatório): Par de moedas: btc_brl ou ltc_brl.
  • order_id
    String (Obrigatório): ID da ordem.

Campos de retorno

  • success
    Inteiro: Retorna 1 caso tenha tido sucesso na requisição ou 0, caso contrário.
  • return
    Dicionário com os dados de retorno.
    • id
      String: ID da ordem em questão.
      • status
        String: Status da ordem, com valores idênticos aos do campo de mesmo nome da requisição.
      • created
        Inteiro: Data e hora em Era Unix da criação da ordem.
      • price
        String: Preço unitário em reais.
      • volume
        String: Volume de compra ou venda da moeda digital em questão.
      • pair
        String: Indica o par de moedas da ordem. Pode ser btc_brl, para bitcoin, ou ltc_brl, para litecoin.
      • type
        String: Tipo da ordem: buy para ordens de compra, ou sell para ordens de venda.
      • operations
        Lista vazia de operações referentes à ordem.

Exemplo de retorno:

{
  'success': 1,
  'return': {
  '27176': {
  'status': 'active',                            
  'created': '1381414719',
  'price': '400.00000',
  'volume': '0.50000000',
  'pair': 'btc_brl',
  'type': 'sell',
  'operations': {}
}
}                        
}


3.5. Método withdrawal_bitcoin

voltar ao índice

Transferência de Bitcoins.

Campos

  • volume
    String (Obrigatório): Volume em Bitcoins da moeda digital para a operação.
  • bitcoin_address
    String (Obrigatório): Endereço Bitcon de destino.
    IMPORTANTE: Só é permitida a transferência para endereços 'confiáveis'. Endereços Bitcoin podem ser marcados como confiáveis em 'Configurações' > 'Endereços Bitcoin e Litecoin', com uso do token da autenticação em dois passos e do PIN. Essa funcionalidade só está disponível para usuários que possuem uma chave de Trade API ativa.

Campos de retorno

  • success
    Inteiro: Retorna 1 caso tenha tido sucesso na requisição ou 0, caso contrário.
  • return
    Dicionário com os dados de retorno.
    • withdrawal
      Dicionário com os dados da transferência.: ID da ordem em questão.
      • id
        String.: ID da transferência.
      • volume
        String: Volume da operação.
      • status
        String: Status da transferência. Domínio: (0: 'new', 1: 'open', 2: 'closed', 3: 'cancelled')
      • status_description
        String: Descrição do status da transferência.
      • bitcoin_address
        String: Endereço Bitcon de destino da transferência.
      • transaction
        String: Hash da Transação de Bitcoin de transferência.
      • created_timestamp
        Inteiro: Data e hora em Era Unix da criação da transferência.
      • updated_timestamp
        Inteiro: Data e hora em Era Unix da atualização da transferência.

    Exemplo de retorno:

    {
      'success': 1,
      'return': {
          'withdrawal' : {
            'id' : '1',
            'volume' : '0.50000000',
            'status' : '1',
            'status_description' : 'open',
            'bitcoin_address' : '1G38ybvfUyn96aJbKnzkifX2eEMH9N87ww',
            'transaction' : 'd9893c57880953f044bcf0c9f31b923459a2fc54e82e8c8544645b96da37726f',
            'created_timestamp' : '1387493109',
            'updated_timestamp' : '1387493116'
          }
      }
    }


    4. Considerações

    voltar ao índice

    4.1. Valores como strings

    voltar ao índice

    Para evitar erros de arredondamento entre dispositivos durante a comunicação, todos os valores são serializados em strings, pois internamente a representação é em decimal e não em float, que seria o resultado padrão da serialização JSON.


    Qualquer dúvida acesse nossa central de ajuda.


Segue abaixo um exemplo de código em Python para acesso à API de negociações. Em breve traremos exemplos em outras linguagens também.


import httplib
import urllib
import json
import hashlib
import hmac
import time

#para debugar
#import pdb
#pdb.set_trace()

# substitua com os dados da chave de acesso criada. Este dados são sigilosos, nunca os exponha de forma pública!
mercado_tapi_identificador = '<identificador>'
mercado_tapi_segredo = '<segredo>'

#substitua com o seu PIN de acesso
PIN = '<PIN>'

#nome do metodo que ira acessar na TAPI
metodo = 'getInfo'

#criar tonce
tonce = str(int(time.time()))

# parametros. Coloque os demais parametros para outros metodos quando necessario.
params = {
    'method': metodo,
    'tonce' : tonce
}
params = urllib.urlencode(params)

# criando o MAC
H = hmac.new(mercado_tapi_segredo, digestmod=hashlib.sha512)
H.update(params)
tapi_mac = H.hexdigest()

#cria o cabecalho
headers = {"Content-type": "application/x-www-form-urlencoded",
"Key":mercado_tapi_identificador,
"Sign":tapi_mac}

#realiza a chamada
conn = httplib.HTTPSConnection("www.mercadobitcoin.net")
conn.request("POST", "/tapi/v2/", params, headers)

#mostra resultado
response = conn.getresponse()
print response.status, response.reason
print json.load(response)
conn.close()