API reference
filecoin.plus's public read-only API: chain, network, miner, address and ranking data as JSON.
Contents
Conventions
Every endpoint is a GET at https://filecoin.plus/api/<name>/<object>; parameters may also be given as query parameters. Replies look like:
{"code": 200, "msg": "", "data": { … }}
- Amounts are attoFIL (1 FIL = 10¹⁸) and power is bytes, both as decimal strings so large numbers keep their precision.
- Heights are numbers (one every 30 seconds), times are unix seconds and dates are UTC unless noted. Unknown values are null.
- Malformed parameters: HTTP 400 with code 400 and msg naming the parameter (e.g. miner error, limit error).
- Well-formed but nothing found (e.g. a miner this site does not index, a block that does not exist): HTTP 200 with code 501 and msg giving the reason (e.g. miner error, block not found).
- Upstream failures: HTTP 502/503/504 with msg such as lotus node unavailable or service unavailable; retry later.
- Most endpoints are cached (see each one). Endpoints marked “live” query a Lotus node and have limited concurrency slots; when they are full the reply is 503. Please call them sensibly and do not poll rapidly.
- Rate limit: 5 requests per second per source IP on average, with bursts of up to 40; beyond that you get HTTP 429 (code 429, msg too many requests). Wait a moment and retry.
- This site serves curated data, not Lotus's native JSON-RPC; for the native API use a public node such as Glif:
https://api.node.glif.io/rpc/v1
curl -s https://filecoin.plus/api/minerInfo/f01518369
Chain
Latest height
The newest height this site has indexed, usually 1–2 epochs behind the live head (the live head is in /api/network).
data fields
| height | number | height (epoch) |
| timestamp | number | unix seconds |
| blocks | number | blocks at this height, 0 for a null round |
| messages | number | null | message count; null for heights backfilled from headers only |
Blocks
Blocks since genesis, orphans excluded. With miners, only those miners' blocks. Without after, the newest limit blocks, newest height first (order within a height is unspecified).
Parameters
| after | query | oldest first, only blocks above this height (not with from or page) |
| from | query | old form: only blocks above this height, newest first, default 0 |
| limit | query | 1–2000, default 500 |
| miners | query | comma-separated miner IDs, up to 50 (or miner= or /api/blocks/<miner> for one) |
| page | query | page number (limit rows a page), newest first, for a single miner only; for the network or several miners continue with after |
data fields
| cid | string | block CID |
| height | number | height |
| timestamp | number | unix seconds (from the height) |
| miner | string | the miner |
| winCount | number | wins (election win count) |
| messageCount | number | null | message count; null when only the header was backfilled |
| parentBaseFee | string | parent base fee, attoFIL |
| reward | string | null | estimated reward (the hour's network reward per win × winCount), attoFIL, tips excluded; null without reward data |
| rewardEstimated | boolean | always true |
To follow on completely (e.g. syncing blocks), use after: limit blocks with height > after, oldest first, the last height always complete (possibly a few over limit); the next page uses after=this page's last height, and fewer than limit means the end for now, so resume later from the same after. after only goes up to the height this site has indexed contiguously (at least about 10 minutes behind the head, further while backfilling after an outage), so no block is skipped.
from is the old form (the newest limit blocks above from, skipping the middle when there are more than limit); kept for compatibility, do not page with it.
Block
One block by CID. Same fields as /api/blocks plus orphan (true for orphaned blocks).
Parameters
| cidrequired | path | block CID |
Height details
A height's overview and all its blocks (this site's index, complete from genesis, orphans excluded).
Parameters
| heightrequired | path | height |
data fields
| height, timestamp | number | height, unix seconds |
| nullRound | boolean | a null round (no blocks at this height) |
| messages | number | null | deduplicated message count; null for heights backfilled from headers only |
| parentBaseFee | string | null | attoFIL |
| blocks[] | array | items as in /api/blocks |
Block details
/api/block's fields plus the header from the node: parents, parent weight, parent state root, header time. header is null when the node cannot answer right now.
Parameters
| cidrequired | path | block CID |
data fields
| cid … rewardEstimated, orphan | as in /api/block | |
| header | object | null | {timestamp, parents[], parentWeight, parentStateRoot, messages} |
Tipset
The tipset at a height. A null round returns the nearest earlier tipset with nullRound true.
Parameters
| heightrequired | path | height, not above the head |
data fields
| height | number | the actual tipset height |
| requested | number | the height asked for |
| nullRound | boolean | the height asked for was a null round |
| timestamp | number | unix seconds (block header time) |
| parentBaseFee | string | attoFIL |
| blocks[] | array | {cid, miner, winCount} |
Message result
A message's execution result, searching back 7 days. replaced is true when the message found replaced it (same nonce, higher gas).
Parameters
| cidrequired | path | message CID, or an Ethereum transaction hash (0x…) |
data fields
| cid | string | message CID (the resolved CID when asked by a 0x hash) |
| ethHash | string | null | the message's Ethereum transaction hash (every message has one; null when the node cannot tell) |
| replaced | boolean | whether it was replaced |
| foundCid | string | the message CID found |
| executedHeight | number | the tipset holding the receipt (the first tipset after inclusion) |
| exitCode | number | 0 means success |
| gasUsed | number | gas used |
| return | string | null | return value, base64 |
| returnTooLarge | boolean | true when the return value exceeds 64 KiB and return is null |
Messages older than 7 days answer 501 message not found.
Message details (decoded)
A message in full: from, to, value, gas, the method name, decoded params and the receipt. Params are decoded against the destination actor's version at execution. Searches back 7 days.
Parameters
| cidrequired | path | message CID, or an Ethereum transaction hash (0x…) |
data fields
| cid, ethHash, replaced, foundCid | as in /api/message | |
| from, to | string | the addresses as in the message |
| value | string | value, attoFIL |
| nonce, methodId | number | nonce, method number |
| method | string | null | method name (e.g. SubmitWindowedPoSt); null for Send or unknown |
| params | object | string | null | decoded params; "raw:<hex>" when not decodable; null without params |
| paramsTooLarge | boolean | true when params exceed 64 KiB and are left out |
| gasLimit, gasFeeCap, gasPremium | gas settings (the last two attoFIL strings) | |
| executedHeight, exitCode, gasUsed, return, returnTooLarge | the receipt, as in /api/message |
/api/message is the light, undecoded version.
Ethereum tx → message CID
The Filecoin message CID of an Ethereum transaction hash (for the execution result use /api/message/0x… directly).
Parameters
| hashrequired | path | 0x-prefixed 32-byte hash |
data fields
| hash | string | the hash, lower case |
| cid | string | message CID |
The node keeps messages for roughly the last 2–3 weeks; older transactions may not be found.
Network
Network overview
Live head, network power, 24-hour rewards, pledge, and power expiring, expired, extended and added over 24 hours / 7 days. Items that cannot be computed are null.
data fields
| height, timestamp | number | the live head |
| qualityAdjPower, rawBytePower | string | bytes, decimal string |
| reward24h | string | null | miner rewards over the last 2880 epochs, attoFIL |
| serviceReward24h | string | null | the service reward stream over the same span, attoFIL |
| rewardPerTiB24h | string | null | 24-hour reward per TiB QA power, attoFIL |
| blockReward | string | null | average reward per win, attoFIL |
| pledgePerTiB | string | null | initial pledge for 1 TiB of CC sectors, attoFIL |
| expiring24h, expiring7d | string | null | QA power expiring ahead, bytes |
| expired24h/7d, extended24h/7d, added24h/7d | string | null | QA power expired, extended and added, bytes |
| powerSince, addedSince | number | heights these statistics began; windows reaching earlier are incomplete |
Network expiry by month
Sector expiry of all powered miners from today (UTC) on, summed by month.
data fields
| miners | number | miners with expiry data |
| updatedFrom, updatedTo | number | oldest / newest per-miner snapshot, unix seconds |
| months[] | array | {month: YYYY-MM, sectors, rawPowerTiB, qaPowerCCTiB, qaPowerDCTiB (DC as QA ×10), pledgeCCFIL, pledgeDCFIL}, numbers; same names as /api/minerExpire |
Unit exception: monthly chart data, with power in TiB and pledge in FIL as numbers rather than byte / attoFIL strings.
powerCC, powerDC, pledgeCC and pledgeDC are the pre-rename fields (same values) and will be removed.
Miners
Miner overview
Everything at the top of the miner page: power and rank, balances, sectors, addresses, totals and the four block-statistics windows. minerAccount and minerStats combined.
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| sectorSize | string | bytes, decimal string |
| power | object | qualityAdj, raw, network (bytes), networkShare (0–1), rank |
| balance | object | null | total, available, initialPledge, vesting, preCommitDeposits, feeDebt (attoFIL); null when the node is unavailable |
| market | object | null | market escrow and locked (attoFIL) |
| sectors | object | live, active, faulty, recovering; faulty is live at the head (this site's snapshot when Lotus is unavailable) |
| addresses | object | null | owner, worker, control, beneficiary as in /api/minerAccount |
| total, blocks | object, array | total and windows as in /api/minerStats |
Block statistics
Blocks, rewards, efficiency and luck over 24 hours, 7 days, 30 days and a year, plus totals since genesis. Rewards are estimated from the network reward per win of each hour and exclude tips.
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| power, networkPower | string | bytes, decimal string |
| windows[].key | string | 24h / 7d / 30d / 1y |
| windows[].blocks, wins | number | blocks (no orphans), wins |
| windows[].reward | string | estimated rewards, attoFIL |
| windows[].efficiency | string | null | reward per TiB of current QA power, attoFIL; null without power |
| windows[].efficiencyAvgPower | string | null | reward per TiB of the window's mean QA power, attoFIL |
| windows[].luck | number | null | luck, 1 = network average |
| windows[].qaPowerDelta | string | null | QA power change over the window, bytes, may be negative |
| windows[].complete | boolean | whether reward data covers the whole window |
| total | object | blocks, wins, reward, first (first block height) |
Balances and addresses
The miner's live balances, recovering and faulty sectors, market escrow, and the Owner, Worker, Control and Beneficiary addresses with their balances.
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| balance, available, initialPledge, vesting, preCommitDeposits, feeDebt | string | attoFIL string |
| recovering | number | recovering sectors |
| faulty | number | faulty sectors (live at the head) |
| market | object | null | escrow, locked, attoFIL |
| owner, worker, beneficiary | object | {id, address, balance}; address or balance null when unknown |
| control[] | array | {id, address, balance} |
| newWorker | object | pending worker (only during a change) |
| beneficiaryTerm | object | quota, usedQuota (attoFIL), expiration (height); when the beneficiary is not the owner |
Sector expiry
Sectors, power and pledge expiring each day from today (UTC).
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| updatedAt | number | when the snapshot was taken, unix seconds |
| days[] | array | {date: YYYY-MM-DD, sectors, rawPowerTiB, qaPowerCCTiB, qaPowerDCTiB (DC as QA ×10), pledgeCCFIL, pledgeDCFIL}, numbers |
Unit exception: daily chart data, with power in TiB and pledge in FIL as numbers.
WindowPoSt (48 deadlines)
Each deadline's latest window: state, partitions and proof messages.
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| deadlines[].deadline | number | 0–47 |
| deadlines[].openHeight, openTime | number | window opening height and time |
| deadlines[].state | string | ok / wait / part (some late) / late / new / idle |
| deadlines[].partitions[] | array | {index, live, faulty, state, txid, txHeight, round}; the last three null without a proof message |
Current WindowPoSt window
The current deadline's partitions and proof messages for several miners (up to 200), all on one head. Miners that could not be fetched are listed in missing.
Parameters
| minersrequired | query | comma-separated miner IDs |
data fields
| height | number | the head used |
| miners[] | array | {miner, deadline, openHeight, updatedAt, partitions[{index, live, faulty, txid, txHeight}]}; txid is null until this window's proof lands |
| missing | string[] | miners unknown to this site or not fetched this time |
Not cached and has few concurrency slots; please do not poll it rapidly.
Faulty sectors
The miner's faulty sector numbers (ascending).
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
data fields
| count | number | number of faulty sectors |
| sectors | number[] | sector numbers |
Whenever the node's answer is uncertain the reply is a 5xx, never an empty list; bad parameters answer HTTP 400.
Sector info
A sector's on-chain info. code 202 sector precommitted when it is precommitted but not proven yet; 501 sector not found when it is absent, expired or terminated.
Parameters
| minerrequired | path | Miner ID starting with f0, e.g. f01518369 (or ?miner=) |
| sectorrequired | path | sector number |
data fields
| sealProof, sealedCid, sectorKeyCid | seal proof, CIDs; sectorKeyCid only after a SnapDeal | |
| activation, expiration, powerBaseEpoch | number | heights |
| dealIds | number[] | deal IDs |
| dealWeight, verifiedDealWeight | string | deal weights |
| initialPledge, expectedDayReward, expectedStoragePledge, replacedDayReward, dailyFee | string | attoFIL string |
Only HTTP 200 with code 501 and msg "sector not found" means the sector is really gone (an explicit answer from a fresh node, no precommit either); precommitted but not proven answers code 202 (data: miner, sector, sealedCid, precommitEpoch, expiration), bad parameters HTTP 400 and node failures 5xx. Delete files on the first only.
Addresses
Address details
Any address (f0–f4 or 0x): type, balance, nonce, multisig details, related miners and the balance of miners owned.
Parameters
| addressrequired | path | an f0/f1/f2/f3/f4 or 0x address (or ?address=) |
data fields
| id, robust, eth | string | null | ID, robust and 0x addresses (null when none) |
| actor | string | type: account, multisig, storageminer, evm, ethaccount, placeholder… |
| balance | string | live balance, attoFIL |
| nonce, height | number | messages sent, the head used |
| multisig | object | multisigs only: signers, threshold, available, locked, startEpoch, unlockDuration |
| miners[] | array | {miner, roles (owner/worker/control), power (bytes), balance (attoFIL)} |
| owned | object | miners owned: miners (count), balance, total (with its own), attoFIL |
Address → ID
The ID address (f0…) of any address.
Parameters
| addressrequired | path | an f0–f4 or 0x address |
data fields
| address | string | the address asked for |
| id | string | ID address |
Rankings
Power ranking
Miners with power, by quality-adjusted power.
Parameters
| page | query | page, from 1 |
| pageSize | query | 30 / 50 / 100 / 200, default 30 |
data fields
| total, page, pageSize | number | paging |
| list[].rank, miner | rank, miner | |
| list[].sectorSize, qualityAdjPower, rawBytePower | string | bytes, decimal string |
| list[].share, shareOfTop | number | of the network, relative to #1, 0–1 |
| list[].blocks24h, wins24h | number | blocks and wins in the last 24 hours |
Rich list
The top 1,000 addresses by balance; a miner's whole balance (pledge and vesting included) counts toward its owner and miners are not listed on their own. Balances come from this site's index (refreshed within 24 h). System addresses f00–f099 and payment channels are left out.
Parameters
| page, pageSize | query | as in /api/rankPower |
| kind | query | all (default) / owner (owns miners) / plain (the rest); ranks are kept when filtering |
data fields
| list[].rank, id, address, actor | rank, ID, robust address, type | |
| list[].balance, ownBalance, minerBalance | string | total, own, owned miners', attoFIL |
| list[].miners | number | owned miners with a balance |
| list[].power | string | the owned miners' QA power, bytes |
| list[].share | number | wealth share: the total balance as a fraction of the base, 0–1 |
| list[].powerShare | number | power share: the owned power as a fraction of the network QA power, 0–1 |
| top, supply, updatedAt | the filtered #1's total, the share's base (attoFIL), when computed |
Downloads
Sector expiry sheet (Excel)
The miner's daily sector expiry as an .xlsx file, past dates included.
Parameters
| minerrequired | query | miner ID |
Legacy endpoints
These are earlier endpoints with inconsistent names and formats. They still work but are deprecated (their replies carry a Deprecation header); please use the endpoint on the right. They will be removed once their callers have moved.
| /api/NewHeight | → chainHead |
| /api/overview | → chainHead |
| /api/rank | → rankPower / rankRich |
| /api/ListBlocksHeight | → blocks |
| /api/ListBlocksCid | → block |
| /api/ChainGetTipSetByHeight | → tipset |
| /api/SectorExpire | → minerExpire |
| /api/miner | → minerAccount / minerInfo |
| /api/deadlines | → minerWdpostCurrent |
| /api/minerFaults | → minerFaulty |
| /api/StateSectorGetInfo | → minerSector |
| /api/StateSearchMsg | → message |
| /api/EthGetMessageCidByTransactionHash | → ethTx |
| /api/StateLookupID | → addressId |
| /api/minerBlocks | → blocks?miners= |
| /api/wdpostCurrent | → minerWdpostCurrent |