TRC20-Token-Transaktionen auf TRON erstellen

Einführung

Dieses Tutorial behandelt die TRC20-Endpunkte der Chaingateway-V2-API: eine TRON-Adresse erstellen, einen Token-Contract auslesen, ein Token-Guthaben prüfen und einen TRC20-Transfer senden. Beispiele gibt es in Shell (cURL), PHP (Guzzle), Python (Requests) und JavaScript (Axios).

Informationen zum Erhalt eines API-Keys und zur Autorisierung finden Sie im Abschnitt Schnellstart der Chaingateway-Dokumentation.

Was die API tut und was nicht

Die API hat keinen Endpunkt, der einen Smart Contract kompiliert oder deployt. Es gibt keine Route, die einen neuen TRC20-Contract im TRON-Netzwerk veröffentlicht, und keiner der TRON-Endpunkte akzeptiert Contract-Bytecode. Jede TRC20-Route nimmt eine contractaddress eines Tokens entgegen, das bereits on-chain existiert, USDT ebenso wie jeder andere TRC20-Token.

Wenn Sie nach einem Weg suchen, Ihren eigenen Token-Contract zu deployen, ist diese API nicht das richtige Werkzeug für diesen Schritt. Sobald der Contract deployt ist, decken die folgenden Endpunkte den Teil ab, den die meisten Integrationen tatsächlich brauchen: Adressen, Guthaben, Transfers und Benachrichtigungen.

Was Sie erreichen wollen	Endpunkt
Eine TRON-Adresse erstellen	`POST /v2/tron/addresses`
Einen bestehenden Private Key importieren	`POST /v2/tron/addresses/import`
Name, Symbol, Dezimalstellen und Supply lesen	`GET /v2/tron/trc20/{contract_address}`
Ein Token-Guthaben lesen	`GET /v2/tron/balances/{address}/trc20/{contract_address}`
Einen TRC20-Transfer senden	`POST /v2/tron/transactions/trc20`
Einen Transfer bauen, ohne ihn zu broadcasten	`POST /v2/tron/transactions/trc20/build`
Eine signierte Transaktion broadcasten	`POST /v2/tron/transactions/broadcast`
Über eingehende Token benachrichtigt werden	`POST /v2/tron/webhooks`

Schritt 1: Eine TRON-Adresse erstellen

Die sendende Adresse muss Chaingateway bekannt sein. Erstellen Sie sie entweder über die API oder importieren Sie einen bestehenden Private Key über POST /v2/tron/addresses/import.

Übergeben Sie ein password, wird der Private Key verschlüsselt gespeichert, und Sie signieren spätere Transaktionen mit diesem Passwort. Lassen Sie das Passwort weg, enthält die Antwort den Private Key selbst, und Sie müssen ihn mit jeder Transaktionsanfrage mitsenden. Der Ansatz mit Passwort wird ausführlich unter Wallet-Verwaltung beschrieben.

curl --request POST\
    --url https://api.chaingateway.io/v2/tron/addresses\
    --header 'Accept: application/json'\
    --header 'content-type: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'\
    --data '{"password":"test123"}'

import requests

url = "https://api.chaingateway.io/v2/tron/addresses"
payload = {"password": "test123"}
headers = {
    'Accept': 'application/json',
    'content-type': 'application/json',
    'Authorization': 'YOUR_API_TOKEN'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://api.chaingateway.io/v2/tron/addresses';
const payload = { password: 'test123' };
const headers = {
  'Accept': 'application/json',
  'content-type': 'application/json',
  'Authorization': 'YOUR_API_TOKEN'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://api.chaingateway.io/v2/tron/addresses', [
    'headers' => [
        'Accept' => 'application/json',
        'content-type' => 'application/json',
        'Authorization' => 'YOUR_API_TOKEN',
    ],
    'json' => [
        'password' => 'test123'
    ]
]);

echo $response->getBody();
?>

Die Antwort enthält die neue Adresse:

{
  "status": 201,
  "ok": true,
  "message": "Address created",
  "data": [
    {
      "privateKey": "59f1c6200e01a2ca9471411f10198bfa63678d0e87cc2ca30f9c4a68dee78edc",
      "publicKey": "040fe6e677442c36f7fdd5535ba3ff1cef0110d78363420f7e24b65298990e3467aed68b9a67e1396d84753db25b32a2fa3e1fc0a673f01638e9bcfab2d8f4ceb5",
      "hexAddress": "41a56a6505ffbee78eb916dd44f4846874deddaebd",
      "address": "TR3qx91smURF3R455V1ubqtoUsZbgqikfg"
    }
  ]
}

Chaingateway speichert keine Passwörter. Ein verlorenes Passwort bedeutet eine verlorene Wallet.

Schritt 2: Den Token-Contract lesen

Bevor Sie einen Token bewegen, lesen Sie dessen Contract. Der Wert decimals ist der, den Sie am häufigsten brauchen, denn er sagt Ihnen, wie sich das rohe On-Chain-Guthaben auf den Betrag abbildet, den ein Nutzer sieht.

curl --request GET\
    --url https://api.chaingateway.io/v2/tron/trc20/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\
    --header 'Accept: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'

{
  "status": 200,
  "ok": true,
  "message": "TRC20 contract fetched",
  "data": {
    "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "symbol": "USDT",
    "name": "TetherUSD",
    "totalSupply": "61742996582033118",
    "decimals": "6"
  }
}

Eine unbekannte oder keine TRC20-Contract-Adresse antwortet mit Status 400 und der Meldung Error fetching TRC20 contract.

Schritt 3: Das Token-Guthaben prüfen

curl --request GET\
    --url https://api.chaingateway.io/v2/tron/balances/TVF2Mp9QY7FEGTnr3DBpFLobA6jguHyMvi/trc20/TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj\
    --header 'Accept: application/json'\
    --header 'Authorization: YOUR_API_TOKEN'

{
  "status": 200,
  "ok": true,
  "message": "TRC20 balance fetched",
  "data": {
    "tronaddress": "TVF2Mp9QY7FEGTnr3DBpFLobA6jguHyMvi",
    "decimals": 6,
    "balance": "1000000000000000000",
    "contractaddress": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj"
  }
}

Das Feld balance ist der rohe Ganzzahlwert. Teilen Sie ihn durch 10 hoch decimals, um den lesbaren Betrag zu erhalten.

Schritt 4: Den TRC20-Transfer senden

POST /v2/tron/transactions/trc20 benötigt from, to, contractaddress und amount. Zum Signieren geben Sie entweder password an, wenn die Adresse mit einem Passwort erstellt wurde, oder privatekey für eine ungesicherte oder importierte Adresse.

Parameter

from: Die TRON-Adresse des Absenders.
to: Die TRON-Adresse des Empfängers.
contractaddress: Die Contract-Adresse des Tokens.
amount: Der zu sendende Betrag.
password: Das Passwort einer passwortgeschützten Chaingateway-Adresse. Erforderlich, wenn privatekey nicht angegeben ist.
privatekey: Der Private Key des Absenders, für Adressen, die ohne Passwort erstellt oder importiert wurden.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/transactions/trc20\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1,
    "password": "test123"
}'

import requests

url = "https://api.chaingateway.io/v2/tron/transactions/trc20"
payload = {
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1,
    "password": "test123"
}
headers = {
    'Accept': 'application/json',
    'content-type': 'application/json',
    'Authorization': 'YOUR_API_TOKEN'
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const url = 'https://api.chaingateway.io/v2/tron/transactions/trc20';
const payload = {
  from: 'TLkkCeNdJKPNUwucdro84WjswkzM62LCTH',
  to: 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp',
  contractaddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
  amount: 1,
  password: 'test123'
};
const headers = {
  'Accept': 'application/json',
  'content-type': 'application/json',
  'Authorization': 'YOUR_API_TOKEN'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://api.chaingateway.io/v2/tron/transactions/trc20', [
    'headers' => [
        'Accept' => 'application/json',
        'content-type' => 'application/json',
        'Authorization' => 'YOUR_API_TOKEN',
    ],
    'json' => [
        'from' => 'TLkkCeNdJKPNUwucdro84WjswkzM62LCTH',
        'to' => 'TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp',
        'contractaddress' => 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
        'amount' => 1,
        'password' => 'test123'
    ]
]);

echo $response->getBody();
?>

Ein erfolgreicher Aufruf antwortet mit dem Transaktions-Hash:

{
  "status": 201,
  "ok": true,
  "message": "Succesfully created transaction",
  "data": {
    "txid": "0x73344d178812d4919e9002c560781f288030edf72ece88823ef1c377dfb71f27"
  }
}

Zwei Fehler kommen als Status 422 zurück und sind es wert, gesondert behandelt zu werden. balance is not sufficient bedeutet, dass die sendende Adresse die Transaktion nicht bezahlen kann. Die Meldung Validate signature error bedeutet, dass der Key oder das Passwort nicht zur from-Adresse passte.

Die sendende Wallet braucht TRX

Ein TRC20-Transfer ist ein Smart-Contract-Aufruf, und TRON berechnet dafür Energy und Bandwidth. Eine Adresse, die nur Token hält, kann sie nicht senden. Statten Sie die Adresse entweder mit TRX aus, staken Sie über POST /v2/tron/freeze und POST /v2/tron/delegate für Ressourcen, oder lassen Sie die Gebühr sponsern. Das Sponsern von Gebühren wird unter TRC20-Gebühren sponsern beschrieben.

Die Transaktion selbst signieren

Wenn Sie den Private Key lieber aus der Anfrage heraushalten möchten, teilen Sie den Transfer in zwei Aufrufe. POST /v2/tron/transactions/trc20/build liefert den rohen Transaktions-Hex, ohne ihn zu broadcasten. Diesen Hex signieren Sie in Ihrem eigenen Code und übergeben die signierte Transaktion an POST /v2/tron/transactions/broadcast.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/transactions/trc20/build\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": 1
}'

Die Antwort enthält raw_data und raw_data_hex. Zu diesem Zeitpunkt ist noch nichts beim Netzwerk angekommen.

Über eingehende Token benachrichtigt werden

Um von einer TRC20-Einzahlung zu erfahren, ohne zu pollen, abonnieren Sie einen Webhook mit type auf TRC20 und der contractaddress des Tokens. Die Filter from und to grenzen ihn auf eine einzelne Adresse ein.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/webhooks\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "url": "https://example.com/webhook-receiver",
    "type": "TRC20",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp"
}'

Wie Sie die empfangende Seite schreiben, steht unter Webhooks erstellen, und wie Sie prüfen, dass eine Benachrichtigung wirklich von Chaingateway stammt, unter Webhooks absichern.

Eine Benachrichtigung, die Ihr Server nicht angenommen hat, wird nicht von selbst erneut gesendet. Fehlgeschlagene Benachrichtigungen werden unter GET /v2/tron/webhooks/notifications/failed aufgelistet und können mit POST /v2/tron/webhooks/notifications/{id}/retry erneut ausgelöst werden.

Testen auf Nile

Jeder Aufruf oben funktioniert gegen das TRON-Testnet Nile. Fügen Sie den Header X-Network: testnet hinzu und verwenden Sie Test-Token statt Mainnet-Contracts. Die Netzwerkliste ist unter Unterstützte Netzwerke dokumentiert.