TronSave MCP Server

Buy the SAME amount of ENERGY or BANDWIDTH for several receiver addresses in one call, paid from the TronSave internal balance; returns one order id per receiver. Side effect: SPENDS `paymentAmount` SUN of the internal balance; not idempotent (a repeat buys again). Estimate one receiver with `tronsave_estimate_buy_resource` first and show the user receivers, amount and total cost before calling. Requires a wallet signature identity.

Cancel an open order by `orderId`. Returns `{ success, message, code }`. Side effect: marks the order non-matchable and refunds locked balance per backend rules; effectively destructive on the live order. Idempotent — cancelling an already-cancelled order is a no-op success. Fails for fulfilled orders or unauthorized callers. Requires a wallet signature identity (the order's owner). Verify state with `tronsave_get_order` first; prefer `tronsave_update_order` when only price/receiver should change.

Create a rule that automatically buys `resourceAmount` for `receiver` whenever its remaining resource falls below `thresholdResourceAmount`, paying up to `unitPrice` SUN per unit from the TronSave internal balance. Side effect: SPENDS internal TRX every time the rule fires until a budget/order limit or `endActiveAt` stops it; not idempotent (each call adds a rule). Confirm receiver, amounts, price cap and limits with the user first; prefer setting `limitBudgetInSun`. Requires a wallet signature identity.

Create a buy order for ENERGY/BANDWIDTH delegated to `orderReceiver`. SPENDS FUNDS — confirm the plan with the user first. API-key integrations paying from the internal balance can instead use `tronsave_internal_order_create` (FAST/MEDIUM/SLOW pricing, fill guards). Inputs: `orderResourceType`, `orderReceiver`, `orderUnitPrice` (SUN, not TRX), `orderDurationSec`, `orderResourceAmount`, `paymentPaymentAmount` (SUN), and `paymentMethod`: `internal` — debits the TronSave internal balance (needs an api-key login/header or a signature login whose wallet has an internal account); `onchain` — no login needed, but `paymentSignedTx` must be the user's wallet-signed TRX transfer to `systemDepositAddress`. Take price/amount/duration values from the latest `tronsave_estimate_buy_resource`. Returns `{ success, message, code, data.orderId }` — check `success`; verify with `tronsave_get_order` or `tronsave_list_orders`. Not idempotent: on a timeout, verify before retrying to avoid duplicate orders.

Permanently delete one auto-buy rule by `id` (`MObjectId`). Side effect: stops all future executions matching that rule; the rule cannot be restored. Idempotent — deleting a non-existent or already-removed id returns success. Requires a wallet signature identity. Use `tronsave_get_user_auto_setting` to list current rules first; prefer disabling/updating instead when reversibility is desired.

Quote price and availability for buying ENERGY or BANDWIDTH for a receiver address before placing an order. This quote feeds `tronsave_create_order`; for `tronsave_internal_order_create` (API key) quote with `tronsave_internal_order_estimate`. Returns `{ unitPrice (SUN/unit), durationSec, estimateTrx (total cost in SUN), availableResource, systemDepositAddress }` — map them to `tronsave_create_order` as `orderUnitPrice`, `orderDurationSec`, `paymentPaymentAmount`. Defaults: ENERGY, 100000 units (1000 for BANDWIDTH), 900 s. Read-only and safe to call repeatedly; no session is required, but backend rate limits apply. For order-book depth use `tronsave_list_order_books`; for the minimum unit price only use `tronsave_get_min_price`.

Estimate what an address would receive by flash-unstaking all its staked TRX now: total staked, fee percentage, payout, delegations to reclaim and the minimum unstake amount. Nothing is submitted. Use before requesting a flash unstake; check an existing request with `tronsave_get_flash_unstake_request`. Public (any address), read-only. Fails with 404 when the address has nothing staked.

Generate a new internal API key credential for the current user. Returns `data` containing the issued key — show it to the user once and tell them to store it securely; do not repeat it in later messages. Side effect: issues secret material; not idempotent — each call mints a fresh key and may invalidate the previous one per backend policy. Requires a wallet signature identity. Sensitive output — never log raw keys; unauthorized sessions or policy checks may reject issuance.

Read the on-chain staked and delegatable ENERGY/BANDWIDTH of a TRON address, plus its TRX balance (SUN string). Use to check whether a wallet can sell, or how much resource it holds. Public (any address), read-only; does not need a login.

Read the logged-in user's Telegram agency bot (resale bot): name, username, status (PENDING, ACTIVE, INACTIVE, BLOCKED, REJECTED), rewards (total and unpaid) and order / resource statistics. `bot` is null when none is registered. The bot token is never returned. Requires a wallet signature identity. Read-only.

Fetches the specific deposit address for the TronSave internal account. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Trigger this tool if the user asks for a deposit address or needs to top up their TronSave TRX balance. Constraints: 1) TRX only; 2) Minimum deposit amount is 10 TRX; 3) Read-only operation.

Read the logged-in user's flash-unstake request (selling staked TRX early for an immediate payout): state, payout state, amounts and release progress. `request` is null when there is none. Use for the user's own request; to preview a payout before requesting use `tronsave_estimate_flash_unstake`, to browse everyone's orders use `tronsave_list_flash_unstake_orders`. Requires a wallet signature identity. Read-only.

Retrieve the Tronsave internal account profile for the current logged-in session (wallet/represent address, balances, deposit address). Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use when the user needs their linked address or balance; for the full wallet profile use `tronsave_get_user_info`, for the ledger of deposits and payments `tronsave_list_internal_transactions`. Returns `{ id, balance (SUN string), representAddress, depositAddress }`; any API key in the payload is masked. Read-only.

Read the TronSave market summary: resource currently available and total listed for ENERGY and BANDWIDTH, number of pooled sellers, and seller APY (percent). Use for a quick 'how is the market' answer before pricing; for prices use `tronsave_get_price_table` (grid) or `tronsave_estimate_buy_resource` (one quote), for depth by price use `tronsave_list_order_books`. Public, read-only. Data refreshes about every TRON block (3 s).

Quote the minimum unit price for a buy. Use when only the floor price matters; for a full purchase quote use `tronsave_estimate_buy_resource`, for a grid across amounts and durations `tronsave_get_price_table`. Returns `{ minPrice }` (SUN per resource unit; per day when `durationSec` >= 86400) from GraphQL `market.estimateMinPrice` for the given `resourceType`, `buyAmount`, and `durationSec`. Optional `address` scopes context when the API supports it. No login required. Read-only and idempotent. Pair with `tronsave_estimate_buy_resource` for full buy quotes and `tronsave_list_order_books` for depth buckets.

Read one order by `id` and return its full snapshot for NORMAL, FAST, or EXTEND order types. With only an API key, use `tronsave_internal_order_details` instead. Use this as the source of truth before `tronsave_update_order`, `tronsave_sell_order_manual`, or `tronsave_cancel_order` to avoid acting on stale state. Requires a wallet signature identity. Read-only and idempotent.

Read the price grid for ENERGY or BANDWIDTH: `prices[i][j]` is the unit price in SUN for `amounts[i]` resource units rented for `durations[j]` (e.g. '15m', '1h', '1d'). Durations of 1 day or longer are priced per day: '30d' at 40 SUN costs 40 x 30 SUN per unit in total. Use to compare cost across amounts and durations in one call. For an exact quote on one purchase use `tronsave_estimate_buy_resource`; for only the floor price use `tronsave_get_min_price`. Public, read-only.

Read the logged-in user's referral status: own referral code, sponsor, referral counts, bonus earned and remaining (SUN strings), rank, the referral list (PENDING/ACTIVE) and recent commission payouts. Use for referral questions only; account profile is `tronsave_get_user_info`. `offset`/`limit` page the referral list and the payout list together. Requires a wallet signature identity. Read-only.

Read the logged-in seller's lifetime totals (delegations, resource delegated, TRX earned, average price per resource) and a daily earnings chart split into auto, manual, exclusive and extend delegations. Use for 'how much did I earn' totals; for the individual delegations behind them use `tronsave_list_delegations`. Requires a wallet signature identity. Read-only.

Report the current authentication state without calling TronSave: `authMode` (none | api-key | signature), `source` (login | header), `walletAddress`, `hasInternalApiKey`, `expiresAt`, network, and which tool groups are available now. Call this first when unsure whether to log in, and after `SESSION_REQUIRED` / `INVALID_SESSION_TYPE` errors.

Step 1 of wallet login. Returns `{ message, timestamp }`: ask the user to sign `message` with their TRON wallet (TronWeb `signMessageV2`, TronLink, etc.), then call `tronsave_login` with `signature: "<signature>_<timestamp>"`. Signing the plain decimal `timestamp` text is also accepted. No auth needed; no side effects on the account.

Read TronSave and TRON protocol parameters: latest block, minimum buy amounts, TRX burn rates per unit, dynamic buy/lowest prices, the system deposit address, max lock period and the energy cost of a USDT transfer. Use to size purchases (minimums) and to compare renting with burning TRX. For market prices use `tronsave_get_price_table` or `tronsave_estimate_buy_resource`; for supply and APY use `tronsave_get_market_overview`. Public, read-only.

Read the Telegram alert filters of the logged-in user: seller alerts (remaining amount, duration, price and APY ranges, unlocked-only) and buyer alerts (reclaim warning time, low energy / bandwidth thresholds). `setting` is null when Telegram is not linked. Read these before changing them with `tronsave_update_telegram_notify_setting` (which replaces whole filter objects). For in-app alerts use `tronsave_list_notifications`. Requires a wallet signature identity. Read-only.

Read the current user's auto-sell configuration (`autoSettings`). Returns the full `autoSettings` object — call this before `tronsave_register_auto_sell` or `tronsave_update_auto_sell_setting` to avoid overwriting fields you do not intend to change. Requires a wallet signature identity. Read-only and idempotent.

Read the current authenticated user's profile and linked TronSave internal account. For the internal balance alone use `tronsave_get_internal_account`; for referral data `tronsave_get_referral`. Returns `{ caller, address, balance (SUN string), info, internalAccount }` — `info` carries referral/contact metadata and may be null; `internalAccount` is null when the wallet has not provisioned a TronSave internal balance yet. `internalAccount.apiKey` is masked. Requires a wallet signature identity. Read-only and idempotent. Use `tronsave_get_user_auto_setting` for the auto-sell config or `tronsave_get_user_permissions` for permission flags when the full profile is unnecessary.

Read the enabled permission operations (`autoSettings.permitOperations`) for the authenticated user. Returns `{ permitOperations: string[] }` — use it before mutating auto-sell or auto-buy rules to confirm the action is allowed for the wallet. Requires a wallet signature identity. Read-only and idempotent.

Submit an extension request for existing delegated resources on TronSave via authenticated REST `POST /v2/extend-request`. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Side effect: creates an extension order and may commit TRX from the internal account. `extendData` must follow the REST contract (see schema on each row). Get `extendData` from `tronsave_internal_extend_delegates` (STEP 1) and pass the rows unchanged. Do not copy rows from `tronsave_list_extendable_delegates` (GraphQL); that payload shape differs and is for market discovery only.

Return extendable delegations for a receiver plus an `extendData` payload for the extension flow. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use as STEP 1 before `tronsave_internal_create_extend_request` when the user wants to extend existing delegation time. This is the only source of submittable `extendData`; `tronsave_list_extendable_delegates` is a public market view, and `tronsave_list_extendable_receivers` finds which receiver to extend. Read-only; does not submit anything. FRESHNESS: pricing/availability change within seconds — run immediately before extending and pass the returned `extendData` unchanged.

Return the current TronSave market depth/price tiers for ENERGY or BANDWIDTH via the api-key REST endpoint. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use before `tronsave_internal_order_create` or `tronsave_internal_order_estimate` when the user needs live prices or liquidity. Same depth as the public `tronsave_list_order_books`, plus SLOW/MEDIUM/FAST price tiers; use the public tool when there is no API key. Read-only. FRESHNESS: live market depth can change roughly every 3 seconds (one TRON block) — re-read immediately before placing an order.

Place a new buy order for ENERGY or BANDWIDTH on TronSave, paid from the internal account balance. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Side effect: SPENDS internal TRX balance and creates a live order; not idempotent — each call places a new order. This is the api-key/internal path; for the signature-session market path use `tronsave_create_order`. Always derive `unitPrice` from the latest `tronsave_internal_order_estimate` (re-estimate immediately before submitting — quotes older than a few seconds may be stale and revert). Returns `{ orderId }`.

Fetch full details for one internal-account order by order ID. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use when monitoring fulfillment after `tronsave_internal_order_create`, or when the user asks for status on a specific order id. API-key path; with a wallet signature `tronsave_get_order` returns the same order. Read-only. FRESHNESS: order state changes within seconds as the market matches — re-read immediately before acting.

Estimate the TRX cost and availability for a buy order before submitting it (api-key internal account). Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use when the user wants a quote or price check; feed the result into `tronsave_internal_order_create`. Quotes for `tronsave_create_order` come from `tronsave_estimate_buy_resource` instead. Read-only. FRESHNESS: `unitPrice`/`estimateTrx` are live and can change roughly every 3 seconds — re-estimate immediately before creating the order.

List paginated order history for the internal account linked to the API key, newest first. Requires an internal API key: `tronsave_login` (api-key mode, or signature mode for a wallet with an internal account) or an `Authorization: ApiKey <key>` client header. Never pass API keys as tool arguments; the server forwards the key from the session/header to TronSave. Use when the user asks about past purchases, fulfillment, payouts, or delegates on their internal account. This is the API-key path; wallet-signature sessions can also use `tronsave_list_orders` with `isOnlyMyOrder`. Read-only. Pair with `tronsave_internal_order_details` for a single order's full snapshot.

List the logged-in user's auto-buy rules: receiver, resource, unit price cap, threshold, budget/order limits, totals bought and active state. Use before `tronsave_update_auto_buy_setting` or `tronsave_delete_auto_buy_setting` to get rule ids. Requires a wallet signature identity. Read-only.

List the logged-in seller's delegations (resource sent to buyers): amount, TRX amount, duration, unit price, type (AUTO, MANUAL, EXTEND, FAST), status and payout. Newest first; page with `offset`/`limit`. Use for a seller's per-delegation history; for earnings totals use `tronsave_get_seller_stats`, for orders the user bought use `tronsave_list_orders` (`isOnlyMyOrder`). Requires a wallet signature identity. Read-only.

List extendable delegate candidates for a `receiver` and `resourceType` (ENERGY|BANDWIDTH). Optional `suggestData` scores an extend-and-buy scenario for planning purposes. Read-only; does NOT create orders or change on-chain state. No login required. NOTE: this is GraphQL market data for discovery only. To actually submit an extension, use `tronsave_internal_create_extend_request` with `extendData` from the authenticated REST `POST /v2/get-extendable-delegates` (payload shape differs from this GraphQL response).

List the receiver addresses that have delegations bought by `requester` which can still be extended, with expiry time (Unix seconds), delegation count and total amount. Use as the first step of an extension flow to find which receiver to extend, then `tronsave_list_extendable_delegates` (market view) or `tronsave_internal_extend_delegates` (API-key path, returns the `extendData` to submit). Public (any requester address), read-only.

Browse the flash-unstake market: `available` (open orders buyers can take), `ongoing` (being paid out) or `completed`. Amounts are SUN-scaled numbers; `estimateCompletionTime` is seconds. Use to browse the whole market; the user's own request is `tronsave_get_flash_unstake_request` and a payout preview is `tronsave_estimate_flash_unstake`. Public, read-only.

List the TRX ledger of the logged-in user's internal account (deposits, order payments, refunds), newest first, with the current balance and deposit address. Amounts are SUN strings. Use to reconcile spending after orders. For the orders themselves use `tronsave_internal_order_history` (API key) or `tronsave_list_orders` (`isOnlyMyOrder`); for the balance alone, `tronsave_get_internal_account`. Page with `offset`/`limit`. Requires a wallet signature identity. Read-only.

List the logged-in user's notifications (order created / filled / cancelled / reclaimed, referral payouts) newest first, with the unread count. Use to follow up on an order after creating it; page with `offset`/`limit`, and mark items read with `tronsave_mark_notifications_read`. Requires a wallet signature identity. Read-only.

Read market depth buckets for `ENERGY` or `BANDWIDTH`. Public view; with an API key, `tronsave_internal_order_book` adds SLOW/MEDIUM/FAST price tiers. Returns price buckets `{ min, max, value }` optionally scoped by viewer address, minimum delegate amount, and duration. No login required; read-only and idempotent. Use this to estimate market ranges before create/update decisions; pair with `tronsave_estimate_buy_resource` for quote-style buy estimation and `tronsave_get_order` for one concrete order.

Query the market order list with paging (`offset`, `limit` ≤ 10). For an API-key account's own purchases use `tronsave_internal_order_history`. Returns `{ orders: [{ id, requester?.address, receiver.address, resourceType, resourceAmount, remainAmount, durationSec, unitPrice (SUN), isOwner, isMatching, apy, createdAt, typeOrder (NORMAL|FAST|EXTEND) }] }`. `status`: `ACTIVE` = still matching, `COMPLETED` = no longer matching. Set `isOnlyMyOrder=true` (requires a wallet signature identity) to list orders requested by the caller's wallet. Use `tronsave_get_order` with an `id` for one snapshot before mutating an order.

Log in to TronSave for the rest of this MCP connection. Provide EXACTLY ONE of: `signature` = `<signature>_<timestamp>` produced by the user's wallet over the `message` from `tronsave_get_sign_message` (unlocks wallet tools; also loads the wallet's internal API key if it has one), or `apiKey` = raw TronSave internal API key (unlocks internal-account tools and `paymentMethod=internal`). The login is bound to the current `mcp-session-id` automatically — do not pass session ids in later tool arguments. Returns `{ sessionId, authMode, walletAddress?, hasInternalApiKey, expiresAt, unlocked }`. Signed timestamps older than the server limit (default 24h) are rejected with `SIGNATURE_EXPIRED`. Never ask the user for private keys or seed phrases.

Remove the TronSave login bound to this MCP connection (api-key or signature). Returns `{ loggedOut: true }`; idempotent. Header credentials configured on the client are not affected.

Mark one notification (by `id`) or, when `id` is omitted, ALL of the user's notifications as read. Get ids from `tronsave_list_notifications`. Only changes the read flag; idempotent. Requires a wallet signature identity.

Create the initial auto-sell configuration for the authenticated user. Returns the persisted `autoSettings` payload. Side effect: persists automation settings that affect future delegation/sell behavior; not idempotent — calling twice may reset fields. Requires a wallet signature identity. Use for FIRST-TIME setup only; for subsequent edits use `tronsave_update_auto_sell_setting`, and always read the current state with `tronsave_get_user_auto_setting` first to avoid overwriting unknown fields. Fails for invalid config combinations, unauthorized sessions, or backend policy restrictions.

Revoke the caller's current internal API key. Side effect: any future request using the previous key is rejected. Existing in-flight sessions cached by the server may continue serving until their TTL expires — treat the effect as 'best-effort immediate' rather than guaranteed instantaneous cutoff. Idempotent — revoking an already-revoked key returns success. Requires a wallet signature identity. Call `tronsave_generate_api_key` afterwards to mint a replacement when continued internal access is needed.

Manually execute seller-side fulfillment of an existing order with a wallet `signedTx`. Returns `{ success, message, code, delegatedId }`. Side effect: broadcasts a market/delegation transaction and may consume balances/resources; not idempotent — each call re-executes. Requires a wallet signature identity. Use only when explicit manual sell is intended; call `tronsave_get_order` first to verify order state before signing.

Ask the market how a buy would be filled: a plain new order, buying more only, or extending existing delegations (optionally plus extra). Returns each option with `readyToFill` (percent), `payout` (SUN) and the `extendData` rows. Use before `tronsave_create_order` when the receiver may already have delegations that can be extended cheaper. Public, read-only. Prices move every ~3 s: re-run right before ordering.

Change an auto-buy rule by id: pause or resume it with `isActive`, or change any of price cap, amount, duration, threshold and limits (only the fields you send change). Side effect: a resumed or loosened rule can start spending internal TRX again. Idempotent for the same arguments. Get ids from `tronsave_list_auto_buy_settings`. Requires a wallet signature identity.

Update the existing auto-sell configuration with partial fields. Returns the updated `autoSettings` payload. Side effect: overwrites stored automation settings for the current user; not idempotent across different field sets. Requires a wallet signature identity. Use for INCREMENTAL changes after registration; read the baseline via `tronsave_get_user_auto_setting` to avoid accidental resets, and use `tronsave_register_auto_sell` only for first-time setup. Fails for invalid field combinations, unauthorized sessions, or policy constraints.

Update an open order by `orderId` with partial fields (`receiver`, `newPrice`). Returns `{ success, message, code }`. Side effect: overwrites live order parameters; not idempotent — each call with a different `newPrice` produces a new state. Requires a wallet signature identity (the order's owner). Prefer this over cancel+recreate when only price/receiver should change. Verify state with `tronsave_get_order` first; fails for already-fulfilled, already-cancelled, or non-editable orders.

Replace the Telegram alert filters. Send the COMPLETE `sellerFilter` and/or `buyerFilter` objects (read the current ones with `tronsave_get_telegram_notify_setting`, edit, send back); each range or value has `isEnabled` plus its numbers. Only changes which alerts are sent; no funds move. Idempotent. Requires a wallet signature identity and a linked Telegram account.