LithosDocs
ProtocolPayoutsTokenStatsDocs
Start mining
Documentation home
Protocol
  • Lithos Protocol
  • LFSM
    • Rollups
    • NISPs
    • Emissions
    • Mining on Lithos
    • Candidate building
    • Ergo Voting
  • LithosDex
    • Choosing a pool
    • Trading with orders
    • Providing liquidity
    • Creating a pool
    • Difficulty forwards
Run Lithos
  • Startup guide
    • Setting up an Ergo node
  • Configuration
    • Node connection and security
    • Stratum and difficulty
    • Block packages
    • Batching and orders
    • Collateral and emission
    • Wallet and consolidation
    • Statistics and web panels
    • Synchronization and storage
    • Tasks and dispatchers
    • Failure modes
    • Reporting issues
    • Renting hashrate into Lithos
    • Checking your wallet
Client API
  • Overview
    • getLithos client information
    • getList UTXO ids for blocks
    • getUTXO ids by block height
    • getBlock info by UTXO id
    • postBlock info for multiple UTXO ids
    • getGet a block's miner set
    • getList all pool blocks
    • getGet Lithos payouts
    • getStatistics overview
    • getMining and payment totals
    • getMining statistics by hour or day
    • getEstimate Lithos hashrate
    • getNetwork difficulty by epoch
    • getThis client's own hashrate
    • getThis client's hashrate over time
    • getThis client's payouts and claims
    • getCollateral inventory
    • getThis wallet's lending earnings
    • getLocal mining activity
    • getCollateral market snapshot
    • getList queue boxes
    • getList the active set
    • getPermit price history
    • getYour lending status
    • postQuote joining the queue
    • postJoin the collateral queue
    • getLithosDex pool state
    • getEvery LithosDex pool
    • getOne LithosDex pool and its vault
    • getList your outstanding orders on any pool
    • postQuote a direct swap on any pool
    • postSwap directly on any pool
    • postQuote a direct deposit on any pool
    • postDeposit directly on any pool
    • postQuote a direct redemption on any pool
    • postRedeem a provision directly on any pool
    • getList your provisions on any pool
    • postClaim a provision's fees on any pool
    • postCheck a flush on any pool
    • postFlush any pool
    • getA verified pool's price history
    • getA verified pool's fee history
    • getA verified pool's recent activity
    • getA provision's fee history on a verified pool
    • postQuote a new LithosDex pool
    • postCreate a LithosDex pool
    • postQuote a swap order on any pool
    • postPlace a swap order on any pool
    • postQuote a deposit order on any pool
    • postPlace a deposit order on any pool
    • postQuote a redeem order on any pool
    • postPlace a redeem order on any pool
    • getLithosDex fee vault state
    • getList your outstanding orders
    • postQuote a swap order
    • postPlace a swap order
    • postQuote a deposit order
    • postPlace a deposit order
    • postQuote a redeem order
    • postPlace a redeem order
    • postCancel an order
    • postQuote a swap
    • postQuote a swap by desired output
    • postExecute a swap
    • postQuote a liquidity deposit
    • postDeposit liquidity
    • postQuote a liquidity redemption
    • postRedeem liquidity
    • getList liquidity provisions
    • postLook up provision NFTs
    • postClaim settled fees for a provision
    • postQuote a provision resize
    • postResize a provision
    • postCheck a pending fee flush
    • postFlush pending fees to the vault
    • getPool-wide fee history
    • getPool price history
    • getRecent pool activity
    • getFee history for one provision
    • getDifficulty accumulator and the next epoch's difficulty
    • getList open offers
    • postCreate an offer
    • postQuote an offer
    • postQuote filling an offer
    • postFill an offer
    • postQuote cancelling an offer
    • postCancel an offer
    • getThe whole market
    • getYour settled positions and closed offers
    • getList your positions and offers
    • postQuote settling a position
    • postSettle a position
    • getWallet balances
    • getYour block rewards
    • postClaim unlocked block rewards
    • getVerified tokens
    • getGet Stratum information
    • getGet candidate settings
    • getGet difficulty commitment
    • postCommit a difficulty
    • getGet best NISP at height
Lithos

A decentralized mining pool protocol on Ergo. Miners build their own blocks; contracts pay them for proven work.

Live on Ergo mainnet
Protocol
  • How Lithos works
  • Mining on Lithos
  • NISPs
  • Emissions
  • LFSM contracts
Run Lithos
  • Startup guide
  • Configuration
  • LithosDex
  • Difficulty forwards
  • Client API
  • Failure modes
Network
  • Live stats
  • Public stats API
  • Ergo Platform↗
  • SOAT Miner↗
Community
  • Telegram↗
  • X / Twitter↗
  • GitHub↗
Lithos
© 2026 Lithos Protocol. The Lithos client, its contracts and Lithos Launcher are open source under CC0.λίθος — stone
Docs/Client API/Difficulty Forwards

List your positions and offers

get/forwards/positionsapi_key

Every position this wallet holds a side of, by window end, with its status and a mark against the strike; and every unspent offer it made, open or not, so expired ones can be cancelled.

Responses

200This wallet's positions and offersDFPositionList▶
  • heightinteger · int32required
  • currentEpochinteger · int32required
  • ▶
    positionsDFPositionView[]required
    • boxIdstringrequired
    • sidestringrequired

      This wallet's side; both when it holds both keys.

      one oflongshortboth
    • longstringrequired

      Address the long side is paid to.

    • shortstringrequired
    • strikestringrequired
    • notionalstringrequired
    • marginstringrequired
    • windowStartinteger · int32required
    • windowLengthinteger · int32required
    • windowEndinteger · int32required
    • statusstringrequired

      waiting before the window starts, in_window until its last epoch is recorded, settleable once it is, and refundable once its first epoch has left the accumulator, when each side gets its margin back.

      one ofwaitingin_windowsettleablerefundable
    • epochsKnowninteger · int32required

      Window epochs whose difficulty is known, recorded or current.

    • markDifficultystring

      The window's mean with every unknown epoch at the newest difficulty known. Absent when refundable.

    • markMovenumber · double

      markDifficulty against the strike, as a fraction.

    • markPayoutstring

      LIT base units the long side would receive on top of its margin at the mark, negative when the short side is paid; at most the margin either way. Exact once settleable.

    • pnlstring

      markPayout from this wallet's side; zero when it holds both.

    • owedLongstring

      LIT base units a settlement now pays the long side, margin included. Present once settleable or refundable.

    • owedShortstring
  • ▶
    offersDFOfferView[]required

    Every unspent offer this wallet made, open, expired or unfillable.

    • boxIdstringrequired
    • makerstringrequired

      Address the maker is paid to.

    • makerSidestringrequired

      long is paid when the window's mean difficulty is above the strike, short when below.

      one oflongshort
    • strikestringrequired

      Difficulty the window's mean is measured against.

    • notionalstringrequired

      LIT base units.

    • marginstringrequired

      Each side's margin, a fifth of the notional, and the most either side can lose of it.

    • windowStartinteger · int32required
    • windowLengthinteger · int32required
    • windowEndinteger · int32required

      The window's last epoch.

    • expiryinteger · int32required

      The last height a fill can be mined at.

    • lastFillHeightinteger · int32required

      The last height a fill can actually be mined at: the expiry, or earlier when the window would start less than 2 epochs after the fill.

    • litstringrequired

      LIT base units the offer holds.

    • nanoErgsstringrequired
    • takerLitstringrequired

      LIT base units a fill takes from the taker.

    • takerNanoErgsstringrequired

      nanoERG a fill takes from the taker, network fee included.

    • impliedMovenumber · double

      The strike against the current difficulty, as a fraction.

    • impliedMoveNextnumber · double

      The strike against nextDifficulty, when known.

    • minebooleanrequired

      Whether this wallet made the offer.

    • fillablebooleanrequired

      Whether this wallet's fill sent now would be accepted.

    • refusalstring

      Why not, when fillable is false.

  • truncatedbooleanrequired

    Whether a scan stopped at 2,000 boxes, so older boxes may be missing.

403Missing or wrong api_keyApiError▶
  • errorintegerrequired

    Error code

  • reasonstringrequired

    Error message explaining the reason of the error

  • detailstringrequirednullable

    Detailed error description

503Node or index unavailable. Never returns a partial list.ApiError▶
  • errorintegerrequired

    Error code

  • reasonstringrequired

    Error message explaining the reason of the error

  • detailstringrequirednullable

    Detailed error description

defaultErrorApiError▶
  • errorintegerrequired

    Error code

  • reasonstringrequired

    Error message explaining the reason of the error

  • detailstringrequirednullable

    Detailed error description

← PreviousYour settled positions and closed offersNext →Quote settling a position
Request
curl -X GET "http://localhost:9000/forwards/positions" \
  -H "api_key: $LITHOS_API_KEY"
Response
{
  "height": 0,
  "currentEpoch": 0,
  "positions": [
    {
      "boxId": "string",
      "side": "long",
      "long": "string",
      "short": "string",
      "strike": "string",
      "notional": "string",
      "margin": "string",
      "windowStart": 0,
      "windowLength": 0,
      "windowEnd": 0,
      "status": "waiting",
      "epochsKnown": 0,
      "markDifficulty": "string",
      "markMove": 0,
      "markPayout": "string",
      "pnl": "string",
      "owedLong": "string",
      "owedShort": "string"
    }
  ],
  "offers": [
    {
      "boxId": "string",
      "maker": "string",
      "makerSide": "long",
      "strike": "string",
      "notional": "string",
      "margin": "string",
      "windowStart": 0,
      "windowLength": 0,
      "windowEnd": 0,
      "expiry": 0,
      "lastFillHeight": 0,
      "lit": "string",
      "nanoErgs": "string",
      "takerLit": "string",
      "takerNanoErgs": "string",
      "impliedMove": 0,
      "impliedMoveNext": 0,
      "mine": true,
      "fillable": true,
      "refusal": "string"
    }
  ],
  "truncated": true
}