Эндпоинты и ключи

Эндпоинты

Эндпоинт — это ключ Node API. Эндпоинты создаются в разделе Личный кабинет → Node API, когда у вас есть тариф или триал. У каждого эндпоинта есть:

свой ключ;
свой белый список IP;
свой счётчик — WU и вызовы за текущий период, которые видны в кабинете.

Квота и лимиты в секунду принадлежат тарифу и общие для всех его эндпоинтов: второй эндпоинт даёт отдельный ключ и счётчик, а не дополнительную пропускную способность. Сколько эндпоинтов можно иметь, зависит от тарифа — см. Тарифы и оплата. Ключ показывается только один раз — при создании эндпоинта. Если вы его потеряли, удалите эндпоинт и создайте новый. В кабинете эндпоинту также можно изменить белый список IP, его можно выключить и снова включить, а также удалить:

Состояние эндпоинта	Запросы с его ключом
Выключен	`403 key_disabled`, пока вы снова его не включите
Удалён	`401 unknown_key`; восстановить ключ нельзя

Изменения в кабинете — новый эндпоинт, новый белый список IP, выключенный или удалённый эндпоинт, оплаченное продление — доходят до шлюза нод примерно за 30 секунд. Только что созданный ключ в это время может получать 401 unknown_key.

Ключи Node API и ключи REST API

Ключи Node API — отдельный вид ключей. Ключ эндпоинта работает только на node.tronrental.com; REST API TronRental (api.tronrental.com) отклоняет его с 403 NODE_API_KEY_ONLY. Ваши ключи REST API, в свою очередь, не работают на ноде и получают там 401 unknown_key.

Передача ключа по HTTP

Передайте ключ в одном из этих мест:

Где	Пример
Заголовок `TRON-PRO-API-KEY`	`TRON-PRO-API-KEY: <YOUR_KEY>`
Заголовок `X-API-Key`	`X-API-Key: <YOUR_KEY>`
Заголовок `Authorization`	`Authorization: Bearer <YOUR_KEY>`
Первый сегмент пути	`https://node.tronrental.com/<YOUR_KEY>/wallet/getaccount`

Имена заголовков не чувствительны к регистру. Ключ в пути удаляется до того, как запрос передаётся ноде, поэтому нода его никогда не видит.

curl -X POST https://node.tronrental.com/wallet/getaccount \
  -H 'TRON-PRO-API-KEY: <YOUR_KEY>' \
  -d '{"address": "TXYZ…", "visible": true}'

curl -X POST https://node.tronrental.com/<YOUR_KEY>/wallet/getaccount \
  -d '{"address": "TXYZ…", "visible": true}'

Один запрос — один ключ. Один и тот же ключ, переданный дважды (например, в пути и в заголовке), — это нормально; два разных ключа отклоняются с 400 key_conflict, потому что мы не можем понять, какой из них должен платить.

Ключ в пути — часть URL, поэтому он оказывается везде, где записываются URL: в логах прокси и приложений, в мониторинге, в истории браузера. Если клиент позволяет задать заголовок, используйте заголовок.

Библиотеки

TronWeb отправляет заголовки, которые вы ему передали:

import { TronWeb } from 'tronweb';

const tronWeb = new TronWeb({
  fullHost: 'https://node.tronrental.com',
  headers: { 'TRON-PRO-API-KEY': '<YOUR_KEY>' },
});

tronpy отправляет api_key= только своему адресу по умолчанию, поэтому с нашим адресом он не отправит ключ вовсе. Задайте заголовок в сессии провайдера сами — или передайте ключ в пути, со слешем в конце: без него tronpy отбрасывает последний сегмент адреса, а вместе с ним и ключ.

from tronpy import Tron
from tronpy.providers import HTTPProvider

provider = HTTPProvider('https://node.tronrental.com')
provider.sess.headers['TRON-PRO-API-KEY'] = '<YOUR_KEY>'
client = Tron(provider)

# или ключ в пути — сохраните слеш в конце
# client = Tron(HTTPProvider('https://node.tronrental.com/<YOUR_KEY>/'))

Передача ключа по gRPC

Передавайте ключ в метаданных tron-pro-api-key каждого вызова (x-api-key и authorization: Bearer <YOUR_KEY> тоже работают). В gRPC нет пути, в котором можно передать ключ. См. gRPC.

Белый список IP

Каждый эндпоинт можно ограничить списком IP-адресов — IPv4 или IPv6, точные адреса, не диапазоны. С пустым списком ключ работает с любого адреса. Если список задан, запросы с любого другого адреса получают 403 ip_not_allowed. Адрес IPv4, записанный в форме IPv6 (::ffff:203.0.113.7), считается самим адресом IPv4.

Браузерные приложения (CORS)

Node API отвечает на браузерные запросы с любого origin, поэтому dApp может обращаться к нему напрямую:

Заголовок	Значение
`Access-Control-Allow-Origin`	`*`
`Access-Control-Allow-Methods`	`GET, POST, OPTIONS`
`Access-Control-Allow-Headers`	`Content-Type, TRON-PRO-API-KEY, X-API-Key, Authorization`
`Access-Control-Expose-Headers`	`X-Node-API-WU, X-Node-API-Mode, Retry-After`
`Access-Control-Max-Age`	`86400`

Ключ в браузерном коде виден всем, кто открывает ваше приложение, и любой, кто его скопирует, тратит вашу квоту. Белый список IP здесь не поможет — адреса ваших пользователей заранее неизвестны. Выделите браузеру отдельный эндпоинт, следите за его счётчиком и удалите его при злоупотреблениях: серверные ключи продолжат работать.