Position Lifecycle

Open

POST /api/v1/positions/open-by-token — Build an unsigned transaction to open a leveraged position.

curl -X POST https://api.lavarage.xyz/api/v1/positions/open-by-token \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "baseTokenMint": "So11111111111111111111111111111111111111112",
    "userPublicKey": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
    "collateralAmount": "1000000000",
    "leverage": 3,
    "side": "LONG",
    "slippageBps": 50
  }'

Returns { transaction, positionAddress, lastValidBlockHeight, quote }.

Monitor

GET /api/v1/positions — List positions filtered by owner wallet or status.

curl "https://api.lavarage.xyz/api/v1/positions?owner=GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v&status=OPEN" \
  -H "x-api-key: YOUR_KEY"

Query parameters:

owner — filter by wallet address
status — OPEN, CLOSED, or ALL (default: ALL)

Close

Two-step process: get a quote first, then build the transaction.

Step 1 — Get close quote:

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

Returns a CloseQuote with repayAmount, fee, and swap details.

Step 2 — Build close transaction:

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

Returns { transaction, lastValidBlockHeight, quote }.

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.

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.

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 }.

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 [email protected] to set up delegation.