Guides

Advanced Operations

Operations beyond basic open/close for managing positions. All endpoints require x-api-key authentication.

Partial Sell

Take partial profits atomically: splits the position at a ratio and closes the split portion in a single Jito bundle.

curl -X POST https://api.lavarage.xyz/api/v1/positions/partial-sell \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
    "splitRatioBps": 3000,
    "slippageBps": 50
  }'

Returns { splitTransaction, closeTransaction, newPositionAddresses, swapQuote }. Submit both transactions as a Jito bundle via POST /api/v1/bundle.

splitRatioBps: 3000 = sell 30% of the position. The remaining 70% stays open.

Split

Split one position into two positions at a given ratio.

curl -X POST https://api.lavarage.xyz/api/v1/positions/split \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
    "splitRatioBps": 5000
  }'

splitRatioBps: 5000 = split 50/50. Returns { transaction, lastValidBlockHeight, newPositionAddresses }.

Repay

Repay borrowed funds directly from the wallet (no swap). Returns collateral without slippage risk — useful if you already hold the quote token.

curl -X POST https://api.lavarage.xyz/api/v1/positions/repay \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v"
  }'

For partial repay (reduce borrow without fully closing), use POST /api/v1/positions/partial-repay with repaymentBps: 1-10000.

Position Health Management

When a position's LTV drops below the pool's open LTV (e.g. price appreciation), you have excess borrowing capacity. When a position approaches liquidation, you can add collateral to improve health. These endpoints let you manage position health programmatically.

Key Concepts

  • LTV (Loan-to-Value): debt / collateral value. Lower = healthier.
  • Open LTV: maximum LTV the pool allows for borrowing (e.g. 78% = 7800 bps).
  • Liquidation LTV: threshold where the position gets liquidated (e.g. 90%).
  • Headroom: when current LTV is well below liquidation LTV, you can borrow more.

Check Borrow Headroom

curl -X POST https://api.lavarage.xyz/api/v1/positions/increase-borrow-quote \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "mode": "withdraw"
  }'

Response includes:

  • maxAdditionalBorrow — max you can borrow in quote token smallest units
  • currentLTV / projectedLTV — LTV before and after borrowing max
  • hasHeadroom — true if position has meaningful borrowing capacity
  • priceScenarios — what-if table showing PnL and LTV at various price changes

Withdraw (Borrow More)

Borrow additional quote tokens and receive them in your wallet:

curl -X POST https://api.lavarage.xyz/api/v1/positions/increase-borrow \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "additionalBorrowAmount": "500000000",
    "mode": "withdraw"
  }'

Sign and submit the returned transaction. Your debt increases and you receive the quote tokens.

Compound (Re-Leverage)

Borrow more, swap to base token via Jupiter, and deposit as additional collateral — all in one transaction:

# First get a compound quote to see the swap estimate
curl -X POST https://api.lavarage.xyz/api/v1/positions/increase-borrow-quote \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "mode": "compound",
    "slippageBps": 50
  }'

# Then build the transaction
curl -X POST https://api.lavarage.xyz/api/v1/positions/increase-borrow \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "additionalBorrowAmount": "500000000",
    "mode": "compound",
    "slippageBps": 50,
    "astralaneTipLamports": 10000
  }'

Compound mode includes a Jupiter swap, so it supports MEV protection via astralaneTipLamports. Submit the signed transaction via POST /api/v1/bundle/submit with mevProtect: true.

The compound quote's jupiterQuote.outAmount tells you how many base tokens you'll receive. The projectedLTV accounts for both the increased debt and the new collateral.

Add Collateral (Rescue from Liquidation)

If your position is approaching liquidation, add more base tokens as collateral:

# Get quote to see projected LTV improvement
curl -X POST https://api.lavarage.xyz/api/v1/positions/add-collateral-quote \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "collateralAmount": "1000000000"
  }'

# Build the transaction
curl -X POST https://api.lavarage.xyz/api/v1/positions/add-collateral \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "YOUR_POSITION",
    "userPublicKey": "YOUR_WALLET",
    "collateralAmount": "1000000000"
  }'

The collateral amount is in the base token's smallest units. The add-collateral quote response includes baseTokenAddress and baseDecimals so you know which token to send and at what precision.

Auto-Compound Bot Example

// Poll positions and auto-compound when headroom is available
async function autoCompound(positionAddress: string, wallet: Keypair) {
  const quote = await fetch(`${API_BASE}/api/v1/positions/increase-borrow-quote`, {
    method: 'POST',
    headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      positionAddress,
      userPublicKey: wallet.publicKey.toBase58(),
      mode: 'compound',
      slippageBps: 100,
    }),
  }).then(r => r.json());

  if (!quote.hasHeadroom || Number(quote.maxAdditionalBorrow) <= 0) return;

  const { transaction } = await fetch(`${API_BASE}/api/v1/positions/increase-borrow`, {
    method: 'POST',
    headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      positionAddress,
      userPublicKey: wallet.publicKey.toBase58(),
      additionalBorrowAmount: quote.maxAdditionalBorrow,
      mode: 'compound',
      slippageBps: 100,
    }),
  }).then(r => r.json());

  const tx = VersionedTransaction.deserialize(bs58.decode(transaction));
  tx.sign([wallet]);
  const sig = await connection.sendRawTransaction(tx.serialize());
  console.log('Compounded:', sig);
}

Take-Profit and Stop-Loss Orders

Create automated TP/SL orders that execute server-side when the trigger price is hit.

curl -X POST https://api.lavarage.xyz/api/v1/orders \
  -H "x-api-key: YOUR_KEY" \
  -H "x-wallet-address: GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v" \
  -H "x-wallet-signature: <Ed25519 signature>" \
  -H "x-wallet-message: lavarage:GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v:1710500000000" \
  -H "Content-Type: application/json" \
  -d '{
    "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "walletId": "privy-wallet-id",
    "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
    "orderType": "TAKE_PROFIT",
    "triggerPrice": "200.00",
    "side": "LONG"
  }'

Required fields: positionAddress, walletId, userPublicKey, orderType, triggerPrice, side.

Note: Orders require a Privy embedded wallet with delegation enabled. walletId is the Privy wallet ID (not the Solana address). The wallet must be delegated to the Lavarage key quorum before orders can execute server-side. Contact https://lavarage.xyz/partners if this is a blocker for your integration.

Updated 4 days ago