JustLend DAO API¶

Public REST endpoints for querying JustLend DAO protocol state: lending markets, user positions, liquidation risk, USDD supply‑mining rewards, sTRX staking, and Energy Rental.

Contents¶

This page is the human-readable reference. The OpenAPI 3.1 YAML is the machine-readable contract — treat the YAML as authoritative if they ever diverge.

• Quick start — connectivity check + minimal response example.
• §1 Conventions — response envelope, address format, numeric formats, rate / APY semantics, pagination, error responses, rate limits, versioning.
• §2 jToken Address Reference — the 23-market table with status: active|legacy and the programmatic-filter tip.
• §3 Supply & Borrow Market endpoints — /lend/jtoken, /lend/account, /justlend/liquidate/highRiskAccountList.
• §4 USDD Supply Mining — /mining/reward, /mining/apy, /mining/distributions.
• §5 Staked TRX & Energy Rental — /lend/strx, /lend/strxStake/account, /lend/rentResource/account.
• §6 Quick reference for AI agents — common end-to-end recipes.
• §7 Interactive API Explorer — embedded Swagger UI.
• §8 Event-stream and indexing options — how to query historical Mint / Borrow / Repay events on TRON.

For gotchas while using these endpoints (USDT-style approve race, decimals mismatch, close-factor cap, etc.), see Common Pitfalls. For precise term definitions, see the Glossary.

• Base URL: https://openapi.just.network
• Method: All endpoints are GET. No authentication.
• Content‑Type: application/json
• Machine‑readable spec: justlend_apis.yaml (OpenAPI 3.1). Importable into Swagger UI, Postman, Insomnia, or any LLM tool.
• Rate limits: The public service is unauthenticated and may throttle abusive traffic. Keep pageSize <= 1000, cache stable metadata such as jToken lists, and retry 429 / 5xx responses with exponential backoff.

Quick start¶

Run this read-only request to verify connectivity and inspect the current JustLend market list:

curl -sS https://openapi.just.network/lend/jtoken

Expected result (one token shown in full; real response has ~23 entries with the same shape):

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "tokenList": [
      {
        "address":              "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
        "symbol":               "jTRX",
        "underlyingAddress":    "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
        "underlyingSymbol":     "TRX",
        "underlyingDecimal":    6,
        "underlyingPriceInTrx": 1.0,
        "underlyingPriceInUsd": 0.21,
        "borrowIndex":          1224530412174750380,
        "borrowRate":           0.064673716541040000,
        "supplyRate":           0.009044500002192000,
        "apy":                  0.000000000000000000,
        "cash":                 349909392.537020000000000000,
        "totalSupply":          12345678901234,
        "totalBorrows":         123456789.012345,
        "reserveFactor":        0.20,
        "collateralFactor":     0.75,
        "exchangeRate":         200345678901234567890000000
      }
      /* ... 22 more entries ... */
    ]
  }
}

Units cheat-sheet for the response above (see §1.3 and §1.4 for the full table):

• borrowRate, supplyRate, apy, collateralFactor, reserveFactor — annualized / fractional decimals. Multiply by 100 for percent. See §1.4 Rate / APY semantics for the full table.
• cash, totalBorrows — already de-scaled by the underlying's decimals. Use as-is.
• totalSupply — jToken units (always 8 decimals).
• borrowIndex, exchangeRate — mantissa-scaled by 1e18 (see Glossary → mantissa).

For integrations, import the OpenAPI schema from apis/justlend_apis.yaml, then start with GET /lend/jtoken for market metadata and GET /lend/account?addresses={wallet} for a user's positions.

1. Conventions¶

These conventions apply to every response unless an endpoint says otherwise.

1.1 Response envelope¶

Every successful response uses the same envelope:

{
  "code": 0,
  "message": "SUCCESS",
  "data": { ... }
}

1.2 Address format¶

All addresses are TRON Base58 addresses (start with T, 34 chars). Examples: TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf.

1.3 Numeric formats¶

1.4 Rate / APY semantics¶

All *Rate and apy values are annualized decimals. Multiply by 100 to get a percentage.

A user's total supply APY in a market that has mining enabled is therefore supplyRate + apy.

1.5 Pagination¶

Endpoints that accept pageNo and pageSize return:

{ "totalCount": 1234, "totalPage": 13, "list": [ ... ] }

• pageNo is 1‑based. Default = 1.
• pageSize default = 10, max = 1000.
• Invalid or out-of-range pageNo/pageSize are often silently ignored (defaults applied, 200 SUCCESS) rather than rejected — validate client-side. See §1.6 Error responses.

1.6 Error responses¶

Important for clients and AI agents: business and validation outcomes are returned with HTTP 200 and the same { code, message, data } envelope — not signalled through HTTP status codes, and not in RFC 7807 form. Branch on the body code, not the HTTP status. Only transport-level conditions (rate limiting, server faults) surface as non-200 HTTP statuses.

Business / validation errors — HTTP 200, code ≠ 0, data omitted:

{ "code": 404, "message": "interface [/lend/nonExistentXYZ] non exist" }

Transport-level statuses (the only non-200 HTTP codes to expect):

Silent parameter handling (must-know): unknown or out-of-range query parameters (e.g. pageSize=invalid, pageNo=-1) are commonly silently ignored — the service returns 200 SUCCESS with default data rather than rejecting the request. Some endpoints do return a non-zero code (e.g. {"code":1,"message":"illegal pageNo or pageSize"}), but this is not guaranteed. The API does not reliably validate inputs for you: validate parameters client-side and never assume a malformed request will fail.

This error contract reflects the live service as of 2026-06-08. A future API revision may adopt HTTP status codes and/or a structured error body; until then, treat HTTP 200 + body code as authoritative and validate inputs client-side.

1.7 Rate limits and retry¶

The public API is designed for read-only integrations and AI agents. It is not a bulk export interface.

Adaptive client policy (recommended starting point):

Start conservative and let the server tell you when to back off:

initial_rate         = 1 req/s
concurrent_max       = 2          # connections in flight
on each clean window (60 s, no 429): double initial_rate, cap at 20 req/s
on 429:
    sleep = base * (2 ** attempt) + random(0, jitter_ms)
    base = 1000 ms, max attempt = 5, max sleep = 30 s
    after 5 failed attempts in a row: halve initial_rate, reset attempt counter
on 5xx (transient):
    same exponential backoff as 429
on persistent 429 across multiple windows:
    treat the current rate as the operator's ceiling and stay below it

This policy converges to the real ceiling without ever guessing it. The 20 req/s cap is an arbitrary safety net so a buggy client doesn't spin to 1000 req/s on its own; adjust based on whatever you observe in production.

General hygiene (works regardless of the actual limit):

• Use pageSize <= 1000; this is the documented maximum for paginated endpoints.
• Cache stable reference data such as jToken addresses, symbols, decimals, and collateral factors (TTL ≥ 5 min is safe; these change only via governance).
• Avoid tight polling loops. Market dashboards normally do not need sub-second refreshes; a 30-second refresh is plenty.
• For per-account health monitoring across many addresses, batch via the high-risk endpoint (/justlend/liquidate/highRiskAccountList) rather than polling /lend/account per address.
• If you need sustained high-volume traffic, contact the JustLend team before production launch (the public service is unauthenticated and has no per-key tier).

1.8 Versioning and compatibility¶

The OpenAPI info.version is the documentation schema version. The HTTP API is read-only and backward-compatible unless an endpoint or field is explicitly marked otherwise.

• Existing fields may be extended with new optional fields. Clients should ignore unknown fields.
• Field removals, type changes, or semantic changes require a documentation version update and deprecation note before rollout.
• Legacy fields can remain documented for compatibility. For example, reserse is preserved as returned by the service and should be read as reserves.
• When the rendered page and OpenAPI YAML differ, treat apis/justlend_apis.yaml as the source of truth for request and response shapes.

2. jToken Address Reference¶

Several endpoints key their payloads by jToken address (e.g. data["TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf"]). Use this table to translate.

The protocol currently exposes 17 active + 6 legacy = 23 markets. Legacy markets are closed to new supply and borrow — existing positions remain queryable so they can be unwound, but do not direct new deposits to them.

3. Supply & Borrow Market¶

3.1 GET /lend/jtoken — List all SBM markets¶

Returns the on‑chain state of every Supply & Borrow market: rates, total supply/borrow, exchange rates, prices, and collateral factor.

Parameters: none.

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "tokenList": [
      {
        "address":              "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
        "symbol":               "jTRX",
        "underlyingAddress":    "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
        "underlyingSymbol":     "TRX",
        "underlyingDecimal":    6,
        "underlyingPriceInTrx": 1.0,
        "borrowIndex":          1224530412174750380,
        "borrowRate":           0.064673716541040000,
        "supplyRate":           0.009044500002192000,
        "cash":                 349909392.537020000000000000,
        "reserves":             2300647.881336000000000000,
        "totalBorrows":         63951044.565948000000000000,
        "totalSupply":          39391010299.49149122,
        "exchangeRate":         0.010448063811832339,
        "collateralFactor":     0.750000000000000000,
        "reserveFactor":        0.100000000000000000
      }
    ]
  }
}

Field reference

3.2 GET /lend/account — User SBM positions¶

Returns each queried wallet's supply/borrow positions, health factor and totals.

Parameters

Example request

GET /lend/account?addresses=T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb,TXJgM...&pageNo=1&pageSize=20

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "totalCount": 1,
    "totalPage": 1,
    "list": [
      {
        "addresses":                 "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
        "health":                    5.88,
        "totalCollateralValueInTrx": 24.126681,
        "totalBorrowValueInTrx":     11.277370,
        "liquidateStatusStartTime":  null,
        "tokens": [
          {
            "address":                "TNSBA6KvSvMoTqQcEgpVK7VhHT3z7wifxy",
            "underlyingSymbol":       "USDD",
            "entered":                1,
            "supplyBalanceJtoken":    1.09062037,
            "supplyBalanceUnderlying":0.01148891329334797277745383,
            "borrowBalanceUnderlying":0.704372293431165977793198
          }
        ]
      }
    ]
  }
}

Field reference

3.3 GET /justlend/liquidate/highRiskAccountList — High‑risk accounts¶

Returns accounts that are currently liquidatable or close to it. Use this to drive liquidation bots.

Parameters: none.

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "updateTime": 1770275708508,
    "jtokens": [ { "jUSDD": "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf", "jTRX": "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP", "...": "..." } ],
    "accounts": [
      {
        "borrower":                "TLc34aTvy1vBFzLvM9oz36ihhb7sVpQmgQ",
        "risk":                    "1.105684",
        "totalCollateralUsd":      "234.063780",
        "totalBorrowUsd":          "193.705172",
        "liquidateStatusStartTime":1770089973150,
        "collateralTokenList": [
          {
            "jtokenAddress":    "TR7BUFRQeq1w5jAZf1FKx85SHuX6PfMqsV",
            "symbol":           "jETH",
            "amount":           "11.03049909",
            "price":            "21.090028146702653201",
            "valueUsd":         "232.633536",
            "exchangeRate":     "0.010021847796289808",
            "collateralFactor": "0.750000000000000000"
          }
        ],
        "borrowTokenList": [
          {
            "tokenAddress":     "TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9",
            "symbol":           "JST",
            "amount":           "19.357667866419444238",
            "price":            "0.040802750477000000",
            "valueUsd":         "0.789846",
            "exchangeRate":     "0.010481635809265784",
            "collateralFactor": "0.600000000000000000"
          }
        ]
      }
    ]
  }
}

Field reference

4. USDD Supply Mining¶

JustLend rewards users who supply into the USDD market (jUSDD = TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf) with extra USDD. Rewards are distributed in time‑bounded phases (cycles); each phase publishes a Merkle root, and users claim by submitting their (index, amount, proof) to the on‑chain claim contract.

Reward = supplied‑USDD × apy × time_in_phase. Once a phase ends, the API exposes per‑user Merkle proofs the user submits on‑chain to claim accrued USDD.

4.1 GET /mining/apy — Mining APY per market¶

Returns the current USDD mining APY for every market that has supply‑mining enabled.

Parameters: none.

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf": {
      "USDD": 0.09175706
    }
  }
}

Field reference

If a market is missing from the response, mining is not active there. If USDD is 0, mining is paused / waiting for the next phase.

Worked example

A user supplies 1,000 USDD into jUSDD. With supplyRate = 0.012 and apy = 0.09175706:

• Base supply yield: 1000 × 0.012 = 12 USDD / year
• Mining bonus: 1000 × 0.09175706 = 91.76 USDD / year
• Combined: ~103.76 USDD / year (≈ 10.38 % total APY)

4.2 GET /mining/reward — Current phase status for a user¶

Returns the active and previous mining phase for the given user, per market.

Parameters

Example request

GET /mining/reward?address=T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf": {
      "currPhase":         64,
      "currStartTime":     "2026-05-12T00:00:00Z",
      "currEndTime":       "2026-05-19T00:00:00Z",
      "currReward":        0.0000,
      "currRewardStatus":  1,
      "lastStartTime":     "2026-05-05T00:00:00Z",
      "lastEndTime":       "2026-05-12T00:00:00Z",
      "lastReward":        0.0000,
      "lastRewardStatus":  2,
      "price":             1.000000000000000000
    }
  }
}

Field reference

4.3 GET /mining/distributions — Claim proofs for all phases¶

Returns every mining phase the user has ever been entitled to, including claimed and unclaimed phases. Each entry carries the Merkle proof needed to call the on‑chain claim function.

Parameters

Example request

GET /mining/distributions?address=T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "Phase 22": {
      "tokenAddress": "TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn",
      "claimed":      false,
      "merkleIndex":  "0x00",
      "index":        "0x0659",
      "amount":       "0x6933158b3c05",
      "merkleRoot":   "0x3fdc21ab4fed9e13714fa852ff2e659f9e32af553f4426810ff75e38ccf17a97",
      "proof": [
        "0x6b734d20b9ca2a0dda57b184789dbb6df2d2993049a9365b6eafe932cd435255",
        "0xb1c6c5a90e8c2b8e6b1aa9b2ffaef1f0a36c12c3f95dd84d96cd6f8a9b0a0a0a"
      ]
    }
  }
}

Field reference

All hex strings are bare 0x… values. Older docs may show a leading : (e.g. :0x6933158b3c05); that colon is a delimiter and is not part of the value.

Decoding amount¶

# Python
hex_amount = "0x6933158b3c05"
raw        = int(hex_amount, 16)              # 115698932195333
human_usdd = raw / 10 ** 6                    # 115698932.195333

// JS / TS — use BigInt for safety
const raw       = BigInt("0x6933158b3c05");
const humanUsdd = Number(raw) / 1e6;

Typical claim workflow¶

1. GET /mining/distributions?address={user}
2. Filter entries where claimed == false.
3. For each unclaimed phase, call the distribution contract's claim function with (merkleIndex, index, amount, proof) (the contract verifies them against the stored merkleRoot).
4. After the on‑chain transaction succeeds, the next API call returns claimed: true.

5. Staked TRX & Energy Rental¶

5.1 GET /lend/strx — sTRX market & Energy Rental snapshot¶

Returns global state for the sTRX liquid‑staking pool and the Energy Rental market.

Parameters: none.

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "stakeInfo": {
      "strxAddress":         "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5",
      "symbol":              "sTRX",
      "decimal":             18,
      "underlyingDecimal":   6,
      "exchangeRate":        1.181813870419231022,
      "supplyRate":          0.03937302,
      "totalSupply":         6553955254.250487546804870562,
      "totalUnderlying":     7745555225.580224,
      "totalSupplyUsd":      1729932328.75828661,
      "trxPrice":            0.223345167438102719,
      "reserse":             71933070.321420,
      "rentReserveFactor":   0.200000000000000000,
      "rewardReserveFactor": 0.200000000000000000
    },
    "rentInfo": {
      "rentMarketAddress":       "TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd",
      "priceFor10KEnergByRent":  0.65530713,
      "priceFor10KEnergByStake": 885.28697646,
      "priceFor10KEnergByBurn":  4.20000000,
      "totalDelegatedEnergyTrx": 162748507.908930,
      "totalDelegatedEnergyRate":0.03254970
    }
  }
}

stakeInfo field reference

rentInfo field reference

5.2 GET /lend/strxStake/account — User sTRX positions¶

Parameters

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "totalCount": 1,
    "totalPage":  1,
    "list": [
      {
        "addresses":             "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5",
        "sTRXBalance":           1.000000000000000000,
        "availableWithdrawAmount":150865439.643028,
        "unstakingAmount":       24120999.583032
      }
    ]
  }
}

5.3 GET /lend/rentResource/account — User Energy Rental positions¶

Currently only Energy rentals are exposed.

Parameters

Response data

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "totalCount": 1,
    "totalPage":  1,
    "list": [
      {
        "rentType":         "Energy",
        "renter":           "TWdWEHRLPBVGsXhwjSUv45XwnsfUHXydJa",
        "receiver":         "TWdWEHRLPBVGsXhwjSUv45XwnsfUHXydJa",
        "delegatedAmount":  10000.000000,
        "rentRemainAmount": 8500.000000,
        "rentAmountPerDay": 1500.000000
      }
    ]
  }
}

6. Quick reference for AI agents¶

If you are an LLM tool building requests against this API, follow these rules:

1. All endpoints are GET against https://openapi.just.network.
2. All responses are wrapped in {code, message, data}. Always check code == 0 before reading data.
3. Numbers are already de‑scaled — never multiply by 1e18 / 1e6 again unless explicitly told (the only exception is amount / index in /mining/distributions, which are hex uint256 in raw smallest units).
4. Rates (*Rate, apy) are annualized decimals. Multiply by 100 for %.
5. A market's effective supply APY = tokenList[i].supplyRate + (mining apy if tokenList[i].address appears in /mining/apy, else 0).
6. Address‑keyed objects — look up the jToken address in §2 to know which market a sub‑object refers to.
7. Liquidations — pull /justlend/liquidate/highRiskAccountList periodically; risk > 1 ⇒ liquidatable.
8. Mining claims — every entry of /mining/distributions with claimed == false is a free transaction the user should submit.

The machine‑readable OpenAPI 3.1 spec lives at apis/justlend_apis.yaml and stays consistent with this page.

7. Interactive API Explorer¶

Use the embedded Swagger UI below to call endpoints directly from this page. Same OpenAPI spec as the YAML link above.

8. Event-stream and indexing options¶

The HTTP API exposes current state. For historical events (every Mint, Borrow, RepayBorrow, Redeem, LiquidateBorrow, enterMarkets, governance ProposalCreated/VoteCast/ProposalExecuted, sTRX Deposit/Withdrawal, EnergyRental RentResource/ReturnResource) you need an event source.

There is currently no official JustLend subgraph or hosted indexer. Use one of these patterns instead:

8.1 TronGrid event filter (recommended for low-volume queries)¶

TronGrid exposes GET /v1/contracts/{address}/events for any contract. Filter by event_name and time range. Free tier covers most ad-hoc analytics; paid tiers raise the rate limit.

# All Mint events on jUSDT for the last hour
curl -H "TRON-PRO-API-KEY: $TRONGRID_API_KEY" \
  "https://api.trongrid.io/v1/contracts/TXJgMdjVX5dKiQaUi9QobwNxtSQaFqccvd/events?event_name=Mint&min_block_timestamp=$(($(date +%s%3N)-3600000))"

Pros: zero setup, well-documented, works for any JustLend contract. Cons: cursored pagination only, ~30-day retention on the free tier, not great for full historical backfills.

8.2 Self-hosted indexer (recommended for production analytics)¶

Stand up an indexer that consumes block ranges and writes typed event tables. TRON's EVM compatibility is partial (different signature scheme, different fee model, different address encoding) so most "EVM-indexer" tooling needs a TRON-specific datasource — verify support before adopting.

• Custom decoder against a TRON archive endpoint (most robust path). Run java-tron in archive mode, or use a TronGrid full-archive plan, and decode events with the JSON ABIs at /developers/abis/. Write your own schema; commit indices on (market, block_number) for the per-market views you need. Most operational overhead, most flexibility, no third-party dependency.
• Generic EVM indexers (DipDup, Subsquid, Substreams, Goldsky, etc.). These have evolving TRON support — some via official adapters, some via community forks, some not at all. Treat any "DipDup/Subsquid supports TRON" claim as needing verification against the project's current docs and your specific event-decoding needs. None of these are recommended without a proof-of-concept run against a TRON archive endpoint first.
• Tron-native option: TronGrid event API. §8.1 covers this; for low-to-mid volume it removes the need for a self-hosted indexer entirely.

8.3 MCP server read_events (when integrating with an AI agent)¶

For low-volume agent-driven queries, the full MCP server exposes contract read primitives that can be composed into event lookups (get_account_summary, get_market_data, etc.). For raw event log access, fall back to TronGrid via your own tooling — MCP is not optimized for historical-event sweeps.

8.4 Quick reference: event signatures by contract¶

ABIs at /developers/abis/ carry the canonical event signatures. The most commonly indexed:

Compute the topic 0 with any standard tool: web3.utils.sha3('Mint(address,uint256,uint256)'). Avoid hard-coding topic hashes in source — derive from the JSON ABIs at runtime, since event signatures could change in a future upgrade.