Was eine TRON-Energie-API tatsächlich tut
Eine TRON-Energie-API verkauft genau eine Sache, und ein Rabatt auf eine Gebühr ist es nicht. Ihr Konto braucht Energie, um den USDT-Vertrag auszuführen, und ohne sie nimmt sich das Netz stattdessen TRX, zu 100 sun für jede Einheit. Eine Energie-API sorgt dafür, dass ein anderes Konto — eines, das TRX gestakt hat — seine Energie für ein paar Minuten an die Adresse verleiht, die Ihren Transfer signieren wird. Alles Weitere hier ist die Form der Anfragen rund um diese eine Tatsache on-chain.
On-chain ist es eine Delegation, und Sie signieren nichts davon
Das verleihende Konto signiert eine Delegation, die Ihre Adresse nennt. Ihre Adresse signiert nichts, genehmigt nichts und gewährt im Gegenzug nichts: Das Netz hebt ihr Energielimit an, und das ist das ganze Ereignis (was Energie ist). Deshalb fragt eine Energie-API nach einer Adresse und nie nach einem Schlüssel — die einzige Signatur in der ganzen Sache gehört der Gegenseite.
Der kleinste Ablauf, der funktioniert
Die Basis-URL ist https://api.nrg.market/v1, und der Schlüssel reist in einem einzigen Header, Authorization: Bearer nrg_live_…. Er wird bei der Ausstellung einmal gezeigt und lässt sich an eine Liste von IPs binden. Rufen Sie ihn von Ihrem Server aus auf: Die authentifizierten Endpunkte lassen überhaupt keinen Browser-Origin zu, denn ein Schlüssel, der auf eine Seite gelangt, ist ein Schlüssel, den jeder hat. Es gibt eine zweite Basis-URL, auf einer sandbox-Subdomain von nrg.market — dieselbe /v1-Oberfläche über Testgeld und eine simulierte Kette, mit eigenen nrg_test_…-Schlüsseln und einem eigenen Kundenbereich, dokumentiert auf docs.nrg.market.
Fangen Sie mit POST /v1/estimate an. Der Aufruf reserviert nichts und belastet nichts, nimmt bis zu 500 Empfänger auf einmal und antwortet mit dem, was eine Bestellung errechnen würde.
curl -s https://api.nrg.market/v1/estimate \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"duration_s":300,
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
{"items":[{"to":"TN3W…","kind":"single","energy_units":65000,"warnings":[]}],
"zone":"day","duration_s":300}
# gekürzt — die Antwort trägt außerdem price_trx je Position, total_trx und burn_cost_trx
kind ist single für einen Empfänger, der bereits USDT hält, double für einen, der keine hält und dem erst ein Token-Konto angelegt werden muss, und custom für einen Vertrag, dessen Preis aus einem Dry-Run statt aus einer der beiden Standardzahlen kommt. from ist optional und bewegt keinen Preis; wer es angibt, kauft damit zwei Auskünfte über den Absender — inactive_sender und blacklisted_sender unter den warnings —, bevor eine Bestellung im genutzten Modus an einer davon scheitern kann.
Dann die Bestellung. Mode a ist der, in dem Sie den Transfer selbst senden.
curl -s https://api.nrg.market/v1/orders \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: 8f3c1e02-6b47-4a1d-9d5c-0b2e7c4a1f90" \
-d '{"mode":"a","client_ref":"invoice-1042",
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
Die Antwort ist ein 202 mit zwei Headern, die zu lesen besser ist als sie zusammenzubauen: Location, die eigene URL der Bestellung, und Retry-After, die Sekunden bis zur ersten Abfrage und zwischen den Abfragen. Der Body ist die Bestellung, normalerweise mit status auf funded und send_before noch auf null — das Geld ist reserviert und der Einkauf hat begonnen.
send_before erscheint, wenn die Energie on-chain bestätigt ist und die Bestellung ready erreicht. Es ist ein Fenster von etwa vier Minuten, gezählt ab der zuletzt bestätigten Delegation, sodass alle Positionen eines Stapels dieselbe Frist teilen; lesen Sie das Feld, statt die vier Minuten anzunehmen. Achten Sie auch auf das Feld und nicht auf das Wort ready: Eine Bestellung in mode A ist mit der Lieferung der Energie erfüllt und nicht mit Ihrem Transfer, also kann completed eintreffen, bevor Sie überhaupt etwas gesendet haben.
Zwei Abweisungen lohnen sich vor der ersten echten Bestellung: 402 insufficient_balance, entschieden bevor Geld bewegt wird und mit required_trx und available_trx im Gepäck, und 422 invalid_address mit details.reason auf inactive_wallet — die sendende Wallet wurde nie aktiviert, es gibt also kein Konto, an das delegiert werden könnte (die Fehlschläge dahinter).
Der Idempotenzschlüssel
POST /v1/orders verlangt einen Idempotency-Key, und der ist an die rohen Bytes des Body gebunden, nicht an das geparste JSON. Dieselben Bytes geben die ursprüngliche Bestellung zurück; ein anderer Body unter demselben Schlüssel ist ein 409 idempotency_conflict und keine zweite Bestellung; eine von der Prüfung abgewiesene Anfrage verbraucht den Schlüssel nicht. In Stapelgröße macht genau das aus einer Netzwerk-Zeitüberschreitung eine Frage, auf die es eine Antwort gibt.
Was die Rate-Limit-Header sagen
Drei Töpfe werden je API-Schlüssel gezählt: Bestellungen mit 120 pro Minute, Auskunftsanfragen mit 600 und GET /v1/address-check mit 60, weil jeder Fehlgriff seines Caches eine Frage an die Kette ist. Jede Antwort aus einem Schlüssel-Topf, die erfolgreichen eingeschlossen, trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset, damit ein Client vor der Abweisung langsamer werden kann statt danach; über dem Limit gibt es 429 rate_limited mit Retry-After. Ein anderes 429 meint fast das Gegenteil — too_many_auth_failures, wo Warten nicht hilft, weil die Zugangsdaten selbst abgelehnt werden. Verzweigen Sie über code, nie über message.
Webhooks, damit die Schleife keine Abfrage ist
Melden Sie einen Empfänger mit POST /v1/webhooks an: Die url muss https sein, auf einen öffentlichen Host auflösen und keine Zugangsdaten enthalten. Das Signaturgeheimnis kommt einmal zurück, bei der Anlage, und ein Konto hält höchstens fünf aktive Endpunkte. Abonnieren Sie, was der Ablauf braucht — order.ready, order.completed, order.partially_completed, order.failed, dazu die positionsbezogenen order.item.sent und order.item.expired. Jede Zustellung trägt X-NRG-Timestamp, X-NRG-Event-Id und X-NRG-Signature, ein HMAC-SHA256 über Zeitstempel, Punkt und rohen Body: Prüfen Sie gegen die empfangenen Bytes und nicht gegen neu kodiertes JSON, und entdoppeln Sie über event_id. POST /v1/webhooks/{webhook_id}/test schickt eine echte signierte Zustellung über den tatsächlichen Weg und berichtet, was Ihr Endpunkt geantwortet hat — kostenlos.
Mode B: Sie signieren, wir senden
Mode b ersetzt from und to durch signed_tx, die signierte Transaktion in Hex, und wir senden sie in dem Moment, in dem die Energie ankommt — niemand sitzt vor einem Fenster von vier Minuten. Was angenommen wird, ist absichtlich eng: ein transfer-Aufruf des USDT-Vertrags und sonst nichts, eine Signatur des Eigentümers, kein angehängtes TRX, und Multisig wird abgelehnt, weil der Schlüsselsatz einer Berechtigung im Netz lebt und sich ohne unser Wissen ändern kann. Die Transaktion braucht bei Anlage der Bestellung noch drei Minuten Restlaufzeit, und ihr eigener Ablauf verkürzt das Fenster — send_before läuft nie über diese Frist abzüglich einer Sendereserve hinaus. Gelingt die Weiterleitung nicht rechtzeitig, schließt die Position als failed mit broadcast_window_missed, und die Reservierung kommt vollständig zurück.
Mode C: Energie ohne genannten Empfänger
Mode c nimmt from und kind und überhaupt keinen Empfänger — für eine Wallet, die bereit sein soll, bevor es den Stapel gibt. kind ist single oder double, und es richtig zu wählen ist Ihre Sache: Ohne Empfänger gibt es nichts, woraus sich die Menge lesen ließe, also lässt single dort, wo double nötig war, den Transfer zu kurz kommen, und die Differenz verbrennt TRX. custom gibt es hier bewusst nicht, denn es ist das Ergebnis eines Dry-Runs gegen einen bestimmten Vertragsempfänger. Positionen tragen to: null, erreichen nie sent und werden expired, wenn das Fenster schließt: Die Miete lief ab, was das normale Ende ist und kein Fehlschlag — und belastet wird es, weil die Energie geliefert wurde.
Was nie in der Anfrage steht
Es gibt im ganzen Vertrag kein Feld für einen privaten Schlüssel, in keinem Modus. Mode A sieht Ihre Transaktion nie. Mode B sieht eine, die Sie bereits signiert haben und die wir nicht um ein Byte ändern können, ohne diese Signatur zu zerstören; sie wird verschlüsselt gehalten und sieben Tage nach dem Endstatus der Bestellung gelöscht. Mode C hat gar keine Transaktion zu sehen. Was die API bekommt, sind Adressen (der Rest dessen, was wir halten und nicht halten).
Die Teile, die keinen Schlüssel brauchen
Die Auskunfts-Endpunkte und der Vertrag brauchen überhaupt keinen Schlüssel und werden nach IP statt nach Schlüssel begrenzt. GET /v1/tariff nennt den Preis einer Einheit Energie in sun im Moment, die laufende Zone, next_change_at und einen Referenzplan — das ist es, was die Preisseite bei jedem Laden liest. GET /v1/market nennt, was die von uns beobachteten Anbieter über sich selbst veröffentlichen, jede Zahl mit dem Zeitpunkt ihrer Ablesung gestempelt und unser eigener Preis dazwischen eingeordnet, also die Marktseite. Zitieren Sie den Endpunkt und nicht eine Zahl: Unser Preis wird alle paar Minuten neu berechnet.
Der Vertrag selbst liegt unter https://docs.nrg.market/openapi.yaml und Byte für Byte dasselbe Dokument unter https://api.nrg.market/v1/contract.yaml — gut zu wissen, denn der Doku-Host sitzt hinter einem Edge, der manche programmatischen Clients abweist, bevor die Anfrage bei uns ankommt. ETag ist dort der SHA-256 des Body, also liefert If-None-Match ein 304, wenn sich nichts geändert hat. Erzeugen Sie Ihren Client aus dieser Datei: Diese Seite ist eine Zusammenfassung, und die Datei ist das, woran wir gebunden sind.