Join the collateral queue

post/collateral/joinapi_key

Post principal and permit for count new positions, each under its own lender key. Positions cannot be withdrawn once queued, so acknowledgeNoWithdrawal must be true. Send expectedEmissionBoxId from the quote to get a 409 instead of a join priced against stale state.

Send priorityFeeEachNanoErgs as the quote was taken at, since it decides what each position locks up. A non-zero fee is at least minPriorityFeeNanoErgs, but there is no maximum: a fee above the quote's break-even is accepted, because the mined block's own transaction fees can still cover it.

Refused with 409 while the client has autoCollateralize on. The automated pass owns lender-key selection, and a manual join can take a key it is already using; only one live position per key is allowed, and the second is forfeited. Check manualJoinAllowed on the quote first.

Positions are created one at a time, each chained onto the last. If one fails, the run stops there: the response is 200 with the positions already created and a stoppedReason. A run that creates none returns an error status instead.

Request body

CollateralJoinExecuteRequest · application/json

countinteger · int32required
Positions to create
1 – 25
acknowledgeNoWithdrawalbooleanrequired
Must be true, or the request is rejected with 400. A queued position cannot be withdrawn or cancelled; its principal and permit return only when a block spends the box.
maxPermitEachLitstring
Permit cap. If any single permit would exceed this, nothing is sent. Omit for no cap. Decimal string.
expectedEmissionBoxIdstring
Emission box the quote was made against
priorityFeeEachNanoErgsstring
The fee, as the quote was taken at. Omitted or '0' posts at the floor; anything else is at least minPriorityFeeNanoErgs. Not capped at the quote's break-even — a higher fee is accepted and can still be repaid by the mined block's transaction fees. Decimal string.
default "0"decimal string

Responses

200The join transactions, one per positionCollateralJoinResult▶

▶
joinsCollateralJoinEntry[]required
- outcomestringrequired
  Node submission outcome for the known transaction ID.
  one ofacceptedrejecteduncertain
- txIdstringrequired
- positioninteger · int64required
  Queue position taken
- lenderAddressstringrequired
  The key holding this position. It receives the block reward when the position is mined against, and the permit back when the box is spent.
- principalNanoErgsstringrequired
  What this position locked up, the whole priority fee included. Decimal string.
- priorityFeeNanoErgsstring
  The fee this position posted. '0' when it posted at the floor. Decimal string.
- permitLitstringrequired
  Decimal string.
totalNanoErgsstringrequired
Everything sent, principals plus fees. Decimal string.
stoppedReasonstring
Present when fewer positions were created than requested, giving the error that stopped the run. The entries in joins were still created and their principal is committed.

400Malformed body, a count outside 1..25, a permit cap below the current requirement, or `acknowledgeNoWithdrawal` not set. ApiError▶

errorintegerrequired
Error code
reasonstringrequired
Error message explaining the reason of the error
detailstringrequirednullable
Detailed error description

409`autoCollateralize` is on, so manual joins are refused — the client's own pass owns joining. Also returned when the emission box moved between quote and send, in which case re-quote and resend. ApiError▶

errorintegerrequired
Error code
reasonstringrequired
Error message explaining the reason of the error
detailstringrequirednullable
Detailed error description

422The wallet cannot cover it, a permit exceeds `maxPermitEachLit`, fewer free lender keys remain than positions requested, or the run created no position at all. ApiError▶

errorintegerrequired
Error code
reasonstringrequired
Error message explaining the reason of the error
detailstringrequirednullable
Detailed error description

503Node or wallet unavailable. Retry.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

← PreviousQuote joining the queue Next →LithosDex pool state

curl -X POST "http://localhost:9000/collateral/join" \ -H "api_key: $LITHOS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "count": 3, "acknowledgeNoWithdrawal": true, "maxPermitEachLit": "20000000000", "expectedEmissionBoxId": "88c297f99da7172f6aa20efbead69aa40e2b7734a1873d66ca1db6b19d214db6", "priorityFeeEachNanoErgs": "10000000" }'

{ "joins": [ { "outcome": "accepted", "txId": "40b7d045a858d537cdbf072e46ffbb86c0c9f6b0e93c369c1ffcba76797636d7", "position": 1247, "lenderAddress": "3WwbQFz3vgi8ChY9dM1haQLGDeQYe5U9z98bwWW4TqxxEAvyYu5y", "principalNanoErgs": "2925000000", "priorityFeeNanoErgs": "10000000", "permitLit": "19370000000" } ], "totalNanoErgs": "8748000000", "stoppedReason": "Double spending attempt" }