Quote joining the queue
/collateral/join/checkapi_keyWhat creating count positions costs right now: principal per position, network fee per join, and the permit for each. Permits escalate because each join lengthens the queue the next one is priced from.
priorityFeeEachNanoErgs is the ERG added to the box above the floor, so it raises principalEachNanoErgs one for one. A miner spends whichever collateral box pays it most, so a fee buys a place ahead of the boxes offering nothing. Past breakEvenPriorityFeeNanoErgs the 3 ERG coinbase no longer covers the principal and netAtCoinbaseEachNanoErgs goes negative — the rest then has to come from the transaction fees of the block the box is mined against.
Also reports whether the join would be accepted: check manualJoinAllowed and blockedReason before enabling a send control. Requires an api_key, since the quote names this wallet's lender addresses and its shortfall.
Request body
CollateralJoinCheckRequest · application/jsoncountinteger · int32Positions to create, each under its own key
default11 – 25priorityFeeEachNanoErgsstringnanoERG each position adds above the 2.915 ERG floor. Part of it goes to whichever miner spends the collateral box, which is what buys the position priority. Omitted or '0' posts at the floor; anything else is at least minPriorityFeeNanoErgs.
default"0"decimal string
Responses
200Quote for the requested number of positionsCollateralJoinQuote▶
countinteger · int32requiredprincipalEachNanoErgsstringrequiredWhat one position locks up: the 2915000000 floor plus the whole priority fee. Identical for every position in the quote. Decimal string.
priorityFeeEachNanoErgsstringrequiredThe fee this quote was priced at, echoed back. Decimal string.
minPriorityFeeNanoErgsstringrequiredThe smallest non-zero fee that may be posted. Fixed at 1000000 (0.001 ERG); below it the block's finder is left too little to be worth the output it is paid in.
breakEvenPriorityFeeNanoErgsstringrequiredThe largest fee the 3 ERG coinbase repays on its own, which is the whole spread a lender earns. Fixed at 85000000. A fee above it is accepted; the difference then has to come from the mined block's transaction fees.
netAtCoinbaseEachNanoErgsstringrequiredBlock reward minus principal, per position, before the mined block's own fees. Signed — negative above breakEvenPriorityFeeNanoErgs. Decimal string.
txFeeEachNanoErgsstringrequiredNetwork fee per join transaction. Decimal string.
permitsLitstring[]requiredPermit for each position, in join order. Each join lengthens the queue, so these escalate. Decimal strings.
permitTotalLitstringrequiredSum of
permitsLit. Decimal string.totalNanoErgsstringrequiredTotal ERG leaving the wallet — principals plus fees. Decimal string.
firstPositioninteger · int64requiredQueue position the first join takes; the rest follow consecutively
emissionTipBoxIdstringrequiredEmission box the quote was made against. Send back as
expectedEmissionBoxId.affordNowbooleanrequiredWhether the wallet can cover it today
shortfallNanoErgsstringrequiredHow much short the wallet is when
affordNowis false. Decimal string.ownRoomLeftinteger · int32requiredPositions the configured exposure budget would still allow after this
manualJoinAllowedbooleanrequiredWhether
POST /collateral/joinwill accept this join. Disable the send control when false. The join endpoint checks the same conditions itself, so a quote taken before a configuration change does not license the send.blockedReasonstringWhy
manualJoinAllowedis false; absent when it is true. Only the first applicable reason is reported, in the order listed above.AUTO_COLLATERALIZE— the client joins on its own timer and refuses manual joins.BUDGET_EXHAUSTED—maxOwnCollateralleaves room for fewer positions than requested.NO_LENDER_KEYS—freeLenderKeys + keysDerivableis belowkeysRequired.INSUFFICIENT_FUNDS— the wallet cannot covertotalNanoErgs.one ofAUTO_COLLATERALIZENO_LENDER_KEYSBUDGET_EXHAUSTEDINSUFFICIENT_FUNDSlenderAddressesstring[]requiredThe lender keys this join would use, in join order, matching
permitsLitindex for index. Shorter thancountwhen the join would derive new keys to make up the difference; those addresses do not exist yet and cannot be named in advance. Empty whenblockedReasonisNO_LENDER_KEYS.freeLenderKeysinteger · int32requiredKeys with status FREE at the moment of quoting
keysRequiredinteger · int32requiredKeys this join consumes — one per position, so equal to
count
400Malformed body, or a count outside 1..25.ApiError▶
errorintegerrequiredError code
reasonstringrequiredError message explaining the reason of the error
detailstringrequirednullableDetailed error description
503Node or wallet unavailable. Retry.ApiError▶
errorintegerrequiredError code
reasonstringrequiredError message explaining the reason of the error
detailstringrequirednullableDetailed error description
defaultErrorApiError▶
errorintegerrequiredError code
reasonstringrequiredError message explaining the reason of the error
detailstringrequirednullableDetailed error description