---
title: JustLend MCP Tool Catalog for AI Agents
description: Generated JustLend MCP tool catalog with routing guidance, side-effect classes, safety annotations, wallet requirements, and source links for AI agents.
tags:
  - justlend
  - mcp
  - tool-catalog
  - ai-docs
  - safety
  - wallet
---

# JustLend MCP Tool Catalog for AI Agents

Use this page when an AI agent must choose a JustLend MCP tool, inspect required parameters, compare read-only tools with write tools, or explain whether a workflow can sign and broadcast a TRON transaction.

This docs-local page wraps the generated catalog from the MCP repository so RAG systems can retrieve both routing context and the complete tool list in one chunk set.

## Source links and routing rules

- Start with the [AI Docs Index](index.md) for task routing.
- Read [MCP Safety Policy](mcp_safety.md) before any write action.
- Use [Source of Truth](source_of_truth.md) to choose between OpenAPI, MCP, contracts, ABIs, and human docs.
- Use [Common Questions](common_questions.md) for English and Chinese user-intent mapping.
- Use the public API spec at [`justlend_apis.yaml`](../../developers/apis/justlend_apis.yaml) for read-only HTTP integrations.

## High-value tool groups

| User intent | Prefer these MCP tools | Safety class |
|-------------|------------------------|--------------|
| Market list, APY, TVL, utilization | `get_supported_markets`, `get_market_data`, `get_all_markets` | Read-only |
| Wallet and account risk | `get_wallet_address`, `get_account_summary`, `get_wallet_balances` | Read-only / wallet read |
| Supply, borrow, repay, withdraw | `supply`, `borrow`, `repay`, `withdraw`, `withdraw_all`, `estimate_lending_energy` | Writes require HITL |
| sTRX staking | `get_strx_dashboard`, `get_strx_account`, `stake_trx_to_strx`, `unstake_strx`, `claim_strx_rewards` | Writes require HITL |
| Energy rental / direct purchase | `get_energy_rental_dashboard`, `rent_energy`, `get_energy_purchase_config`, `quote_energy_purchase`, `get_energy_purchase_history`, `get_energy_payment_risk`, `buy_energy_direct` | Writes require HITL; direct purchase is quote-bound |

Chinese query aliases: “查询市场/APY/TVL” maps to market read tools; “查看我的仓位/健康度” maps to account summary; “帮我存款/借款/还款/赎回/质押/租能量/买能量” maps to write tools and must require explicit confirmation.

---

## Generated MCP API List — `@justlend/mcp-server-justlend` v1.1.3

> **Machine-readable tool catalog (for offline routing).** Auto-generated by `scripts/gen-mcp-api-list.ts` from the `registerTool` definitions + Zod inputSchema + MCP annotations in the source — do not edit by hand; after changing any tool run `npx tsx scripts/gen-mcp-api-list.ts` to regenerate.
>
> Lets an AI agent plan tool routing offline without connecting to the server. Side-effect classes align with the AI-Agent documentation standard baseline (Safe / Network Read / Remote Write / Destructive).

**Total tools**: 104  |  **Protocol**: MCP  |  **Transport**: stdio / HTTP(SSE)

## Common structured output contract (v1.0.0)

Every tool declares an MCP `outputSchema`. Successful calls preserve the legacy text `content` and also return:

```json
{
  "schemaVersion": "1.0.0",
  "tool": "get_supported_markets",
  "result": {}
}
```

Consume `structuredContent` when available; older clients may continue parsing the first text content item. Error results keep `isError: true` and the existing structured JSON error body.

**Read-only tools**: 63  |  **Write tools**: 41 (of which marked destructive: 28)

> ⚠️ Tools marked 🔴 **sign and broadcast TRON transactions that move real assets** — the client MUST require human confirmation (HITL) before executing. 🟡 tools only change local wallet/network config or start an interaction. Private keys are managed encrypted by `@bankofai/agent-wallet` and are **never passed as tool arguments**. The legacy unauthenticated browser-wallet bridge is disabled.

---

## Wallet & Network (10)

### `get_wallet_address`

**Get Wallet Address**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: Get the active agent-wallet address, or a first-use wallet setup guide if no wallet mode has been chosen yet. Legacy browser mode is disabled until its bridge supports request-level authentication.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `list_wallets`

**List Wallets**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: List all wallets configured in agent-wallet. Shows wallet IDs, types, active status, and addresses.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `set_active_wallet`

**Set Active Wallet**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: false
- **Description**: Set the active wallet by wallet ID. Use list_wallets to see available wallet IDs.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `walletId` | string | ✅ |  | The wallet ID to set as active |

### `connect_browser_wallet`

**Connect Browser Wallet**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: false · openWorld: true
- **Description**: Browser wallet signing is temporarily disabled because the legacy local bridge lacks request-level authentication. Use agent-wallet with AGENT_WALLET_PASSWORD until an authenticated bridge is available.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Required TRON address (T...). If set, the user must connect this exact address. |

### `set_wallet_mode`

**Set Wallet Mode**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: false
- **Description**: Switch wallet signing mode. 'agent' uses an encrypted key stored in ~/.agent-wallet/. Browser mode is disabled until the local bridge supports request-level authentication. Selecting agent mode for the first time will create an encrypted agent-wallet if needed.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `mode` | enum(browser | agent) | ✅ |  | Wallet mode: 'browser' or 'agent' |

### `get_wallet_mode`

**Get Wallet Mode**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: Get the current wallet signing mode and agent-wallet status. Legacy browser mode is reported as disabled.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `set_network`

**Set Global Network**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: false
- **Description**: Set the global default network used by all JustLend operations unless explicitly overridden.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | ✅ |  | Network name (mainnet, nile). |

### `get_network`

**Get Global Network**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: Get the current global default network used by all JustLend operations.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `transfer_trx`

**Transfer TRX**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: false · openWorld: true
- **Description**: Transfer TRX to another TRON address. Checks balance sufficiency (including gas) before sending. Typical cost: ~0 energy + ~270 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `to` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Recipient TRON address (Base58 T... format) |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of TRX to transfer (e.g. '1', '10.5') |
| `network` | string | — |  | Network. Default: mainnet |

### `transfer_trc20`

**Transfer TRC20**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: false · openWorld: true
- **Description**: Transfer TRC20 tokens to another TRON address. You can pass a token symbol (e.g. 'USDT', 'JST', 'wstUSDT') or a contract address. Symbol resolution uses the server's known TRON token registry and JustLend underlying-token mappings. Amount is in human-readable units (e.g. '100' for 100 USDT). Checks balance sufficiency before sending.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `to` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Recipient TRON address (Base58 T... format) |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount to transfer in human-readable units (e.g. '100' for 100 USDT) |
| `token` | string | — |  | Token symbol (e.g. 'USDT', 'JST', 'SUN'). Preferred over tokenAddress. |
| `tokenAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRC20 token contract address. Use 'token' parameter instead when possible. |
| `network` | string | — |  | Network. Default: mainnet |

## Market Data (13)

### `get_supported_networks`

**Get Supported Networks**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: List all supported TRON networks for JustLend.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `get_supported_markets`

**Get Supported Markets**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: List all available JustLend lending markets (jTokens) with their addresses and underlying assets.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network (mainnet, nile). Default: mainnet |

### `get_market_data`

**Get Market Data**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get detailed market data for a specific JustLend market: supply/borrow APY, TVL, utilization, collateral factor, price, and status. Use jToken symbol like 'jUSDT' or 'jTRX'.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') or jToken address |
| `network` | string | — |  | Network. Default: mainnet |

### `get_all_markets`

**Get All Markets**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get overview data for ALL JustLend markets including supply APY, borrow APY, mining rewards APY, underlying staking yield, total supply APY, and TVL. Mining APY is calculated from on-chain supply mining programs (USDD/TRX dual mining, WBTC mining, etc.). totalSupplyAPY = base supply APY + underlying staking APY + mining APY.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_protocol_summary`

**Get Protocol Summary**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get JustLend protocol-level info: Comptroller config, close factor, liquidation incentive, total markets.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_account_summary`

**Get Account Summary**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a comprehensive view of a user's JustLend positions (supply, borrow, health factor). IMPORTANT: Returns a snapshot tied to a specific block. You MUST call this again after any transaction (supply, withdraw, etc.) to get updated balances and health factor.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address (Base58 T... format) to check. Leave empty to use configured wallet. |
| `network` | string | — |  | Network. Default: mainnet |

### `check_allowance`

**Check Allowance**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Check if the underlying TRC20 token has been approved for a jToken market. Must be approved before supply() or repay() for TRC20 markets. Not needed for jTRX. The returned 'allowance' is in human-readable token units (e.g. '1' means 1 USDT, not 1 raw unit). Compare it directly with the amount the user wants to supply/repay. 'allowanceUnit' indicates the token symbol.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT') |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | — |  | Amount to check sufficiency against (human-readable, e.g. '0.5'). If provided, returns whether allowance is sufficient. |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Address to check. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_trx_balance`

**Get TRX Balance**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get TRX balance for an address.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_token_balance`

**Get Token Balance**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get TRC20 token balance for an address. You can pass either a token symbol (e.g. 'USDD', 'USDT', 'ETH') or a contract address. When using a symbol, it resolves to the correct contract address from JustLend markets automatically. IMPORTANT: Always prefer using token symbols over raw addresses to avoid using outdated/wrong contract addresses. For example, use 'USDD' instead of a raw address — the old USDD (TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn) is deprecated. The returned balance is already formatted in human-readable token units (decimals already applied). Do NOT divide the balance by decimals again.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `token` | string | — |  | Token symbol (e.g. 'USDD', 'USDT', 'TRX', 'ETH', 'BTC', 'SUN', 'JST', 'WIN', 'BTT', 'NFT', 'TUSD', 'WBTC', 'USD1', 'wstUSDT', 'sTRX'). Preferred over tokenAddress. |
| `tokenAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRC20 token contract address. Use 'token' parameter with a symbol name instead when possible. |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_wallet_balances`

**Get Wallet Token Balances (Batch)**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Batch-fetch TRC20 token balances for a wallet across multiple JustLend markets in a single RPC call using the Multicall3 walletTokensBalance method. Returns human-readable balances (decimals already applied) for all specified tokens at once. Use this instead of calling get_token_balance repeatedly when you need balances for several tokens.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `tokens` | string[] | — |  | List of token symbols to check (e.g. ['USDT', 'USDD', 'ETH', 'BTC']). Defaults to all TRC20 underlying tokens across all JustLend markets. |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON wallet address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_mining_rewards`

**Get Mining Rewards**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get mining rewards for supply markets (USDD, WBTC, etc.). Returns unclaimed rewards, mining APY, and reward breakdown from API.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Leave empty to use configured wallet. |
| `network` | string | — |  | Network. Default: mainnet |

### `get_usdd_mining_config`

**Get USDD Mining Config**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: Get USDD mining configuration including mining periods, reward tokens (USDD/TRX dual mining), and schedule.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_wbtc_mining_config`

**Get WBTC Mining Config**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: false
- **Description**: Get WBTC mining configuration and supply mining activity details.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

## Lending Operations (10)

### `supply`

**Supply Assets**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Supply (deposit) assets into a JustLend market to earn interest. For TRC20 markets, you must first call approve_underlying. For jTRX, TRX is sent directly. Returns a jToken balance representing your deposit. Typical cost: ~100,000 energy + ~310 bandwidth for TRC20, ~80,000 energy + ~280 bandwidth for TRX. Use estimate_lending_energy tool for precise estimates before executing.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of underlying to supply (e.g. '1000' for 1000 USDT) |
| `network` | string | — |  | Network. Default: mainnet |

### `withdraw`

**Withdraw Assets**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw (redeem) supplied assets from a JustLend market. Specify the amount in underlying units. May fail if assets are used as collateral for active borrows. Typical cost: ~90,000 energy + ~300 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of underlying to withdraw (e.g. '500') |
| `network` | string | — |  | Network. Default: mainnet |

### `withdraw_all`

**Withdraw All**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw ALL supplied assets from a JustLend market by redeeming all jTokens. Typical cost: ~90,000 energy + ~300 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT') |
| `network` | string | — |  | Network. Default: mainnet |

### `borrow`

**Borrow Assets**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Borrow assets from a JustLend market against your collateral. You must have entered a market as collateral (enter_market) and have sufficient liquidity. Check your account_summary and health_factor before borrowing. Typical cost: ~100,000 energy + ~313 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of underlying to borrow (e.g. '500') |
| `network` | string | — |  | Network. Default: mainnet |

### `repay`

**Repay Borrow**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Repay borrowed assets to a JustLend market. For TRC20 markets, must have approved underlying first. Use amount='max' to repay the full outstanding borrow. Typical cost: ~80,000~90,000 energy + ~280~320 bandwidth (TRX costs less than TRC20).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Amount to repay (e.g. '500'), or 'max' for full repayment |
| `network` | string | — |  | Network. Default: mainnet |

### `enter_market`

**Enter Market (Enable Collateral)**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Enable a jToken market as collateral. Required before borrowing against supplied assets. Once entered, your supply in this market counts towards your borrowing capacity. Typical cost: ~80,000 energy + ~300 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX') |
| `network` | string | — |  | Network. Default: mainnet |

### `exit_market`

**Exit Market (Disable Collateral)**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Disable a jToken market as collateral. Pre-checks: 1) market must have no outstanding borrows; 2) remaining collateral must still cover all borrows. Typical cost: ~50,000 energy + ~280 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT') |
| `network` | string | — |  | Network. Default: mainnet |

### `approve_underlying`

**Approve Underlying Token**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Approve the jToken contract to spend your underlying TRC20 tokens. Required before supply() or repay() for TRC20-backed markets (not needed for jTRX). Pass the EXACT amount you intend to use (recommended). Pass amount='max' for unlimited approval ONLY when the user explicitly opts in — it lets the jToken contract spend the user's entire balance, present and future, until revoked. Typical cost: ~23,000 energy + ~265 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT') |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Exact amount to approve (e.g. '100'), or 'max' for unlimited (NOT recommended; user must opt in). |
| `network` | string | — |  | Network. Default: mainnet |

### `claim_rewards`

**Claim Rewards**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: false · openWorld: true
- **Description**: Claim accrued JustLend mining rewards for the configured wallet. Typical cost: ~60,000 energy + ~330 bandwidth.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `estimate_lending_energy`

**Estimate Operation Resources**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Estimate energy, bandwidth, and TRX cost for any JustLend operation BEFORE executing it. Covers ALL operations: supply, withdraw, withdraw_all, borrow, repay, approve, enter_market, exit_market, claim_rewards. Tries on-chain simulation first; falls back to historical typical values if simulation fails. Returns per-step breakdown (e.g. approve + mint for supply), total energy, total bandwidth, and estimated TRX cost. For supply/repay: automatically checks current allowance — if sufficient, the approve step is skipped. For approve: supports custom spender address (not just jToken). Use this tool whenever the user asks about gas/energy/cost for any lending operation.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `operation` | enum(supply | withdraw | withdraw_all | borrow | repay | approve | enter_market | exit_market | claim_rewards) | ✅ |  | The operation to estimate resources for |
| `market` | string | ✅ |  | jToken symbol (e.g. 'jUSDT', 'jTRX', 'jUSDD'). Required for all operations except claim_rewards. |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | — |  | Amount in underlying token units (e.g. '100'). Default: '1'. Not needed for enter_market, exit_market, approve, withdraw_all, claim_rewards. |
| `spender` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Custom spender address for approve operation. Default: jToken contract address. Only used when operation is 'approve'. |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address for simulation. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

## JST Voting / Governance (10)

### `get_proposal_list`

**Get Proposal List**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get the list of JustLend DAO governance proposals. Returns proposals with their status (Active, Passed, Defeated, etc.), vote counts, and details. Sorted by newest first.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |
| `limit` | number | — |  | Max number of proposals to return. Default: 10. Use 0 for all. |

### `get_user_vote_status`

**Get User Vote Status**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's voting status across all governance proposals. Shows which proposals the user has voted on, their vote amounts (for/against/abstain), and which proposals have withdrawable votes.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_vote_info`

**Get Vote Info**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get voting power info for a user: JST wallet balance, available (surplus) votes, total deposited votes, and votes currently cast in proposals. This is the key tool to check before voting — it shows how many votes are available to use.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_locked_votes`

**Get Locked Votes**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get the number of votes a user has locked in a specific proposal.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `proposalId` | number | ✅ |  | The proposal ID to check |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `check_jst_allowance_for_voting`

**Check JST Voting Allowance**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Check if JST has been approved for the WJST voting contract. Must be approved before depositing JST to get votes.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `approve_jst_for_voting`

**Approve JST for Voting**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Approve JST token for the WJST voting contract. Required before depositing JST to get voting power. Pass the EXACT amount you intend to deposit (recommended). Pass amount='max' for unlimited approval ONLY when the user explicitly opts in — it lets the WJST contract spend the user's entire JST balance, present and future, until revoked.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Exact amount to approve (e.g. '1000'), or 'max' for unlimited (NOT recommended; user must opt in). |
| `network` | string | — |  | Network. Default: mainnet |

### `deposit_jst_for_votes`

**Deposit JST for Votes**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Deposit JST into the WJST contract to get voting power. Requires prior approval of JST for the WJST contract (use approve_jst_for_voting first). 1 JST = 1 Vote. Deposited JST can be withdrawn back after voting.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of JST to deposit (e.g. '1000') |
| `network` | string | — |  | Network. Default: mainnet |

### `withdraw_votes_to_jst`

**Withdraw Votes to JST**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw WJST back to JST. Can only withdraw votes that are not currently locked in active proposals. Use get_vote_info to check your surplus (available) votes before withdrawing.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of votes/WJST to withdraw back to JST (e.g. '1000') |
| `network` | string | — |  | Network. Default: mainnet |

### `cast_vote`

**Cast Vote**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Cast a vote on a governance proposal. You must have available votes (deposit JST first if needed). Support: true = vote FOR, false = vote AGAINST. You can add more votes to a proposal you already voted on.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `proposalId` | number | ✅ |  | The proposal ID to vote on |
| `support` | boolean | ✅ |  | true = vote FOR the proposal, false = vote AGAINST |
| `votes` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of votes to cast (e.g. '1000') |
| `network` | string | — |  | Network. Default: mainnet |

### `withdraw_votes_from_proposal`

**Withdraw Votes from Proposal**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw (reclaim) votes from a completed or canceled proposal. Only works for proposals that are no longer active. After withdrawing, the votes become available again for other proposals or can be converted back to JST.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `proposalId` | number | ✅ |  | The proposal ID to withdraw votes from |
| `network` | string | — |  | Network. Default: mainnet |

## Energy Rental (15)

### `get_energy_purchase_config`

**Energy Purchase Config**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get live energy direct-purchase limits, supported durations, current unit prices, and pool capacity. Uses the official JustLend production API by default; JUSTLEND_ENERGY_API_URL overrides it.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `quote_energy_purchase`

**Quote Energy Purchase**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get an authoritative, read-only quote for direct energy purchase. It does not create an order, sign, broadcast, or reserve funds. Limits and resource-pool exclusions are validated against live config.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `receiverAddresses` | string[] | ✅ |  | One or more energy receiver addresses |
| `energyPerReceiver` | number (min 0, max 9007199254740991) | ✅ |  | Energy amount for each receiver |
| `duration` | string (min len 1) | ✅ |  | Duration exactly as advertised by get_energy_purchase_config |

### `get_energy_purchase_order`

**Energy Purchase Order**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get the current lifecycle state and delivery details for an energy purchase order.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `orderId` | union | ✅ |  | Energy purchase order id |
| `orderToken` | string (min len 1) | — |  | Optional X-Consumer-Order-Token returned when the order was accepted |

### `get_energy_purchase_history`

**Energy Purchase History**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get public direct-purchase history for a payer address, including in-progress and settled orders. Use it to recover an accepted order when an idempotent retry returns no access token.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Payer address. Default: configured wallet |
| `page` | number (min 0) | — |  | History page (1-based; used with size) |
| `size` | number (min 0) | — |  | Rows per page; omit for the backend default/all-history view |

### `get_energy_payment_risk`

**Energy Payment Risk**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Return unresolved direct-purchase payment risks for the configured wallet without replaying a signed payment. If any result remains, do not sign a new payment.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)
- **Params**: none

### `buy_energy_direct`

**Buy Energy Direct**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: VALUE-MOVING OPERATION. Buy energy by signing a native TRX payment. The MCP server never broadcasts the payment locally; the configured energy service validates and may broadcast it. Call quote_energy_purchase first, show the payer, receivers, duration, and exact TRX amount to the user, and set confirmPayment=true only after the user explicitly confirms. Ambiguous submissions retry only the same signed transaction and block a new payment.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `receiverAddresses` | string[] | ✅ |  | One or more energy receiver addresses |
| `energyPerReceiver` | number (min 0, max 9007199254740991) | ✅ |  | Energy amount for each receiver |
| `duration` | string (min len 1) | ✅ |  | Duration exactly as advertised by get_energy_purchase_config |
| `expectedAmountSun` | number (min 0, max 9007199254740991) | ✅ |  | Exact total_sun from the quote explicitly confirmed by the user |
| `expectedPayAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Exact payment_address from the quote explicitly confirmed by the user |
| `confirmPayment` | literal | ✅ |  | Must be true only after the user explicitly confirms this value-moving payment |
| `network` | string | — |  | Signing network. Default: configured network |

### `get_energy_rental_dashboard`

**Energy Rental Dashboard**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get JustLend energy rental market dashboard data including TRX price, exchange rate, total APY, energy per TRX, total supply, and other market parameters.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_energy_rental_params`

**Energy Rental Parameters**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get on-chain energy rental parameters: liquidation threshold, fee ratio, min fee, total delegated/frozen TRX, max rentable amount, rent paused status, usage charge ratio.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `calculate_energy_rental_price`

**Calculate Energy Rental Price**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Calculate the cost to rent a specific amount of energy for a given duration. Returns TRX amount needed, rental rate, fee, total prepayment, security deposit, and daily cost. For NEW rentals: provide energyAmount and durationHours. For RENEWALS: provide energyAmount and receiverAddress. The tool auto-detects existing rentals and calculates the incremental cost (subtracting existing security deposit). durationHours is optional for renewals (defaults to 0 = no additional time).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `energyAmount` | number (min 50000) | ✅ |  | Amount of energy to rent (minimum 300,000 for new rental, minimum 50,000 for renewal) |
| `durationHours` | number (min 0) | — |  | Rental duration in hours. Required for new rentals (minimum 1). Optional for renewals (default 0 = no additional time). |
| `receiverAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Receiver address. If provided, checks for existing rental to calculate renewal cost. |
| `network` | string | — |  | Network. Default: mainnet |

### `get_energy_rental_rate`

**Energy Rental Rate**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get the current energy rental rate for a given TRX amount. Returns rental rate, stable rate, and effective rate (max of both).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `trxAmount` | number (min 0) | ✅ |  | TRX amount to check rate for (0 for base rate) |
| `network` | string | — |  | Network. Default: mainnet |

### `get_user_energy_rental_orders`

**User Energy Rental Orders**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get a user's energy rental orders from JustLend. Can filter by role: 'renter' (orders where user is renting out), 'receiver' (orders where user receives energy), or 'all'.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Address to query. Default: configured wallet |
| `type` | enum(renter | receiver | all) | — |  | Filter by role. Default: all |
| `page` | number | — |  | Page number (0-indexed). Default: 0 |
| `pageSize` | number | — |  | Results per page. Default: 10 |
| `network` | string | — |  | Network. Default: mainnet |

### `get_energy_rent_info`

**Energy Rent Info**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get on-chain energy rental info for a specific renter-receiver pair. Returns security deposit, rent balance, and whether an active rental exists.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `renterAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Renter address. Default: configured wallet |
| `receiverAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Receiver address |
| `network` | string | — |  | Network. Default: mainnet |

### `get_return_rental_info`

**Return Rental Info**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get estimated refund info for returning/canceling an energy rental. Shows how much TRX would be refunded (estimatedRefundTrx), remaining rent, security deposit, usage rental cost, unrecovered energy, and daily rent cost.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `renterAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Renter address. Default: configured wallet |
| `receiverAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Receiver address |
| `network` | string | — |  | Network. Default: mainnet |

### `rent_energy`

**Rent Energy**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Rent energy from JustLend for a specified receiver address. Automatically calculates TRX needed based on energy amount. For NEW rentals: durationHours is required (minimum 1 hour), minimum energy is 300,000. For RENEWALS (existing active rental to the same receiver): durationHours is NOT needed — the remaining duration from the existing order is used automatically. Minimum energy for renewal is 50,000. Pre-checks: rental not paused, amount within limits, sufficient TRX balance.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `receiverAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Address that will receive the energy |
| `energyAmount` | number (min 50000) | ✅ |  | Amount of energy to rent (minimum 300,000 for new rental, minimum 50,000 for renewal) |
| `durationHours` | number (min 1) | — |  | Rental duration in hours (minimum 1 hour). Required for new rentals. Ignored for renewals (uses existing order's remaining duration). |
| `network` | string | — |  | Network. Default: mainnet |

### `return_energy_rental`

**Return Energy Rental**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Return (cancel) an active energy rental. As a renter, provide the receiver address. As a receiver, provide the renter address. Pre-checks: active rental must exist between the two addresses.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `counterpartyAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | The other party's address (receiver if you are renter, renter if you are receiver) |
| `endOrderType` | enum(renter | receiver) | — |  | Your role: 'renter' (default) or 'receiver' |
| `network` | string | — |  | Network. Default: mainnet |

## sTRX Staking (7)

### `get_strx_dashboard`

**sTRX Dashboard**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get sTRX staking dashboard data including TRX price, sTRX/TRX exchange rate, total APY, vote APY, total supply, unfreeze delay days, and energy stake per TRX.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_strx_account`

**sTRX Account Info**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get user's sTRX staking account info including staked amount, income, claimable rewards, withdrawn amount, and rental energy amount.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Address to query. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_strx_balance`

**sTRX Balance**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Get the sTRX token balance for an address.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Address to check. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `check_strx_withdrawal_eligibility`

**Check sTRX Withdrawal Eligibility**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: false · openWorld: true
- **Description**: Check if user has TRX available to withdraw after sTRX unstaking unbonding period. Shows staked amount, claimable rewards, pending/completed unstake rounds, and withdrawal status.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Address to check. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `stake_trx_to_strx`

**Stake TRX to sTRX**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Stake TRX via JustLend to receive sTRX tokens. sTRX earns staking rewards (vote APY + energy rental income). Pre-checks: sufficient TRX balance for staking amount + gas.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of TRX to stake (human-readable decimal string, e.g. '1' or '10.5') |
| `network` | string | — |  | Network. Default: mainnet |

### `unstake_strx`

**Unstake sTRX**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Unstake sTRX to receive TRX back. Note: unstaked TRX has an unbonding period (typically 14 days) before withdrawal. Pre-checks: sufficient sTRX balance.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of sTRX to unstake (human-readable decimal string, e.g. '1' or '10.5') |
| `network` | string | — |  | Network. Default: mainnet |

### `claim_strx_rewards`

**Claim sTRX Rewards**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Claim all available sTRX staking rewards. Pre-checks: verifies there are claimable rewards before executing.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

## WTRX Wrap / Unwrap (2)

### `wrap_trx`

**Wrap TRX to WTRX**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Wrap native TRX into WTRX (Wrapped TRX) at a 1:1 rate by sending TRX to the WTRX contract's payable deposit(). WTRX is a TRC20 representation of TRX used by DeFi protocols that can't hold native TRX (e.g. JustLend V2 / Moolah markets quoting WTRX). Reversible: unwrap_trx converts WTRX back to TRX 1:1. Pre-checks: sufficient TRX balance for the wrap amount + gas.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of TRX to wrap into WTRX (human-readable decimal string, e.g. '1' or '10.5') |
| `network` | string | — |  | Network. Default: mainnet |

### `unwrap_trx`

**Unwrap WTRX to TRX**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Unwrap WTRX (Wrapped TRX) back into native TRX at a 1:1 rate via the WTRX contract's withdraw(uint256). No approval is needed — you burn your own WTRX. Reverses wrap_trx (1:1). Pre-checks: sufficient WTRX balance and native TRX for gas.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of WTRX to unwrap into TRX (human-readable decimal string, e.g. '1' or '10.5') |
| `network` | string | — |  | Network. Default: mainnet |

## JustLend V2 (Moolah) — Vaults (6)

### `get_moolah_vaults`

**Get Moolah Vaults**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: List all JustLend V2 (Moolah) vaults with APY, TVL, and underlying token. Vaults are ERC4626 — deposit tokens to earn auto-compounding yield allocated across Moolah markets.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `depositToken` | string | — |  | Filter by deposit token symbol (e.g. 'USDT', 'TRX') |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_vault`

**Get Moolah Vault**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get detailed info for a single Moolah vault: APY, TVL, allocation, and the user's share balance if address is provided. vaultSymbol is 'TRX', 'USDT', or 'USDD'.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultSymbol` | string | ✅ |  | Vault symbol: 'TRX', 'USDT', or 'USDD' |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | User address to include share balance. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `approve_moolah_vault`

**Approve Moolah Vault**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Approve TRC20 token spending for a Moolah vault before depositing. Not needed for TRX vaults. Pass the EXACT amount you intend to deposit (recommended). Pass amount='max' for unlimited approval ONLY when the user explicitly opts in — it lets the vault contract spend the user's entire balance, present and future, until revoked (amount='0').
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultSymbol` | string | ✅ |  | Vault symbol: 'USDT' or 'USDD' |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Exact amount to approve (e.g. '100'), or 'max' for unlimited (NOT recommended; user must opt in). |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_vault_deposit`

**Moolah Vault Deposit**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Deposit assets into a Moolah ERC4626 vault to earn yield. For TRC20 vaults (USDT, USDD), call approve_moolah_vault first. Returns vault shares representing your deposit.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultSymbol` | string | ✅ |  | Vault symbol: 'TRX', 'USDT', or 'USDD' |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of underlying to deposit (e.g. '1000' for 1000 USDT) |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_vault_withdraw`

**Moolah Vault Withdraw**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw underlying assets from a Moolah vault by specifying the asset amount. Use amount='max' to withdraw everything. No approval needed.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultSymbol` | string | ✅ |  | Vault symbol: 'TRX', 'USDT', or 'USDD' |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Amount of underlying to withdraw, or 'max' for full withdrawal |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_vault_redeem`

**Moolah Vault Redeem**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Redeem vault shares to receive underlying assets. Use shares='max' to redeem all shares. No approval needed.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultSymbol` | string | ✅ |  | Vault symbol: 'TRX', 'USDT', or 'USDD' |
| `shares` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Number of shares to redeem, or 'max' for all shares |
| `network` | string | — |  | Network. Default: mainnet |

## JustLend V2 (Moolah) — Markets (8)

### `get_moolah_markets`

**Get Moolah Markets**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: List JustLend V2 (Moolah) markets with borrow/supply APY, LLTV, utilization, and liquidity. Markets are isolated — each has its own loan token, collateral token, oracle, and LLTV.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `depositToken` | string | — |  | Filter by loan token symbol (e.g. 'USDT') |
| `collateralToken` | string | — |  | Filter by collateral token symbol (e.g. 'TRX') |
| `pageSize` | number | — |  | Max results. Default: 20 |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_market`

**Get Moolah Market**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get full details for a single Moolah market by its marketId (bytes32 hex). Includes APY, LLTV, utilization, total supply/borrow, and vaults supplying to this market. Use get_moolah_markets to find marketIds.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex, e.g. '0xabc...') |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_user_position`

**Get Moolah User Position**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's position in a specific Moolah market: collateral, borrow amount, lltv, and risk ratio. risk close to 1.0 means the position is near liquidation — consider repaying or adding collateral.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | User address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `approve_moolah_proxy`

**Approve Moolah Proxy**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Approve TRC20 token spending for the Moolah core contract before supplying collateral or repaying. Not needed for TRX operations. Pass the EXACT amount you intend to use (recommended). Pass amount='max' for unlimited approval ONLY when the user explicitly opts in — it lets the Moolah proxy spend the user's entire balance, present and future, until revoked (amount='0').
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `tokenAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRC20 contract address (Base58) |
| `tokenSymbol` | string | ✅ |  | Token symbol for display (e.g. 'USDT') |
| `tokenDecimals` | number (min 0, max 38) | ✅ |  | Token decimals (e.g. 6 for USDT). Integer in [0, 38]. |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Exact amount to approve (e.g. '100'), or 'max' for unlimited (NOT recommended; user must opt in). |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_supply_collateral`

**Moolah Supply Collateral**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Supply collateral into a Moolah market to enable borrowing. For TRC20 collateral, call approve_moolah_proxy first. For TRX collateral, TRX is sent directly with no prior approval.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) — from get_moolah_markets |
| `amount` | string (pattern /^\d+(\.\d+)?$/) | ✅ |  | Amount of collateral to supply (e.g. '10000' for 10000 TRX) |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_withdraw_collateral`

**Moolah Withdraw Collateral**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Withdraw collateral from a Moolah market. Use amount='max' to withdraw all collateral (only allowed when no active borrows). Withdrawing too much while borrowing will revert — check health factor first.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Amount of collateral to withdraw, or 'max' for all (requires no active borrows) |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_borrow`

**Moolah Borrow**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Flexible Moolah borrow entry point. Provide collateralAmount only → supply collateral without borrowing. Provide borrowAmount only → borrow against existing collateral. Provide both → supply collateral then borrow in two sequential transactions. Collateral must cover the borrow at the market's LLTV or the borrow tx reverts.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) — from get_moolah_markets |
| `collateralAmount` | string (pattern /^\d+(\.\d+)?$/) | — |  | Collateral to supply first (e.g. '10000' TRX). Omit to skip. |
| `borrowAmount` | string (pattern /^\d+(\.\d+)?$/) | — |  | Loan token amount to borrow (e.g. '500' USDT). Omit to skip. |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_repay`

**Moolah Repay**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Repay a Moolah market loan. Use amount='max' to repay the full outstanding borrow (uses shares math for exact settlement). For TRC20 loan tokens, call approve_moolah_proxy first. For TRX loans, TRX is sent directly.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Loan amount to repay, or 'max' for full repayment |
| `network` | string | — |  | Network. Default: mainnet |

## JustLend V2 (Moolah) — Liquidation (5)

### `get_moolah_pending_liquidations`

**Get Pending Liquidations**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: List Moolah positions eligible or approaching liquidation. riskLevel > 1.0 means the position is liquidatable right now. Use minRiskLevel=0.9 to find positions near the threshold.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `minRiskLevel` | number | — |  | Minimum risk level (e.g. 0.9 for near-liquidatable, 1.0 for liquidatable now) |
| `maxRiskLevel` | number | — |  | Maximum risk level filter |
| `debtToken` | string | — |  | Filter by loan token symbol (e.g. 'USDT') |
| `collateralToken` | string | — |  | Filter by collateral token symbol (e.g. 'TRX') |
| `page` | number | — |  | Page number (0-indexed). Default: 0 |
| `pageSize` | number | — |  | Results per page. Default: 20 |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_liquidation_quote`

**Get Liquidation Quote**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Estimate the loan token cost to liquidate a position. Provide either seizedAssets (collateral to take) OR repaidShares (borrow shares to repay), not both. Returns the exact loan token amount needed. Use this before calling moolah_liquidate.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) |
| `seizedAssets` | string (pattern /^\d+$/) | — |  | Collateral amount to seize (raw units). Provide this OR repaidShares. |
| `repaidShares` | string (pattern /^\d+$/) | — |  | Borrow shares to repay (raw units). Provide this OR seizedAssets. |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_liquidation_records`

**Get Liquidation Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Historical liquidation events on Moolah — both bot-executed and public liquidations.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `type` | enum(bot | public) | — |  | Filter by liquidator type |
| `debtToken` | string | — |  | Filter by loan token symbol |
| `collateralToken` | string | — |  | Filter by collateral token symbol |
| `page` | number | — |  | Page number (0-indexed). Default: 0 |
| `pageSize` | number | — |  | Results per page. Default: 20 |
| `network` | string | — |  | Network. Default: mainnet |

### `moolah_liquidate`

**Moolah Liquidate**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Liquidate an undercollateralized Moolah position. You must hold the loan token and have approved it via approve_liquidator_token. Provide EITHER seizedAssets (collateral to seize) OR repaidShares (borrow shares to repay), not both. Use get_moolah_liquidation_quote first to estimate the required loan token amount.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex) |
| `borrower` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Address of the borrower to liquidate (Base58) |
| `seizedAssets` | string (pattern /^\d+$/) | — |  | Collateral units to seize (raw). Provide this OR repaidShares. |
| `repaidShares` | string (pattern /^\d+$/) | — |  | Borrow shares to repay (raw). Provide this OR seizedAssets. |
| `network` | string | — |  | Network. Default: mainnet |

### `approve_liquidator_token`

**Approve Liquidator Token**
- **Side effect**: 🟡 State-changing (Write) — changes local wallet/network config or starts an interaction; client should confirm
- **annotations**: idempotent: true · openWorld: true
- **Description**: Approve loan token spending for the Moolah public liquidator contract. Required before calling moolah_liquidate. Pass the EXACT amount you intend to use (recommended). Pass amount='max' for unlimited approval ONLY when the user explicitly opts in — it lets the liquidator contract spend the user's entire balance, present and future, until revoked (amount='0').
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `tokenAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Loan token contract address (Base58) |
| `tokenSymbol` | string | ✅ |  | Token symbol for display (e.g. 'USDT') |
| `tokenDecimals` | number (min 0, max 38) | ✅ |  | Token decimals (e.g. 6 for USDT). Integer in [0, 38]. |
| `amount` | string (pattern /^(\d+(\.\d+)?|max)$/) | ✅ |  | Exact amount to approve (e.g. '100'), or 'max' for unlimited (NOT recommended; user must opt in). |
| `network` | string | — |  | Network. Default: mainnet |

## JustLend V2 (Moolah) — Dashboard & History (6)

### `get_moolah_dashboard`

**Get Moolah Dashboard**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: JustLend V2 (Moolah) protocol overview: top vaults (APY, TVL) and top markets (borrow/supply rates). If address is provided, also includes the user's aggregated V2 position (total supply, borrow, health factor).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | User address to include V2 position summary. Default: configured wallet |
| `depositToken` | string | — |  | Filter vaults and markets by deposit token symbol |
| `collateralToken` | string | — |  | Filter markets by collateral token symbol |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_history`

**Get Moolah History**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's JustLend V2 position history (net worth, supply, borrow over time) and recent transaction records (supply, borrow, repay, etc.).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | User address. Default: configured wallet |
| `timeFilter` | enum(ONE_DAY | ONE_WEEK | ONE_MONTH) | — |  | History time range. Default: ONE_WEEK |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_records`

**Get Moolah Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's paginated V2 (Moolah) transaction history — supply, withdraw, borrow, repay, liquidate events. Distinct from get_moolah_history (which returns position curves + a small recent-txs preview) — this one is the full paginated record list. Works on both mainnet and nile.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | User address. Default: configured wallet |
| `pageNo` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_vault_history`

**Get Moolah Vault History**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Time series of a V2 Moolah vault's APY, TVL, and supply mining data. Returns currentSupplyUsd, supplyBaseApy, supplyMiningApy, and a historyRecords array. Use vaultAddress from get_moolah_vaults or chains.ts vault map.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Vault contract address (Base58 T...) |
| `network` | string | — |  | Network. Default: mainnet |

### `estimate_moolah_energy`

**Estimate Moolah Energy**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Estimate energy, bandwidth, and TRX cost for a JustLend V2 (Moolah) write operation BEFORE executing it. Returns historical typical values (on-chain simulation for Moolah's tuple-args ops is not yet wired). Set isTRX=true when the underlying / loan / collateral token is native TRX (TrxProviderProxy route). Covers: vault_deposit, vault_withdraw, vault_redeem, approve_vault, supply_collateral, withdraw_collateral, borrow, repay, approve_proxy, liquidate, approve_liquidator.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `operation` | enum(vault_deposit | vault_withdraw | vault_redeem | approve_vault | supply_collateral | withdraw_collateral | borrow | repay | approve_proxy | liquidate | approve_liquidator) | ✅ |  | Moolah operation to estimate |
| `isTRX` | boolean | — |  | Whether the route uses native TRX (via TrxProviderProxy). Default: false |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Owner address for resource-sufficiency check. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_market_history`

**Get Moolah Market History**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Time series of a V2 Moolah market's borrow/supply APY, utilization, and totals. Returns current totalBorrow/totalCollateral + borrowApy/supplyApy + list[] of historical points. Use marketId (bytes32 hex) from get_moolah_markets.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `marketId` | string | ✅ |  | Market ID (bytes32 hex, e.g. '0xabc...') |
| `network` | string | — |  | Network. Default: mainnet |

## JustLend V2 (Moolah) — Mining, Rewards & Estimator (5)

### `get_moolah_vault_mining_apy`

**Get Moolah Vault Mining APY**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get V2 mining APY for a single Moolah vault. Returns the USDD / TRX APY split and total (encoded as a fraction, e.g. 0.123 = 12.3%). enabled=true means the vault is active in mining and qualifies for the fire-icon UI hint.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `vaultAddress` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | Vault contract address (Base58 T...) |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_mining_resolver`

**Get Moolah Mining Resolver**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Map every Moolah vault with active mining to its USDD / TRX APY split. Used by the dashboard to prefetch fire-icon eligibility in one round-trip. Vaults with zero mining APY are excluded from the response.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_mining_accruing`

**Get Moolah Mining Accruing**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's accruing & settling V2 mining rewards across vaults. accruingUsd = current round still emitting; settlingUsd = previous round in the brief settlement window (miningStatus=2, currRewardStatus=1) — excluded otherwise so it doesn't double-count with already-published merkle airdrops. globalSettlementStatus=true means the backend reports any token in flux; treat per-token amounts as provisional.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_moolah_pending_mining_periods`

**Get Moolah Pending Mining Periods**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's claimable V2 mining airdrop rounds (already settled and merkle-published). Each period includes merkleIndex, index, per-token amounts (raw + decimal-shifted), the merkle proof, and a USD total. Feed a periodKey directly into claim_moolah_mining_period to submit the on-chain multiClaim. Set includeClaimed=true to also return rounds the indexer marks as already claimed (default false matches the rewards card behaviour).
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | TRON address. Default: configured wallet |
| `includeClaimed` | boolean | — |  | Include rounds the backend marks as claimed. Default: false |
| `network` | string | — |  | Network. Default: mainnet |

### `claim_moolah_mining_period`

**Claim Moolah Mining Period**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Claim a single V2 mining airdrop round via multiClaim() on the Moolah merkle distributor. Pass periodKey from get_moolah_pending_mining_periods (preferred) or supply merkleIndex / index / amounts / proof directly. Pre-checks isClaimed() and merkleRoots() on-chain so the wallet does not pay gas for a guaranteed-revert tx. Mainnet currently errors with 'distributor not configured' until the V2 contract ships — nile testnet works.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `periodKey` | string | — |  | Round key from get_moolah_pending_mining_periods (preferred) |
| `merkleIndex` | union | — |  | Override: merkle tree index |
| `index` | union | — |  | Override: leaf index inside the tree |
| `amounts` | string[] | — |  | Override: token amounts in raw units (integer strings), slot-aligned with the tree's tokenAddress[] |
| `proof` | string[] | — |  | Override: merkle proof (bytes32[]) |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Owner address used to refetch the airdrop entry when periodKey is supplied. Default: signing wallet |
| `network` | string | — |  | Network. Default: mainnet |

## Historical Records (7)

### `get_lending_records`

**Get V1 Lending Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's V1 JustLend transaction history: supply, withdraw, borrow, repay, and collateral enable/disable. Paginated. Each record includes actionType (1-11), actionName (human-readable), token, amount, USD value, and txId. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address (T...). Default: configured wallet |
| `page` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

### `get_strx_records`

**Get sTRX Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's sTRX staking history: stake, unstake, withdraw (after unbonding), and sTRX transfers. Each record has opType (1-6) and a human-readable opName. Paginated. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address. Default: configured wallet |
| `page` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

### `get_vote_records`

**Get Vote Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's governance voting history: get_vote (JST → WJST deposits), votes cast for/against proposals, vote withdrawals, and JST conversions back. Each record has opType (1-6), opName, amount, and proposalId (for votes and withdrawals). Use get_user_vote_status for real-time current voting power. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address. Default: configured wallet |
| `page` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

### `get_energy_rental_records`

**Get Energy Rental Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's JustLend energy-rental history: rent, extend, rent_more, end, recycle actions. Distinct from get_user_energy_rental_orders which returns current active on-chain orders — this one returns the full historical action log. Paginated. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address. Default: configured wallet |
| `page` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

### `get_claimable_rewards`

**Get Claimable Rewards**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Scan all JustLend V1 merkle airdrop distributors for a user's unclaimed rewards. Returns a map keyed by round; each entry includes the merkleIndex, index, amount(s), token symbol/address, and proof. Feed any returned key into claim_v1_mining_period to submit the on-chain multiClaim. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address. Default: configured wallet |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

### `claim_v1_mining_period`

**Claim V1 Mining Period**
- **Side effect**: 🔴 On-chain write · high-risk (Remote Write / Destructive) — signs and broadcasts a TRON transaction moving real assets; the client MUST require human confirmation (HITL) before executing
- **annotations**: idempotent: false · openWorld: true
- **Description**: Claim a single V1 mining airdrop round via multiClaim() on the appropriate merkle distributor. Pass `key` from get_claimable_rewards (preferred) or supply merkleIndex / index / amount / proof directly. Routing matches the front-app: amount[] → multi-merkle distributor (multi-token leaf); single + USDD → USDDNEW distributor; single + other → main distributor. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `key` | string | — |  | Round key from get_claimable_rewards (preferred) |
| `merkleIndex` | union | — |  | Override: merkle tree index |
| `index` | union | — |  | Override: leaf index inside the tree |
| `amount` | union | — |  | Override: token amount(s) in raw units (integer strings); pass an array for multi-token leaves |
| `proof` | string[] | — |  | Override: merkle proof (bytes32[]) |
| `tokenAddress` | union | — |  | Override: token address(es) used for routing when the entry is single-token |
| `tokenSymbol` | union | — |  | Override: token symbol(s); useful when tokenAddress is missing |
| `distributor` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Force a specific distributor address. Set with `selector` to bypass routing. |
| `selector` | enum(single | multi) | — |  | Force a selector. 'single' = (uint256,uint256,uint256,bytes32[])[]; 'multi' = (uint256,uint256,uint256[],bytes32[])[] |
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | — |  | Owner address used to refetch the airdrop entry when key is supplied. Default: signing wallet |
| `network` | string | — |  | Network. Default: mainnet |

### `get_liquidation_records`

**Get V1 Liquidation Records**
- **Side effect**: 🟢 Read-only (Safe / Network Read)
- **annotations**: idempotent: true · openWorld: true
- **Description**: Get a user's V1 JustLend liquidation history — both positions the user liquidated and positions where the user was liquidated. Distinct from get_moolah_liquidation_records which covers V2 Moolah liquidations. Paginated. Mainnet-only.
- **Output schema**: common structured envelope v1.0.0 (`schemaVersion`, `tool`, `result`)

| Param | Type | Required | Default | Description |
|-------|------|:--------:|---------|-------------|
| `address` | string (pattern /^T[1-9A-HJ-NP-Za-km-z]{33}$/) | ✅ |  | TRON address. Default: configured wallet |
| `page` | number | — |  | Page number, 1-indexed. Default: 1 |
| `pageSize` | number | — |  | Records per page. Default: 20 |
| `network` | string | — |  | Must be 'mainnet'. Default: mainnet |

---

_Auto-generated — do not edit by hand. Generator: `scripts/gen-mcp-api-list.ts`. Regenerate: `npx tsx scripts/gen-mcp-api-list.ts`._