API


Nossa API permite que você execute todas as operações que você já faz manualmente pelo nosso site. Ela disponibiliza tanto serviços que não exijam autenticação (como consultar a cotação de uma moeda) quanto serviços que exigem autenticação (como colocar uma ordem no book). A API está disponível tanto via WebSocket quanto HTTP.

A seguir temos diversos exemplos de uso da API com JavaScript, Python e até via curl, organizados da seguinte maneira:

Ao final está a documentação detalhada dos serviços.

Acesso via HTTP

Nossa API disponibiliza diversos serviços via HTTP, cada um deles numa URL específica, seguindo o formato https://api.coinext.com.br:8443/AP/NomeDoServiço. Existem diversos serviços disponíveis, como CancelOrder, CreateQuote e GetUserInfo, geralmente acessíveis via POST, enviando e recebendo dados no formato JSON.

A vasta maioria dos serviços exige autenticação. Para isso, acesse o serviço authenticate, enviando o login e senha via basic authentication. Pegue o atributo Token do JSON retornado e repasse-o no HTTP header aptoken nas chamadas dos serviços seguintes.

Serviços que Não Exigem Autenticação

Alguns serviços, como o serviço para obter os lances em nosso book (e também os valores da última negociação, de compra e de venda) não demandam autenticação. O exemplo a seguir ilustra este serviço (GetL2Snapshot):

$ curl -X POST -d '{"OMSId": 1, "InstrumentId": 1, "Depth": 1}' -H 'Content-type: application/json' 'https://api.coinext.com.br:8443/AP/GetL2Snapshot'
[[7367751,1,1526407423102,0,31736.94,1,31544.81,1,0.002,0],[7367751,1,1526407423102,0,31736.94,1,31529.89,1,0.002,0], [7367751,0,1526407423102,0,31736.94,3,24000,1,0.017224,0],[7367751,1,1526407423102,0,31736.94,1,31840.79,1,0.27218,1], [7367751,1,1526407423102,0,31736.94,1,37622.02,1,0.00000062,1],[7367751,1,1526407423102,0,31736.94,1,37623.87,1,0.00000045,1]]%

Neste exemplo, o único parâmetro de entrada que importa é o InstrumentId, cujo código representa o par de moedas envolvidas:

  • BTCBRL: 1
  • LTCBRL: 2
  • ETHBRL: 4
  • XRPBRL: 6

Este serviço retorna um array de ances em nosso book. Cada item é um array os seguintes itens, respectivamente:

  1. Market Data Update ID: Identificador sequencial do "snapshot".
  2. Accounts: número de contas associadas
  3. Action Date Time: "timestamp" da entrada (número de milisegundos desde 01/01/1970). Ex: em javascript, new Date(1526407423102) retorna 2018-05-15T18:03:43.102Z
  4. Action Type: tipo do lance.
  5. Last Trade Price: valor da última negociação. Sim, é o mesmo número para todas os arrays retornados por este serviço.
  6. Orders: número de ordens associadas.
  7. Price: Preço do lance.
  8. Instrument Id: Código do instrumento
  9. Quantity: Quantidade disponível para compra ou venda neste lance.
  10. Tipo do lance: 0 = compra, 1 = venda

Os primeiros lances do array são lances de compra (última coluna=0) e estão ordenados com o preços decrescentes. A seguir, vem os lances de venda (última coluna=1), ordenados com preços crescentes. Logo, o maior lance de compra (preço de compra está no primeiro lance (31544.81, do array [7367751,1,1526407423102,0,31736.94,1,31544.81,1,0.002,0]) e o menor valor de venda (preço de venda está no ponto em que a última coluna passa de 0 para 1 (31840.79, de [7367751,1,1526407423102,0,31736.94,1,31840.79,1,0.27218,1]). O valor da última negociação está em todas os lances (linhas) e é de 31736.94.

Serviços que Exigem Autenticação

Serviços que exigem autenticação necessitam que seja passado um token junto com este serviço. Para obtê-lo, chamer o serviço que faz a autenticação (authenticate). Com o token em mão, prossiga e chame os demais serviços (neste exemplo, o serviço GetUserInfo). Lembre-se de substituir o login e a senha.

Usando o Curl

curl -v 'https://your.email%40some-domain.com:your-password@api.coinext.com.br:8443/AP/authenticate'
*   Trying 104.41.52.230...
* TCP_NODELAY set
* Connected to api.coinext.com.br (104.41.52.230) port 8443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: api.coinext.com.br
* Server certificate: AlphaSSL CA - SHA256 - G2
* Server certificate: GlobalSign Root CA
* Server auth using Basic with user 'your.email@some-domain.com'
> GET /AP/authenticate HTTP/1.1
> Host: api.coinext.com.br:8443
> Authorization: Basic Z1FuZHkJKzdX3Y29pbmW4dC5jg20xYnI6bHVyZWlhMTIzU2VjYK==
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Transfer-Encoding: chunked
< Server: Microsoft-HTTPAPI/2.0
< Access-Control-Allow-Origin: *
< Date: Wed, 18 Apr 2018 21:03:10 GMT
<
* Connection #0 to host api.coinext.com.br left intact
{ "Authenticated": true,  "UserId": 195, "Token":"f84136b9-84d0-4a12-8b56-ad6732c948ba", "AccountId":"198", "OMSId":"1" }%

De posse do token f84136b9-84d0-4a12-8b56-ad6732c948ba, pode-se invocar os serviços seguintes. Por exemplo, fazer uma simples consulta ao GetUserInfo:

➜  ~ curl -v -X POST -d '{}' -H 'Content-type: application/json' -H 'aptoken: f84136b9-84d0-4a12-8b56-ad6732c948ba' 'https://api.coinext.com.br:8443/AP/GetUserInfo'
Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 104.41.52.230...
* TCP_NODELAY set
* Connected to api.coinext.com.br (104.41.52.230) port 8443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
* Server certificate: api.coinext.com.br
* Server certificate: AlphaSSL CA - SHA256 - G2
* Server certificate: GlobalSign Root CA
> POST /AP/GetUserInfo HTTP/1.1
> Host: api.coinext.com.br:8443
> User-Agent: curl/7.54.0
> Accept: */*
> Content-type: application/json
> aptoken: aebb9625-4231-491e-b0d4-34c780f42ed0
> Content-Length: 2
>
* upload completely sent off: 2 out of 2 bytes
< HTTP/1.1 200 OK
< Content-Length: 309
< Server: Microsoft-HTTPAPI/2.0
< Access-Control-Allow-Origin: *
< Date: Thu, 19 Apr 2018 02:18:09 GMT
<
* Connection #0 to host api.coinext.com.br left intact
{"UserId":195,"UserName":"your.email@some-domain.com","Email":"your.email@some-domain.com","PasswordHash":"","PendingEmailCode":"","EmailVerified":true,"AccountId":198,"DateTimeCreated":"2018-04-15T13:44:04Z","AffiliateId":0,"RefererId":0,"OMSId":1,"Use2FA":false,"Salt":"","PendingCodeTime":"0001-01-01T00:00:00Z"}%

Em Python

O script a seguir faz basicamente o que os comandos anteriores fizeram, mas está em Python:

WebSockets

A vasta maioria dos serviços estão disponíveis através via HTTP/REST. Entretanto, alguns serviços, principalmente os que usam streaming de dados, como SubscribeTicker, estão disponíveis apenas via WebSockets.

Para acessá-los, uma conexão em wss://api.coinext.com.br/WSGateway/. Para invocar os serviços, envie JSONs no formato { "m": 0, "i": next_ivalue, "n": service_name, "o": json.dumps(payload) }, onde:

  • next_ivalue: número incremental (dentro da mesma conexão)
  • service_name: nome do serviço chamado. Ex: SubscribeTicker
  • payload: string com o json específico para o serviço chamado. Ex: "{\"OMSId\": 1, \"InstrumentId\": 1, \"Interval\": 60}"

Exemplos

SubscribeTicker

Exemplo de chamada de um serviço público, via WebSockets

Em Javascript
Em Python

Exemplo de chamada de um serviço público, via WebSockets, em Python

Em PHP

Exemplo de chamada de um serviço público, via WebSockets, em PHP

Nota: este exemplo usa Pawl como cliente de WebSocket.

Serviços que exigem autenticação

A conexão via WebSocket suporta tanto a autenticação via login e senha quanto via chaves.

Autenticando-se usando login e senha

Antes de chamar um serviço que exija que você já esteja autenticado, como GetUserInfo, chame o serviço WebAuthenticateUser.

Exemplo a seguir ilustra de chamada de um serviço que precisam de autenticação (GetUserInfo), via WebSockets. Lembre-se de deixar o login/senha na chamada a WebAuthenticateUser

Autenticando-se usando chaves

Usar login/senha para autenticação funciona, mas pode não ser o método mais adequado para a o seu caso de uso. Como alternativa, temos a opção da autenticação via chaves. Para usar este método, siga os passos:

1. Gere a chave/segredo

Gere uma nova chave usando o serviço AddUserAPIKey.

Note: guarde esta chave e o segredo retornados para usá-los tantas vezes quanto necessárias no passo 2. Ou seja, não gere uma nova chave a cada autenticação.

Observe que é necessário autenticar via login/senha para gerar as chaves.

2. Use a chave/segredo nas próximas conexões

Uma vez com as chave e o segredo, chame o serviço AuthenticateUser passando um JSON com os seguintes campos:

  • Nonce: Um número sequencial que não deve se repetir e, cada vez que usado, deve ser maior que o número anterior. Dica: use o timestamp.
  • UserId: o código do usuário. Dica: faz parte do retorno de WebAuthenticateUser.
  • APIKey: A chave gerada no passo anterior
  • Signature: o resultado da assinatura da string composta pela concatenação dos elementos anteriores (Nonce, UserId e APIKey). O algoritmo para assinar é o HMAC-SHA256 usando secret (que foi gerado junto com a APIKey) como segredo.

O script a seguir ilustra um login usando este método. Os pontos centrais estão na função create_sha256_signature e em sua chamada.

Próximos Passos

O documento a seguir lista os serviços disponíveis. Apesar do acesso via HTTP/REST ser mais simples e direto, recomenda-se o uso via WebService, já que nem todos os serviços documentados abaixo estarem disponíveis em HTTP.