Autenticação

Todas as requisições à API TRXUp requerem autenticação usando um token Bearer e uma assinatura. Isso garante a segurança e integridade das suas requisições à API.

Obtendo Credenciais da API

Para começar a usar a API TRXUp, você precisará obter suas credenciais de API no painel:

1. Faça login no painel do cliente TRXUp
2. Abra Acesso à API, em Conta na barra lateral
3. Clique em Criar credenciais

O token e o segredo de assinatura são exibidos uma única vez, no momento em que são criados. O segredo nunca mais é mostrado — nem em parte, nem nessa tela. Se você o perder, emita um novo par.

A mesma tela permite restringir o par aos endereços IP de onde os seus próprios servidores chamam. Uma requisição corretamente assinada vinda de qualquer outro lugar é recusada.

TIP

Mantenha suas credenciais de API seguras e nunca as compartilhe publicamente. Seu segredo de API deve ser tratado como uma senha.

Cabeçalhos Obrigatórios

Cabeçalho	Descrição
Authorization: Bearer SEU_TOKEN_API	Seu token de API
X-Signature: SUA_ASSINATURA	Assinatura da requisição
Content-Type: application/json	O tipo de conteúdo deve ser JSON

Cálculo da Assinatura

A assinatura é calculada usando o hash SHA256 do corpo da requisição concatenado com seu segredo de API.

signature=$(echo -n "$requestBody$apiSecret" | sha256sum | cut -d' ' -f1)

Exemplo em Diferentes Linguagens

Bash

#!/bin/bash
API_TOKEN="seu_token_api"
API_SECRET="seu_segredo_api"
REQUEST_BODY='{"service":"energy","params":{"address":"ENDERECO_TRX","energy_amount":65000,"duration":1}}'

# Calcula a assinatura
SIGNATURE=$(echo -n "${REQUEST_BODY}${API_SECRET}" | sha256sum | cut -d' ' -f1)

# Faz a requisição à API
curl -X POST "https://api.trxup.com/v1/transaction/new" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"

Node.js

const crypto = require('crypto');
const axios = require('axios');

const apiToken = 'seu_token_api';
const apiSecret = 'seu_segredo_api';
const requestBody = JSON.stringify({
  service: 'energy',
  params: {
    address: 'ENDERECO_TRX',
    energy_amount: 65000,
    duration: 1
  }
});

// Calcula a assinatura
const signature = crypto
  .createHash('sha256')
  .update(requestBody + apiSecret)
  .digest('hex');

// Faz a requisição à API
axios({
  method: 'post',
  url: 'https://api.trxup.com/v1/transaction/new',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  data: requestBody
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

PHP

<?php
$apiToken = 'seu_token_api';
$apiSecret = 'seu_segredo_api';
$requestBody = json_encode([
  'service' => 'energy',
  'params' => [
    'address' => 'ENDERECO_TRX',
    'energy_amount' => 65000,
    'duration' => 1
  ]
]);

// Calcula a assinatura
$signature = hash('sha256', $requestBody . $apiSecret);

// Faz a requisição à API
$ch = curl_init('https://api.trxup.com/v1/transaction/new');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiToken,
  'X-Signature: ' . $signature,
  'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import hashlib
import json
import requests

api_token = 'seu_token_api'
api_secret = 'seu_segredo_api'
request_body = json.dumps({
  'service': 'energy',
  'params': {
    'address': 'ENDERECO_TRX',
    'energy_amount': 65000,
    'duration': 1
  }
})

# Calcula a assinatura
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Faz a requisição à API
headers = {
  'Authorization': f'Bearer {api_token}',
  'X-Signature': signature,
  'Content-Type': 'application/json'
}

response = requests.post(
  'https://api.trxup.com/v1/transaction/new',
  headers=headers,
  data=request_body
)

print(response.json())

Assinatura versão 2 (opcional)

A versão 2 da assinatura é uma forma opcional e mais robusta de assinar as mesmas requisições. Você a ativa por requisição enviando o cabeçalho X-Signature-Version: 2. Uma requisição sem esse cabeçalho, ou com X-Signature-Version: 1, é verificada exatamente como descrito acima, então integrações existentes não precisam de nenhuma alteração. A versão 1 continua funcionando e não há prazo para a mudança; para novas integrações recomendamos a versão 2.

O que a versão 2 acrescenta:

• A assinatura fica vinculada ao endpoint. O método e o caminho fazem parte do que é assinado, então uma requisição assinada para /v1/subscription/check não pode ser reenviada para /v1/subscription/stop.
• Ela expira após 5 minutos. O timestamp assinado deve estar a no máximo 300 segundos do relógio do servidor.
• Cada requisição assinada é aceita uma única vez. O nonce assinado não pode ser reutilizado, então uma requisição interceptada não pode ser reenviada.

Cabeçalhos Obrigatórios (versão 2)

Cabeçalho	Descrição
Authorization: Bearer YOUR_API_TOKEN	Seu token de API, como na versão 1
X-Signature-Version: 2	Seleciona a versão 2 da assinatura para esta requisição
X-Timestamp: 1761040800	Horário Unix atual em segundos, como inteiro decimal
X-Nonce: 7f3c9a12b4e8d05c	Um valor único para cada requisição: de 8 a 128 caracteres de A–Z a–z 0–9 . _ ~ - (um UUID ou 16 ou mais caracteres hexadecimais aleatórios servem). Nunca reutilize um nonce
X-Signature: YOUR_SIGNATURE	Assinatura da requisição, calculada como abaixo
Content-Type: application/json	O tipo de conteúdo deve ser JSON

Cálculo da Assinatura (versão 2)

X-Signature é o HMAC-SHA256, em hexadecimal minúsculo, da string a seguir, com seu segredo de API como chave:

METHOD + "\n" + PATH + "\n" + X-Timestamp + "\n" + X-Nonce + "\n" + BODY

• METHOD é POST (todos os endpoints /v1 usam POST).
• PATH é o caminho da requisição exatamente como enviado, sem o host e sem query string, por exemplo /v1/transaction/new.
• X-Timestamp e X-Nonce são exatamente os valores dos cabeçalhos que você envia.
• BODY são os bytes brutos exatos do corpo da requisição (uma string vazia se o corpo estiver vazio). Assine os bytes que você envia: se o JSON for serializado novamente depois de assinado, a assinatura não vai conferir.
• "\n" é uma única quebra de linha (0x0A). Não há quebra de linha depois do corpo.

O servidor verifica primeiro a assinatura, depois se X-Timestamp está a no máximo 300 segundos (5 minutos) do próprio relógio, em qualquer direção, e por fim se a sua conta ainda não usou esse nonce (os nonces são lembrados por cerca de 11 minutos). Mantenha o relógio do seu servidor sincronizado via NTP. Uma nova tentativa é uma nova requisição: precisa de um novo timestamp, um novo nonce e uma nova assinatura.

Vetor de Teste

Confira seu código com estes valores antes de chamar a API:

Entrada	Valor
Segredo de API	your_api_secret
Método	POST
Caminho	/v1/transaction/new
X-Timestamp	1761040800
X-Nonce	7f3c9a12b4e8d05c
Corpo	{"service":"energy","params":{"address":"TRX_ADDRESS","energy_amount":65000,"duration":1}}

A string a ser assinada (cinco linhas, sem quebra de linha depois da última):

POST
/v1/transaction/new
1761040800
7f3c9a12b4e8d05c
{"service":"energy","params":{"address":"TRX_ADDRESS","energy_amount":65000,"duration":1}}

X-Signature esperada:

56576e1faecaca2b2533bee6124e7ece2b023665addb2f2e79b8ac83bf8104e8

Erros (versão 2)

Uma verificação malsucedida retorna a mesma resposta HTTP 401 da versão 1, com "code": 1. Uma assinatura, timestamp ou nonce incorreto ou ausente, ou um X-Signature-Version diferente de 1 ou 2, recebe o habitual Incorrect token or signature. Somente depois de uma assinatura válida podem aparecer duas mensagens mais específicas:

• X-Timestamp is N seconds from this server's clock; at most 300 either way is accepted — seu relógio está fora de sincronia: sincronize-o via NTP.
• This X-Nonce was already used; every request needs a new one — gere um novo nonce para cada requisição, inclusive nas novas tentativas.

Exemplos da Versão 2 em Diferentes Linguagens

Bash

#!/bin/bash
API_TOKEN="your_api_token"
API_SECRET="your_api_secret"
REQUEST_PATH="/v1/transaction/new"
REQUEST_BODY='{"service":"energy","params":{"address":"TRX_ADDRESS","energy_amount":65000,"duration":1}}'

# A new timestamp and nonce for every request
TIMESTAMP=$(date +%s)
NONCE=$(openssl rand -hex 16)

# Calculate signature: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY, no trailing newline
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "POST" "$REQUEST_PATH" "$TIMESTAMP" "$NONCE" "$REQUEST_BODY" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')

# Make API request
curl -X POST "https://api.trxup.com${REQUEST_PATH}" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "X-Signature-Version: 2" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Nonce: ${NONCE}" \
  -H "X-Signature: ${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"

Node.js

const crypto = require('crypto');
const axios = require('axios');

const apiToken = 'your_api_token';
const apiSecret = 'your_api_secret';
const requestPath = '/v1/transaction/new';
const requestBody = JSON.stringify({
  service: 'energy',
  params: {
    address: 'TRX_ADDRESS',
    energy_amount: 65000,
    duration: 1
  }
});

// A new timestamp and nonce for every request
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();

// Calculate signature: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY
const payload = ['POST', requestPath, timestamp, nonce, requestBody].join('\n');
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(payload)
  .digest('hex');

// Make API request (send exactly the body that was signed)
axios({
  method: 'post',
  url: 'https://api.trxup.com' + requestPath,
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'X-Signature-Version': '2',
    'X-Timestamp': timestamp,
    'X-Nonce': nonce,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  data: requestBody
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

PHP

<?php
$apiToken = 'your_api_token';
$apiSecret = 'your_api_secret';
$requestPath = '/v1/transaction/new';
$requestBody = json_encode([
  'service' => 'energy',
  'params' => [
    'address' => 'TRX_ADDRESS',
    'energy_amount' => 65000,
    'duration' => 1
  ]
]);

// A new timestamp and nonce for every request
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));

// Calculate signature: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY
$payload = implode("\n", ['POST', $requestPath, $timestamp, $nonce, $requestBody]);
$signature = hash_hmac('sha256', $payload, $apiSecret);

// Make API request (send exactly the body that was signed)
$ch = curl_init('https://api.trxup.com' . $requestPath);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestBody);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiToken,
  'X-Signature-Version: 2',
  'X-Timestamp: ' . $timestamp,
  'X-Nonce: ' . $nonce,
  'X-Signature: ' . $signature,
  'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Python

import hashlib
import hmac
import json
import time
import uuid
import requests

api_token = 'your_api_token'
api_secret = 'your_api_secret'
request_path = '/v1/transaction/new'
# Compact separators: the same bytes as the test vector and the other examples
request_body = json.dumps({
  'service': 'energy',
  'params': {
    'address': 'TRX_ADDRESS',
    'energy_amount': 65000,
    'duration': 1
  }
}, separators=(',', ':'))

# A new timestamp and nonce for every request
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex

# Calculate signature: METHOD\nPATH\nTIMESTAMP\nNONCE\nBODY
payload = '\n'.join(['POST', request_path, timestamp, nonce, request_body])
signature = hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

# Make API request (send exactly the bytes that were signed)
headers = {
  'Authorization': f'Bearer {api_token}',
  'X-Signature-Version': '2',
  'X-Timestamp': timestamp,
  'X-Nonce': nonce,
  'X-Signature': signature,
  'Content-Type': 'application/json'
}

response = requests.post(
  'https://api.trxup.com' + request_path,
  headers=headers,
  data=request_body.encode()
)

print(response.json())