API MarketPlace — энергия и Bandwidth TRON

От ключа до TXID

1. 1

   Запросите отдельный ключ Marketplace у поддержки. Проверьте GET /account и GET /capabilities.

2. 2

   Выберите режим покупки, получите POST /quotes и создайте POST /orders. Для оплаты из общего баланса достаточно payment_mode: balance.

3. 3

   Читайте GET /orders/{id} или события webhook. Успех делегации: delivery_complete=true; хеши находятся в txids_delegate. Создание заказа само по себе не подтверждает получение ресурса.

const base = "https://tronbid.com/api/v2/marketplace";
const headers = { Authorization: "Bearer " + process.env.TRONBID_MARKETPLACE_KEY };
async function write(path, body, key = crypto.randomUUID()) {
  const response = await fetch(base + path, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": key },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) throw new Error(JSON.stringify(result.error));
  return result.data;
}
const quote = await write("/quotes", {
  mode: "best", resource_type: "energy", resource_amount: 131000,
  duration: { type: "minutes", value: 15 },
  recipient_address: "YOUR_TRON_RECEIVER_ADDRESS",
  max_price_sun: 50, max_total_trx: "6.550000",
  allow_partial: true, wait_seconds: 900
});
const order = await write("/orders", {
  quote_id: quote.quote_id, payment_mode: "balance",
  external_id: "invoice-2026-0001"
});
const response = await fetch(base + "/orders/" + order.id, { headers });
const { data: state } = await response.json();
console.log(state.status, state.delivery_complete, state.txids_delegate);

Доступ и отдельные ключи

Получите ключ у @tronbid в Telegram или support@tronbid.com. Сначала войдите на сайт с кошельком аккаунта. Администратор выдаёт отдельный ключ tbm_ и права read, buy, sell, offers, wallets, webhooks. Ключи Quick Rent и Seller Delegate API не подходят.

Базовый адрес: https://tronbid.com/api/v2/marketplace. Передавайте Authorization: Bearer tbm_… по HTTPS. Баланс аккаунта общий с сайтом и Quick Rent, история операций API Marketplace отдельная. Лимитов расходов нет. Ограничение запросов и список разрешённых IP задаёт администратор.

Ответы и безопасные повторы

Успех: {data: …, request_id: UUID}. Ошибка: {error: {code, details?}, request_id: UUID}. Суммы TRX в котировках, заказах и статистике возвращаются строками; поля ручных сделок сохраняют числовой формат. Точный тип каждого поля указан в OpenAPI. Расчёты ведутся в SUN, 1 TRX = 1 000 000 SUN.

Каждый POST, PATCH, PUT и DELETE требует Idempotency-Key длиной 8–128 символов: буквы, цифры, . _ : -. При повторе того же запроса с тем же ключом сохраняется первоначальный результат. Для другой операции используйте новый ключ. ID ключа API определяет область идемпотентности.

После таймаута повторяйте исходный запрос с тем же Idempotency-Key. 409 REQUEST_IN_PROGRESS — запрос ещё выполняется; 409 IDEMPOTENCY_CONFLICT — изменилось тело или адрес. При 429 RATE_LIMITED соблюдайте Retry-After. Ответы нельзя трактовать как подтверждение делегации до delivery_complete=true.

Рынок, объёмы и цена

GET /capabilities возвращает действующие минимумы и сроки. Доступны energy и bandwidth, 15 минут, 1 час и 1–30 дней. GET /market?side=offers показывает предложения продавцов; side=bids — заявки покупателей. resource_type, limit (1–100) и offset управляют выборкой.

price_sun — цена за единицу ресурса: за весь период для minutes/hours, за один день для days. Полная цена: объём × price_sun × число дней (для 15 минут и часа множитель равен 1). Комиссия удерживается из дохода продавца по правилам Marketplace; отдельной комиссии покупателя нет.

Доступность берётся из последних проверенных снимков ресурсов продавцов. resources_checked_at показывает их возраст. Котировка не резервирует ресурс. API не вызывает опрос блокчейна при каждом чтении рынка. Заказы исполняют только участники Marketplace, без подмены собственными пулами или китайским поставщиком.

Доступность, цена и расчёт перевода

GET /resources суммирует свободные ресурсы продавцов, не считая один кошелёк несколько раз. Фильтруйте ресурс, срок и цену. Это снимок доступности, а не резервирование.

GET /price показывает цену и доступный объём без создания котировки. Для покупки используйте POST /quotes или POST /orders/instant с ограничением бюджета. Каждый платёж части округляется по правилам Marketplace; окончательная сумма указана в котировке.

GET /estimate-energy симулирует transfer(address,uint256) указанного токена для конкретных from_address и to_address. amount передаётся в минимальных единицах токена. fee_trx — стоимость сжигания TRX по сети, а не цена аренды. Результат кешируется 15 секунд отдельно для каждой комбинации параметров. При неудачной симуляции возвращается 422, а не выдуманная оценка.

Три способа покупки

Сначала POST /quotes: mode, resource_type, resource_amount, duration:{type,value}, recipient_address. bid создаёт заявку с вашей price_sun; offer покупает конкретный offer_id; best выбирает самые дешёвые подходящие предложения в пределах max_price_sun и/или max_total_trx. Для offer можно ограничить максимальную цену.

Котировка действует 60 секунд. POST /orders принимает quote_id, payment_mode (balance или onchain), необязательный external_id. Котировку можно использовать для одного заказа; external_id уникален в аккаунте. Максимальный бюджет фиксируется в заказе и не увеличивается автоматически.

allow_partial=true разрешает частичное исполнение несколькими продавцами. При false покупка offer/best начинается только после резервирования всего объёма в одной операции; заявка bid принимается одним продавцом целиком. wait_seconds задаёт ожидание от 30 секунд до 30 дней, по умолчанию 900 секунд. Уже принятые части исполняются на прежних условиях.

Оплата, отмена и пакетные заявки

balance резервирует бюджет из общего баланса атомарно с созданием заказа. Дополнительного списания при распределении по продавцам нет. onchain создаёт ожидающий оплаты заказ: запросите POST /orders/{id}/payment и отправьте указанное количество TRX с указанного payer_address. Счёт действует 15 минут. Излишек платежа зачисляется на баланс.

POST /orders/{id}/cancel прекращает поиск исполнителей и возвращает нераспределённый остаток на общий баланс. Уже принятые или подписанные делегации сначала проходят проверку результата. Истечение срока ожидания действует так же. Возвраты за неисполненные оплаченные части идут по правилам Marketplace.

POST /orders/batch принимает {orders:[{quote_id,payment_mode,external_id},…]} — до 20 заказов. Создание атомарно: ошибка любого элемента отменяет создание всей партии. У партии один Idempotency-Key.

Кошельки и автоматические предложения

Добавляйте несколько кошельков. POST /wallet-challenges с address возвращает message и challenge_id. Подпишите message методом TronWeb.trx.signMessageV2 и отправьте POST /wallets с challenge_id, signatures и automatic. Подтверждение действует 5 минут; для multisig нужен порог подписей владельцев. Приватные ключи на сервер не отправляются.

Для автоматической продажи сначала зарегистрируйте кошелёк с automatic=false, затем вызовите POST /wallets/{id}/prepare-permission. Подпишите и отправьте полученную транзакцию из своего кошелька. После подтверждения получите новое сообщение для подписи и повторите POST /wallets с automatic=true: API проверит разрешение в блокчейне. Подготовка не отправляет транзакцию; сетевую комиссию оплачивает владелец кошелька. GET /wallets возвращает permission_id, статус и снимки ресурсов. PATCH /wallets/{id} с enabled:false отключает новые операции с кошелька.

POST /offers: wallet_id, resource_type, resource_amount, duration, price_sun, auto_repeat, paused. Цена всегда задаётся продавцом. PATCH /offers/{id} изменяет price_sun, free_amount, duration, paused, auto_repeat или принимает cancel:true. Если условия уже использовались, создаётся замена с новым ID; ответ содержит replaces_offer_id, прежнее предложение — replaced_by. Существующие резервирования сохраняют условия. Для автоповтора отслеживайте repeat_source_offer_id.

// write() uses the same authenticated POST helper as the buyer example.
// tronWeb is connected to the seller's wallet; keys stay on the client.
async function register(automatic) {
  const challenge = await write("/wallet-challenges", {
    address: tronWeb.defaultAddress.base58
  });
  const signature = await tronWeb.trx.signMessageV2(challenge.message);
  return write("/wallets", {
    challenge_id: challenge.challenge_id,
    signatures: [signature], automatic
  });
}
const wallet = await register(false);
const permission = await write(
  "/wallets/" + wallet.id + "/prepare-permission", {}
);
const signed = await tronWeb.trx.sign(permission.transaction);
const sent = await tronWeb.trx.sendRawTransaction(signed);
if (!sent.result) throw new Error("Permission transaction rejected");
// Wait for a confirmed successful transaction before enabling automatic mode.
let confirmed = false;
for (let attempt = 0; attempt < 40; attempt++) {
  await new Promise(resolve => setTimeout(resolve, 3000));
  const receipt = await tronWeb.trx.getTransactionInfo(sent.txid);
  const confirmedTransaction = await tronWeb.trx.getTransaction(sent.txid);
  if (receipt.id && confirmedTransaction.ret?.[0]?.contractRet === "SUCCESS") {
    confirmed = true;
    break;
  }
}
if (!confirmed) throw new Error("Check permission transaction before proceeding");
const ready = await register(true);
const offer = await write("/offers", {
  wallet_id: ready.id, resource_type: "energy", resource_amount: 1000000,
  duration: { type: "minutes", value: 15 },
  price_sun: 20, auto_repeat: true, paused: false
});
console.log(offer.id, offer.wallet_id, offer.status);

Исполнение заявок с собственной подписью

Найдите заявку через GET /market?side=bids. POST /trades принимает order_id, wallet_id, resource_amount и резервирует её на 3 минуты. Ответ содержит источник, получателя, delegate_balance_sun и lock_period_blocks.

Сформируйте DelegateResourceContract с этими параметрами, подпишите на своей стороне и отправьте POST /trades/{id}/delegate: {signed_transaction:{…}}. Подписанная транзакция сохраняется до отправки и восстанавливается после сбоев. POST /trades/{id}/cancel отменяет только ещё не отправленную заявку. Истечение срока неподписанной заявки освобождает её.

GET /trades/{id} показывает статус, комиссию, ожидаемую выплату, delegate_txid и payout_txid. Выплаты используют настройки аккаунта TRX/USDT и правила сайта. Автоматическое исполнение Seller Offers выполняется по выданному разрешению; ручная подпись нужна только для этого отдельного сценария.

// Claim an eligible buyer bid, then use the exact returned amounts.
const claim = await write("/trades", {
  order_id: "BUYER_ORDER_UUID", wallet_id: "YOUR_REGISTERED_WALLET_UUID",
  resource_amount: 131000
});
const transaction = await tronWeb.transactionBuilder.delegateResource(
  Number(claim.delegate_balance_sun), claim.recipient_address,
  claim.resource_type.toUpperCase(), claim.source_address,
  true, Number(claim.lock_period_blocks)
);
const signed = await tronWeb.trx.sign(transaction);
// Persist signed and the Idempotency-Key before this call.
// On timeout, resend the SAME signed transaction and key, not a new delegation.
const result = await write("/trades/" + claim.trade_id + "/delegate", {
  signed_transaction: signed
}, "UNIQUE_PERSISTED_DELEGATION_KEY");
console.log(result.status, result.delegate_txid, result.payout_txid);

Баланс, пополнение и статистика

GET /account возвращает общий баланс, права ключа и использование за сегодня, вчера и всё время. GET /statistics даёт отдельные объёмы Energy/Bandwidth, покупки, валовую выручку продавца, комиссию и доход.

Сегодня и вчера — календарные дни Europe/Moscow по умолчанию; можно выбрать UTC. week — последние 7 суток, month — 30, rolling — days суток. Учитываются подтверждённые исполнения API Marketplace, не чужие Quick Rent операции.

GET /account/recharge показывает адрес и can_recharge. Переводите TRX только с указанного payer_address, без параллельной оплаты других заказов с этого кошелька. Это проверка состояния, а не блокировка кошелька. Подтверждённые зачисления: GET /account/deposits.

Статусы, TXID и история

Проверяйте GET /orders/{id}: awaiting_payment → waiting → partially_delegated → delegated. Возможны cancelling, cancelled, expired; после частичного исполнения смотрите delivered_amount и remaining_amount. delivery_complete=true означает доставку всего заказанного ресурса.

txid_delegate — первый подтверждённый хеш; txids_delegate — все хеши. Детали частей, возвратов и выплат находятся в fulfillments и trades. Ссылка: https://tronscan.org/#/transaction/{txid}. Получение ID заказа само по себе не означает успешную доставку.

GET /orders?external_id=… ищет заказ по вашему идентификатору. GET /events?after=0 возвращает события по возрастанию и next_cursor. GET /statistics?days=30 разделяет покупки и продажи. Комиссия и доход продавца учитываются по подтверждённым операциям.

Подписанные уведомления

PUT /webhook с {url:"https://…"} включает уведомления для текущего ключа; url:null отключает их. Секрет подписи выдаётся администратором вместе с ключом. Только публичный HTTPS-адрес, без перенаправлений.

Проверяйте X-TronBid-Signature: v1=HMAC_SHA256(secret, timestamp + "." + rawBody); timestamp берётся из X-TronBid-Timestamp. Сравнивайте подпись за постоянное время, отклоняйте старые timestamps и дедуплицируйте по X-TronBid-Event-Id. Сначала проверьте подпись, затем разбирайте JSON.

Ответьте HTTP 2xx после надёжного сохранения события. Доставка как минимум один раз; возможны повторы и изменение порядка. При ошибке до 12 попыток с задержкой от 30 секунд до часа. Уведомления отражают состояние на момент события; актуальное состояние запрашивайте по ID. Пропущенные события доступны через GET /events.

import { createHmac, timingSafeEqual } from "node:crypto";
function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  const expected = createHmac("sha256", secret).update(timestamp + "." + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"));
}