JustLend DAO API¶

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

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 24-market table with status: active|legacy and the programmatic-filter tip.
• §3 Supply & Borrow Market endpoints — /lend/jtoken, /lend/account, /justlend/liquidate/highRiskAccountList, plus the V2 (Moolah) read endpoints /v2/index/vault/list, /v2/index/market/list, /v2/index/position, /v2/vault/position, /v2/market/position (§3.4).
• §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
• JSON compliance: Level 2 — uniform {code, message, data} envelope on every endpoint (§1.1), machine-validatable schemas (typed fields + required arrays + x-unit/x-decimals extensions) in the OpenAPI YAML, and a documented compatibility policy (§1.8).
• Machine‑readable spec: justlend_apis.yaml (OpenAPI 3.1). Importable into Swagger UI, Postman, Insomnia, or any LLM tool.
• Live verification: the endpoints on this page are exercised end-to-end in the agent acceptance run (runnable via node scripts/api-acceptance.mjs).
• 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 — a real response captured 2026-07-15; the live response has 24 entries with the same shape):

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "tokenList": [
      {
        "address":              "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
        "symbol":               "jTRX",
        "underlyingSymbol":     "TRX",
        "underlyingAddress":    "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
        "underlyingPriceInTrx": "1.000000000000000000000000000",
        "underlyingDecimal":    6,
        "reserveFactor":        "0.100000000000000000",
        "collateralFactor":     "0.750000000000000000",
        "supplyRate":           "0.004196584241280000",
        "borrowRate":           "0.047954914361424000",
        "exchangeRate":         "0.010582523128618106",
        "cash":                 "2021157853.515481000000000000",
        "totalBorrows":         "217298348.792278000000000000",
        "totalSupply":          "211176098544.66409163",
        "reserves":             "3680255.247515000000000000",
        "borrowIndex":          "1361223278609682980"
      }
      /* ... 23 more entries ... */
    ]
  }
}

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

• All decimal quantities are JSON strings — parse with arbitrary-precision decimal/BigInt tooling, never IEEE-754 floats.
• borrowRate, supplyRate, collateralFactor, reserveFactor — annualized / fractional decimals. Multiply by 100 for percent. (The USDD mining apy is served separately by /mining/apy, see §4.1.) See §1.4 Rate / APY semantics for the full table.
• cash, totalBorrows, reserves — already de-scaled by the underlying's decimals. Use as-is.
• totalSupply — jToken units (always 8 decimals).
• borrowIndex — cumulative interest index, scaled by 1e18; exceeds 2^53, so keep it a string/BigInt (see Glossary → mantissa).
• exchangeRate — de-scaled jToken → underlying ratio (human underlying per human jToken), not the raw on-chain 1e18 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 response — success and business error — uses the same {code, message, data} envelope. The success code differs between the two API generations:

V1 endpoints (/lend/..., /mining/..., /justlend/...):

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

V2 endpoints (/v2/...):

{
  "code": 200,
  "message": "Success",
  "data": { ... },
  "timestamp": 1784101532272
}

JSON compliance: Level 2. Uniform envelope on every endpoint, machine-validatable response schemas (typed fields, required arrays, x-unit / x-decimals / x-format extensions) in justlend_apis.yaml, and a documented compatibility policy (§1.8).

Field necessity (必返性). Every field documented for a data schema is always returned (required) unless it is explicitly marked nullable or optional — a nullable field is still always present but its value may be null (e.g. liquidateStatusStartTime, or the V2 user-scoped fields when no address is supplied). The machine-readable required arrays in justlend_apis.yaml enumerate these per schema, so an agent can distinguish "field missing = bug/unexpected" from "value null = documented empty state" and validate responses programmatically. The per-endpoint tables below carry the same information in their Required column.

1.2 Address format¶

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

1.3 Numeric formats¶

All decimal quantities (amounts, rates, prices, indexes) are serialized as JSON strings — on V1 and V2 alike. Parse them with arbitrary-precision decimal / BigInt tooling, never IEEE-754 floats (many values carry more than 15 significant digits; borrowIndex and V2 share amounts exceed 2^53). Counts, flags and token decimals are plain JSON integers, with two quirks: /lend/strx serializes decimal / underlyingDecimal as strings ("18", "6"), and /mining/reward serializes currPhase and the status enums as strings.

The OpenAPI YAML makes the unit and scale machine-readable: amount / rate / price / time fields carry an x-unit extension (plus x-decimals where the scale is fixed, and x-format for hex or non-RFC time layouts).

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.

V1 business / validation errors — HTTP 200, code ≠ 0, data omitted (real response, captured 2026-07-15):

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

V2 business / validation errors — HTTP 200, code ≠ 200, data: null (real response, captured 2026-07-15):

{ "code": 202, "message": "error: Invalid value for field 'address': Invalid format; error: Invalid value for field 'vaultAddress': Invalid format", "data": null, "timestamp": 1784101590046 }

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"}, or {"code":1,"message":"Required request parameter 'addr' ... is not present"} when a required parameter is missing), 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 verified on 2026-07-15 (see the agent acceptance run). 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.
• The service itself occasionally renames keys without notice — observed examples: stakeInfo.reserse (typo) became reserves, and the per-account key in /lend/account / /lend/strxStake/account responses is address (older captures showed addresses). Where this happened, this page documents the current key and notes the historical one; defensive clients may accept both.
• 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 18 active + 6 legacy = 24 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 (real response captured 2026-07-15; one of 24 entries shown)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "tokenList": [
      {
        "address":              "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
        "symbol":               "jTRX",
        "underlyingSymbol":     "TRX",
        "underlyingAddress":    "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
        "underlyingPriceInTrx": "1.000000000000000000000000000",
        "underlyingDecimal":    6,
        "reserveFactor":        "0.100000000000000000",
        "collateralFactor":     "0.750000000000000000",
        "supplyRate":           "0.004196584241280000",
        "borrowRate":           "0.047954914361424000",
        "exchangeRate":         "0.010582523128618106",
        "cash":                 "2021157853.515481000000000000",
        "totalBorrows":         "217298348.792278000000000000",
        "totalSupply":          "211176098544.66409163",
        "reserves":             "3680255.247515000000000000",
        "borrowIndex":          "1361223278609682980"
      }
    ]
  }
}

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 (real response captured 2026-07-15)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "totalPage": 1,
    "totalCount": 1,
    "list": [
      {
        "address":                   "TB2e78zyzMnaNG2GRazazmbVVv3J564YHg",
        "health":                    "1.00000595",
        "totalBorrowValueInTrx":     "41630.103606",
        "totalCollateralValueInTrx": "41630.351383",
        "liquidateStatusStartTime":  null,
        "tokens": [
          {
            "address":                "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
            "underlyingSymbol":       "TRX",
            "entered":                1,
            "borrowBalanceUnderlying":"41630.103606391458272468557875",
            "supplyBalanceUnderlying":"55507.13517729334283172067476560",
            "supplyBalanceJtoken":    "5245170.10164455"
          }
        ]
      }
    ]
  }
}

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 (real response captured 2026-07-15; jtokens truncated to 2 of 24 keys, accounts to 1 of 85 entries)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "jtokens": {
      "jTRX":  "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
      "jUSDD": "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf"
      /* ... one key per market, 24 total ... */
    },
    "updateTime": 1784101473987,
    "accounts": [
      {
        "borrower":                "TB2e78zyzMnaNG2GRazazmbVVv3J564YHg",
        "collateralTokenList": [
          {
            "jtokenAddress":    "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP",
            "amount":           "5245170.10164455",
            "price":            "0.003436452181842813",
            "valueUsd":         "18024.776240",
            "symbol":           "jTRX",
            "exchangeRate":     "0.010582523217337573",
            "collateralFactor": "0.750000000000000000"
          }
        ],
        "borrowTokenList": [
          {
            "tokenAddress":     "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb",
            "amount":           "41630.094680465196950370956875",
            "price":            "0.324729000000000000",
            "valueUsd":         "13518.499015",
            "symbol":           "TRX",
            "exchangeRate":     "0.010582523217337573",
            "collateralFactor": "0.750000000000000000"
          }
        ],
        "totalCollateralUsd":      "18024.776240",
        "totalBorrowUsd":          "13518.499015",
        "risk":                    "0.999994",
        "liquidateStatusStartTime": 0
      }
    ]
  }
}

Note: jtokens is a plain JSON object (symbol → address map). Older revisions of this page showed it wrapped in a one-element array — that was a documentation error.

Field reference

3.4 JustLend V2 (Moolah) read endpoints¶

JustLend V2 ("Moolah", Morpho-style architecture — see JustLend V2) exposes ERC-4626 vaults (passive supply, allocated across markets) and isolated markets (one collateral / one loan token pair, identified by a 32-byte hex id). Five anonymous read endpoints cover them.

V2 conventions (differ from V1 — see §1.1 / §1.6):

• Success is code: 200 with message: "Success" (V1 uses code: 0 / "SUCCESS").
• Business errors are still HTTP 200, with code ≠ 200 (e.g. 202 = invalid parameters) and data: null.
• Every response carries a top-level timestamp (epoch ms).
• All decimal quantities are strings; shareAmount / borrowShares are raw base-unit integer strings that can exceed 2^53 (use BigInt).
• User-scoped fields (ltv, risk, loanAmount, userSupplyUsd, …) are null when no address is supplied or the user has no position.

3.4.1 GET /v2/index/vault/list — All V2 vaults¶

Returns every V2 vault (name, asset, TVL, APY, performance fee, eligible collateral, underlying market allocations), plus the user's vaults when address is given.

Parameters

Response data (real response captured 2026-07-15, heavily truncated — full sub-schemas in the YAML)

{
  "code": 200,
  "message": "Success",
  "data": {
    "userVaults": { "totalCount": 0, "list": [] },
    "allVaults": {
      "totalCount": 3,
      "list": [
        {
          "chain":             "tron",
          "vaultAddress":      "TXejU9jmd1ooQyY3Zmpo15yN7MjSFYUESg",
          "vaultName":         "JustLend USDT Vault",
          "vaultSymbol":       "jUSDTv2",
          "icon":              "https://static.tronscan.org/production/logo/usdtlogo.png",
          "tags":              [],
          "assetAddress":      "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "assetSymbol":       "USDT",
          "assetName":         "Tether USD",
          "assetDecimals":     6,
          "assetIcon":         "https://static.tronscan.org/production/logo/usdtlogo.png",
          "totalSupplyAmount": "413328.006113",
          "tvl":               "413328.006113000000000000",
          "apy":               "0.000711770302729251",
          "performanceFee":    "10.00",
          "collateralTokens":  [ { "address": "TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR", "symbol": "WTRX", "name": "Wrapped TRX", "decimals": 6, "icon": "…" } /* ... */ ],
          "markets":           [ { "id": "0x8fa76896548f751c9009583976933e6cb355513a180548df5d47b1833d20cb17", "collateralSymbol": "USDD", "totalSupplyAssets": "113259.328861", "borrowSymbol": "USDT", "...": "..." } /* ... */ ],
          "userSupplyUsd":     null,
          "userSupplyAmount":  null,
          "allocations":       [ { "marketId": "0x8fa768…", "collateralSymbol": "USDD", "amount": "113259.286496", "percentage": "27.401793449548277509", "supplyQueueIndex": 0, "isNew": 0, "noMoreAllocation": false } /* ... */ ]
        }
        /* ... 2 more vaults ... */
      ]
    },
    "depositTokens":    [ { "address": "…", "symbol": "USDT", "name": "Tether USD", "decimals": 6, "icon": "…" } /* ... */ ],
    "collateralTokens": [ { "address": "…", "symbol": "WTRX", "name": "Wrapped TRX", "decimals": 6, "icon": "…" } /* ... */ ]
  },
  "timestamp": 1784101532272
}

Field reference (vault entry)

3.4.2 GET /v2/index/market/list — All V2 isolated markets¶

Returns every V2 isolated market (loan/collateral pair, LLTV, liquidity, borrow rate), plus the user's markets when address is given. Accepts the same query parameters as §3.4.1 (address, sort, order, deposit, collateral, keyword, userPage, userPageSize, allPage, allPageSize).

Response data (real response captured 2026-07-15, truncated to one of 9 markets)

{
  "code": 200,
  "message": "Success",
  "data": {
    "userMarketsCount": 0,
    "allMarketsCount":  9,
    "userMarkets":      [],
    "allMarkets": [
      {
        "id":                 "0x8fa76896548f751c9009583976933e6cb355513a180548df5d47b1833d20cb17",
        "ltv":                null,
        "lltv":               "0.800000000000000000",
        "risk":               null,
        "liquidity":          "113190.228074",
        "liquidityUsd":       "113190.228074000000000000",
        "loanSymbol":         "USDT",
        "loanAddress":        "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "loanAmount":         null,
        "loanUsd":            null,
        "loanIcon":           "https://static.tronscan.org/production/logo/usdtlogo.png",
        "borrowRate":         "0.000250508418242629",
        "collateralSymbol":   "USDD",
        "collateralAddress":  "TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz",
        "collateralAmount":   null,
        "collateralUsd":      null,
        "collateralDecimals": 18,
        "collateralIcon":     "https://static.tronscan.org/production/upload/logo/new/TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz.png",
        "tags":               []
      }
      /* ... 8 more markets ... */
    ]
  },
  "timestamp": 1784101532797
}

Field reference (market entry)

3.4.3 GET /v2/index/position — User V2 portfolio summary¶

Aggregated V2 position for one wallet: totals, net rates, mining rewards, and the per-vault / per-market breakdown.

Parameters

Example request

GET /v2/index/position?address=TB2e78zyzMnaNG2GRazazmbVVv3J564YHg

Response data (real response captured 2026-07-15 — this wallet has no V2 positions, so totals are zero and the breakdown arrays are empty)

{
  "code": 200,
  "message": "Success",
  "data": {
    "totalBorrowUsd":        "0.000000000000000000",
    "totalCollateralUsd":    "0.000000000000000000",
    "totalSupplyUsd":        "0",
    "netEarnApy":            "0",
    "netBorrowRate":         "0",
    "dailyRevenue":          "0.000000000000000000",
    "dailyMiningReward":     "0.000000000000000000",
    "dailyMiningRewardUsdd": "0.000000000000000000",
    "dailyMiningRewardTrx":  "0.000000",
    "collateralCount":       0,
    "markets":               [],
    "vaults":                [],
    "borrowNew":             true,
    "vaultNew":              true
  },
  "timestamp": 1784101588616
}

Field reference

3.4.4 GET /v2/vault/position — User position in one vault¶

Parameters

Example request

GET /v2/vault/position?vaultAddress=TXejU9jmd1ooQyY3Zmpo15yN7MjSFYUESg&address=TB2e78zyzMnaNG2GRazazmbVVv3J564YHg

Response data (real response captured 2026-07-15 — wallet without a position in this vault; apy is still the live vault APY)

{
  "code": 200,
  "message": "Success",
  "data": {
    "shareAmount":             "0",
    "depositAmount":           "0.000000",
    "depositUsd":              "0.000000000000000000",
    "apy":                     "0.000711758741868661",
    "dailyInterest":           "0.000000000000000000",
    "dailyInterestAmount":     "0.000000",
    "farmRewardUsddAmount24h": "0",
    "farmRewardTrxAmount24h":  "0"
  },
  "timestamp": 1784101589078
}

Field reference

3.4.5 GET /v2/market/position — User position in one market¶

Parameters

Example request

GET /v2/market/position?market=0x8fa76896548f751c9009583976933e6cb355513a180548df5d47b1833d20cb17&address=TB2e78zyzMnaNG2GRazazmbVVv3J564YHg

Response data (real response captured 2026-07-15 — wallet without a position in this market; token metadata, lltv and borrowApy are live market values)

{
  "code": 200,
  "message": "Success",
  "data": {
    "borrowAddress":     "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "borrowSymbol":      "USDT",
    "borrowAmount":      "0",
    "borrowShares":      "0",
    "borrowUsd":         "0.000000000000000000",
    "collateralAddress": "TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz",
    "collateralSymbol":  "USDD",
    "collateralUsd":     "0.000000000000000000",
    "collateralAmount":  "0",
    "borrowApy":         "0.000250508418242629",
    "ltv":               "0.000000000000000000",
    "lltv":              "0.800000000000000000",
    "risk":              "0.000000000000000000",
    "dailyInterest":     "0"
  },
  "timestamp": 1784101589588
}

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 (real response captured 2026-07-15, truncated to 2 of 24 market keys)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf": {
      "USDD": "0.04275429"
    },
    "TE2RzoSV3wFK99w6J9UnnZ4vLfXYoxvRwP": {
      "USDD": "0.00000000"
    }
    /* ... one key per market, 24 total ... */
  }
}

Field reference

A market with "0.00000000" (or missing from the response) has no active mining — it is paused or waiting for the next phase. Only markets with a non-zero value pay the bonus.

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 (real response captured 2026-07-15 — note the payload is keyed by market address, then by reward-token symbol, currently USDD)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "TKFRELGGoRgiayhwJTNNLqCNjFoLBh3Mnf": {
      "USDD": {
        "currPhase":         "120",
        "currStartTime":     "2026-07-11 20:00",
        "currEndTime":       "2026-07-18 20:00",
        "currReward":        "0.000000000000000000",
        "currRewardStatus":  "1",
        "lastStartTime":     "2026-07-04 20:00",
        "lastEndTime":       "2026-07-11 20:00",
        "lastReward":        "0",
        "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?addr=TB2e78zyzMnaNG2GRazazmbVVv3J564YHg

Response data (real response captured 2026-07-15, truncated to 1 of 10 phases and 2 proof elements — note the keys are bare phase numbers, e.g. "22")

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "22": {
      "tokenAddress": "TPYmHEhy5n8TCEfYGqW2rPxsghSfzghPDn",
      "tokenSymbol":  "USDDOLD",
      "claimed":      false,
      "merkleIndex":  "0x00",
      "index":        "0x04b6",
      "amount":       "0x40086576c6adc75c",
      "merkleRoot":   "0x3fdc21ab4fed9e13714fa852ff2e659f9e32af553f4426810ff75e38ccf17a97",
      "proof": [
        "0x00ffb450e721c910fc2b305b1184ddc9e8fe6c014cb514ac6753c2bddd3e68c2",
        "0x7e31527db07b9a464e5467853ef325426d3d4cae8b180638cb8dfb32e60e7ff5"
      ],
      "prices":       "1"
    }
  }
}

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¶

amount is in the reward token's smallest units. Fetch the token's decimals (from contracts.json or the TRC20 contract) — USDD and USDDOLD both have 18:

# Python
hex_amount = "0x40086576c6adc75c"
raw        = int(hex_amount, 16)              # 4614192507070891868
human_usdd = raw / 10 ** 18                   # 4.614192507070892 (USDDOLD has 18 decimals)

// JS / TS — use BigInt for safety
const raw       = BigInt("0x40086576c6adc75c");
const humanUsdd = Number(raw) / 1e18;         // token decimals = 18 for USDD / USDDOLD

Typical claim workflow¶

1. GET /mining/distributions?addr={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 (real response captured 2026-07-15)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "stakeInfo": {
      "strxAddress":         "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5",
      "symbol":              "sTRX",
      "decimal":             "18",
      "totalSupply":         "7416931940.940514882265682812",
      "totalSupplyUsd":      "3173929709.88356922",
      "exchangeRate":        "1.306200515551643308",
      "totalUnderlying":     "9688000325.067951",
      "underlyingDecimal":   "6",
      "rentReserveFactor":   "0.200000000000000000",
      "rewardReserveFactor": "0.200000000000000000",
      "reserves":            "290201700.064348",
      "supplyRate":          "0.03162947",
      "trxPrice":            "0.327614533793000000"
    },
    "rentInfo": {
      "rentMarketAddress":       "TU2MJ5Veik1LRAgjeSzEdvmDYx7mefJZvd",
      "priceFor10KEnergByRent":  "0.44835366",
      "priceFor10KEnergByStake": "1053.43779485",
      "priceFor10KEnergByBurn":  "1.00000000",
      "totalDelegatedEnergyTrx": "506918969.020237",
      "totalDelegatedEnergyRate":"0.10138379"
    }
  }
}

stakeInfo field reference

rentInfo field reference

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

Parameters

Response data (real response captured 2026-07-15)

{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "totalPage":  1,
    "totalCount": 1,
    "list": [
      {
        "address":                 "TU3kjFuhtEo42tsCBtfYUAZxoqQ4yuSLQ5",
        "availableWithdrawAmount": "804814121.102239",
        "unstakingAmount":         "53899847.795703",
        "sTRXBalance":             "1.000000000000000000"
      }
    ]
  }
}

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

Currently only Energy rentals are exposed.

Parameters

Response data (values illustrative; decimal amounts are returned as strings, like every other endpoint)

{
  "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}. Check the success code before reading data: code == 0 on V1 endpoints, code == 200 on /v2/... endpoints (see §1.1).
3. Decimal quantities arrive as JSON strings and are already de‑scaled — parse with big-decimal/BigInt, and never multiply by 1e18 / 1e6 again unless explicitly told (the exceptions: amount / index in /mining/distributions are hex uint256 in raw smallest units; borrowIndex and the V2 shareAmount / borrowShares are raw integer strings).
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 has a non-zero value 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 (parameter addr, not address) with claimed == false is a free transaction the user should submit.
9. V2 (Moolah) — discover vaults via /v2/index/vault/list and markets via /v2/index/market/list, then read one user's positions via /v2/index/position, /v2/vault/position (by vaultAddress) and /v2/market/position (by market id). See §3.4.

The machine‑readable OpenAPI 3.1 spec lives at apis/justlend_apis.yaml. It is maintained together with this page and verified against the live service (last verified 2026-07-15 — see the agent acceptance run); if the two ever diverge, treat the YAML as authoritative (§1.8) and please report the mismatch.

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.