Uwierzytelnianie

Wszystkie żądania API do TRXUp API wymagają uwierzytelniania za pomocą tokenu Bearer i podpisu. Zapewnia to bezpieczeństwo i integralność żądań API.

Uzyskiwanie danych uwierzytelniania API

Aby rozpocząć pracę z API TRXUp, musisz uzyskać dane uwierzytelniania API z panelu:

1. Zaloguj się do panelu klienta TRXUp
2. Otwórz Dostęp do API, w sekcji Konto na pasku bocznym
3. Naciśnij Utwórz dane uwierzytelniające

Token i sekret podpisu są pokazywane dokładnie raz, w chwili utworzenia. Sekret nie zostanie wyświetlony ponownie — ani we fragmencie, ani na tym ekranie. Jeśli go zgubisz, wydaj nową parę.

Na tym samym ekranie można ograniczyć parę do adresów IP, z których dzwonią Twoje własne serwery. Poprawnie podpisane żądanie z innego adresu zostanie wtedy odrzucone.

TIP

Zachowaj swoje dane uwierzytelniania API w bezpiecznym miejscu i nigdy nie udostępniaj ich publicznie. Twój sekret API powinien być traktowany jak hasło.

Wymagane nagłówki

Nagłówek	Opis
Authorization: Bearer YOUR_API_TOKEN	Twój token API
X-Signature: YOUR_SIGNATURE	Podpis żądania
Content-Type: application/json	Typ zawartości musi być JSON

Obliczanie podpisu

Podpis jest obliczany przy użyciu hasza SHA256 treści żądania połączonej z twoim sekretem API.

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

Przykład w różnych językach

Bash

#!/bin/bash
API_TOKEN="twoj_token_api"
API_SECRET="twoj_sekret_api"
REQUEST_BODY='{"service":"energy","params":{"address":"ADRES_TRX","energy_amount":65000,"duration":1}}'

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

# Wykonaj żądanie 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 = 'twoj_token_api';
const apiSecret = 'twoj_sekret_api';
const requestBody = JSON.stringify({
  service: 'energy',
  params: {
    address: 'ADRES_TRX',
    energy_amount: 65000,
    duration: 1
  }
});

// Oblicz podpis
const signature = crypto
  .createHash('sha256')
  .update(requestBody + apiSecret)
  .digest('hex');

// Wykonaj żądanie 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 = 'twoj_token_api';
$apiSecret = 'twoj_sekret_api';
$requestBody = json_encode([
  'service' => 'energy',
  'params' => [
    'address' => 'ADRES_TRX',
    'energy_amount' => 65000,
    'duration' => 1
  ]
]);

// Oblicz podpis
$signature = hash('sha256', $requestBody . $apiSecret);

// Wykonaj żądanie 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 = 'twoj_token_api'
api_secret = 'twoj_sekret_api'
request_body = json.dumps({
  'service': 'energy',
  'params': {
    'address': 'ADRES_TRX',
    'energy_amount': 65000,
    'duration': 1
  }
})

# Oblicz podpis
signature = hashlib.sha256((request_body + api_secret).encode()).hexdigest()

# Wykonaj żądanie 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())

Podpis w wersji 2 (opcjonalny)

Podpis w wersji 2 to opcjonalny, silniejszy sposób podpisywania tych samych żądań. Włączasz go dla każdego żądania osobno, wysyłając nagłówek X-Signature-Version: 2. Żądanie bez tego nagłówka lub z X-Signature-Version: 1 jest sprawdzane dokładnie tak, jak opisano powyżej, więc istniejące integracje nie wymagają żadnych zmian. Wersja 1 nadal działa i nie ma terminu przejścia; dla nowych integracji zalecamy wersję 2.

Co dodaje wersja 2:

• Podpis jest powiązany z endpointem. Metoda i ścieżka są częścią podpisywanych danych, więc żądania podpisanego dla /v1/subscription/check nie da się odtworzyć na /v1/subscription/stop.
• Wygasa po 5 minutach. Podpisany znacznik czasu może różnić się od zegara serwera najwyżej o 300 sekund.
• Każde podpisane żądanie jest przyjmowane tylko raz. Podpisanego nonce nie można użyć ponownie, więc przechwyconego żądania nie da się odtworzyć.

Wymagane nagłówki (wersja 2)

Nagłówek	Opis
Authorization: Bearer YOUR_API_TOKEN	Twój token API, tak jak w wersji 1
X-Signature-Version: 2	Wybiera podpis w wersji 2 dla tego żądania
X-Timestamp: 1761040800	Bieżący czas Unix w sekundach, jako dziesiętna liczba całkowita
X-Nonce: 7f3c9a12b4e8d05c	Unikalna wartość dla każdego żądania: 8–128 znaków z A–Z a–z 0–9 . _ ~ - (wystarczy UUID lub co najmniej 16 losowych znaków szesnastkowych). Nigdy nie używaj nonce ponownie
X-Signature: YOUR_SIGNATURE	Podpis żądania, obliczony jak poniżej
Content-Type: application/json	Typ zawartości musi być JSON

Obliczanie podpisu (wersja 2)

X-Signature to HMAC-SHA256 poniższego ciągu, zapisany małymi literami szesnastkowymi, z Twoim sekretem API jako kluczem:

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

• METHOD to POST (wszystkie endpointy /v1 używają POST).
• PATH to ścieżka żądania dokładnie w takiej postaci, w jakiej jest wysyłana, bez hosta i bez query string, np. /v1/transaction/new.
• X-Timestamp i X-Nonce to dokładnie wartości wysyłanych nagłówków.
• BODY to dokładne surowe bajty treści żądania (pusty ciąg, jeśli treść jest pusta). Podpisuj bajty, które wysyłasz: jeśli JSON zostanie ponownie zserializowany po podpisaniu, podpis się nie zgodzi.
• "\n" to pojedynczy znak nowego wiersza (0x0A). Po treści nie ma znaku nowego wiersza.

Serwer najpierw sprawdza podpis, potem to, czy X-Timestamp różni się od jego zegara najwyżej o 300 sekund (5 minut) w dowolną stronę, a na końcu to, czy Twoje konto nie użyło już tego nonce (nonce są pamiętane przez około 11 minut). Synchronizuj zegar swojego serwera przez NTP. Ponowienie to nowe żądanie: potrzebuje nowego znacznika czasu, nowego nonce i nowego podpisu.

Wektor testowy

Przed wywołaniem API sprawdź swój kod na tych wartościach:

Dane wejściowe	Wartość
Sekret API	your_api_secret
Metoda	POST
Ścieżka	/v1/transaction/new
X-Timestamp	1761040800
X-Nonce	7f3c9a12b4e8d05c
Treść	{"service":"energy","params":{"address":"TRX_ADDRESS","energy_amount":65000,"duration":1}}

Ciąg do podpisania (pięć wierszy, bez znaku nowego wiersza po ostatnim):

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

Oczekiwany X-Signature:

56576e1faecaca2b2533bee6124e7ece2b023665addb2f2e79b8ac83bf8104e8

Błędy (wersja 2)

Nieudana weryfikacja zwraca tę samą odpowiedź HTTP 401 co w wersji 1, z "code": 1. Błędny lub brakujący podpis, znacznik czasu albo nonce, a także X-Signature-Version inny niż 1 lub 2, otrzymują zwykły komunikat Incorrect token or signature. Dopiero po poprawnym podpisie mogą pojawić się dwa bardziej szczegółowe komunikaty:

• X-Timestamp is N seconds from this server's clock; at most 300 either way is accepted — Twój zegar się rozjechał: zsynchronizuj go przez NTP.
• This X-Nonce was already used; every request needs a new one — generuj nowy nonce dla każdego żądania, także przy ponowieniach.

Przykłady wersji 2 w różnych językach

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())