Disponibilizamos serviços que não exigem autenticação, como consultar a cotação de uma moeda, e serviços que exigem autenticação, como colocar uma ordem no book.
A API está disponível via WebSocket ou 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.
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.
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:
Este serviço retorna um array de ances em nosso book. Cada item é um array os seguintes itens, respectivamente:
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 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.
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"}%
Se a autenticação de dois fatores estiver ativada, o retorno da chamada a authenticate indica que a conta necessita do código 2FA. Neste caso, antes de poder acessar serviços como o GetUserInfo, informe o código 2FA chamando Authenticate2FA, repassando o token em Pending2FaToken:
➜ ~ curl -v -d '{"Code": "121992"}' -H 'Content-type: application/json' -H 'Pending2FaToken: f84136b9-84d0-4a12-8b56-ad6732c948ba' 'https://api.coinext.com.br:8443/AP/Authenticate2FA'
O script a seguir faz basicamente o que os comandos anteriores fizeram, mas está em Python:
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:
Exemplo de chamada de um serviço público, via WebSockets
Exemplo de chamada de um serviço público, via WebSockets, em Python
Exemplo de chamada de um serviço público, via WebSockets, em PHP
Nota: este exemplo usa Pawl como cliente de WebSocket.
A conexão via WebSocket suporta tanto a autenticação via login e senha quanto via chaves.
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
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:
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. Também é possível gerar chaves via HTTP, chamando AddUserAPIKey, apesar de serem suportadas apenas via WebSocket:
➜ ~ curl -X POST -d '{"UserId": 123, "Permissions": ["Trading"]}' -H 'Content-type: application/json' -H 'aptoken: 2ba21e9e-51b6-414f-98ae-7476fa21eda2' 'https://api.coinext.com.br:8443/AP/AddUserAPIKey'
{"APIKey":"1a731d439e0b5da1f051b32f17b7eae4","APISecret":"c13cc51ca35100f6ca644d3da937ea75","UserId":123,"Permissions":["Trading"],"Nonce":0}
Uma vez com as chave e o segredo, chame o serviço AuthenticateUser passando um JSON com os seguintes campos:
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.
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.