Managing positions

Read positions

curl -s "https://api.spiralstake.xyz/v1/partner/positions/0xUSER?chainId=1" \
  -H "authorization: Bearer $SPIRAL_KEY"

Each position carries an id (the on-chain index — feeds manage builds), a globally-unique positionId, collateral/debt, current vs. liquidation LTV, leverage, net USD value, and live APY.

Build a manage/close transaction

curl -s -X POST https://api.spiralstake.xyz/v1/partner/manage/build \
  -H "authorization: Bearer $SPIRAL_KEY" -H "content-type: application/json" \
  -d '{"userAddress":"0x…","id":0,"action":"close"}'

Actions

Action	Extra fields
`close`	—
`increase_leverage`	`desiredLtv` or `leverage`
`add_collateral`	`payToken`, `amount`
`remove_collateral`	`amount`
`repay`	`payToken`, `amount`, optional `full: true`
`borrow`	`amount`

The response is the same { approvals, tx, meta } bundle — sign it the same way. Re-read positions after the transaction confirms to refresh your UI.

Exit health — surface it to your users

Each position carries exitLiquidity, measured against its full unwind notional (closing swaps all the collateral, not just equity):

"exitLiquidity": { "tier": "good", "cleanExitSize": "$500K+", "unwindSizeUsd": 264.2, "exceedsCleanExitSize": false, "noSwapRoute": false }

Show it on your position UI. exceedsCleanExitSize: true means a close will slip — a market can be deep while that specific position is larger than the depth that exits cleanly.

Users are never trapped. A one-shot close needs a live swap route and fails closed if it’s gone. But repay (paying in the loan token) and remove_collateral need no swap at all — repay the debt, then withdraw the collateral in-kind. Build that path into your UI as the fallback, and use exceedsCleanExitSize to prompt users to unwind early.

Get Started

Guides

API Reference

Reference

Read positions

Build a manage/close transaction

Actions

Exit health — surface it to your users

​Read positions

​Build a manage/close transaction

​Actions

​Exit health — surface it to your users

Read positions

Build a manage/close transaction

Actions

Exit health — surface it to your users