diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 00000000..c6519f75 Binary files /dev/null and b/.DS_Store differ diff --git a/api-reference/index.mdx b/api-reference/index.mdx index f340f098..52b04fc8 100644 --- a/api-reference/index.mdx +++ b/api-reference/index.mdx @@ -14,6 +14,9 @@ description: "Overview of Jupiter API Reference" 1 item + + 4 items + 5 items diff --git a/api-reference/lend.mdx b/api-reference/lend.mdx index 921b8814..5585590e 100644 --- a/api-reference/lend.mdx +++ b/api-reference/lend.mdx @@ -6,6 +6,6 @@ description: "Overview of Jupiter Lend API" - 11 items + 11 items diff --git a/api-reference/perps.mdx b/api-reference/perps.mdx new file mode 100644 index 00000000..6b3db716 --- /dev/null +++ b/api-reference/perps.mdx @@ -0,0 +1,20 @@ +--- +title: "Perps (Beta)" +sidebarTitle: "Overview" +description: "Overview of Jupiter Perps API" +--- + + + + 1 item + + + 23 items + + + 3 items + + + 5 items + + diff --git a/api-reference/perps/delete-orders-limit.mdx b/api-reference/perps/delete-orders-limit.mdx new file mode 100644 index 00000000..47bfb0c0 --- /dev/null +++ b/api-reference/perps/delete-orders-limit.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml delete /orders/limit +--- \ No newline at end of file diff --git a/api-reference/perps/delete-tpsl-with-fee.mdx b/api-reference/perps/delete-tpsl-with-fee.mdx new file mode 100644 index 00000000..0f908cc8 --- /dev/null +++ b/api-reference/perps/delete-tpsl-with-fee.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml delete /tpsl-with-fee +--- \ No newline at end of file diff --git a/api-reference/perps/delete-tpsl.mdx b/api-reference/perps/delete-tpsl.mdx new file mode 100644 index 00000000..8af76fef --- /dev/null +++ b/api-reference/perps/delete-tpsl.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml delete /tpsl +--- \ No newline at end of file diff --git a/api-reference/perps/get-jlp-info.mdx b/api-reference/perps/get-jlp-info.mdx new file mode 100644 index 00000000..a8d1b2ff --- /dev/null +++ b/api-reference/perps/get-jlp-info.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /jlp-info +--- \ No newline at end of file diff --git a/api-reference/perps/get-lending-history.mdx b/api-reference/perps/get-lending-history.mdx new file mode 100644 index 00000000..42537a45 --- /dev/null +++ b/api-reference/perps/get-lending-history.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /lending/history +--- \ No newline at end of file diff --git a/api-reference/perps/get-lending-info.mdx b/api-reference/perps/get-lending-info.mdx new file mode 100644 index 00000000..04135dd9 --- /dev/null +++ b/api-reference/perps/get-lending-info.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /lending/info +--- \ No newline at end of file diff --git a/api-reference/perps/get-lending-positions.mdx b/api-reference/perps/get-lending-positions.mdx new file mode 100644 index 00000000..8a39bd9d --- /dev/null +++ b/api-reference/perps/get-lending-positions.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /lending/positions +--- \ No newline at end of file diff --git a/api-reference/perps/get-market-stats.mdx b/api-reference/perps/get-market-stats.mdx new file mode 100644 index 00000000..5fb845a9 --- /dev/null +++ b/api-reference/perps/get-market-stats.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /market-stats +--- \ No newline at end of file diff --git a/api-reference/perps/get-orders-expired.mdx b/api-reference/perps/get-orders-expired.mdx new file mode 100644 index 00000000..726f58d0 --- /dev/null +++ b/api-reference/perps/get-orders-expired.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /orders/expired +--- \ No newline at end of file diff --git a/api-reference/perps/get-orders-limit.mdx b/api-reference/perps/get-orders-limit.mdx new file mode 100644 index 00000000..7e5c8b4a --- /dev/null +++ b/api-reference/perps/get-orders-limit.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /orders/limit +--- \ No newline at end of file diff --git a/api-reference/perps/get-pool-info.mdx b/api-reference/perps/get-pool-info.mdx new file mode 100644 index 00000000..75e9a8d8 --- /dev/null +++ b/api-reference/perps/get-pool-info.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /pool-info +--- \ No newline at end of file diff --git a/api-reference/perps/get-positions-collateral-limits.mdx b/api-reference/perps/get-positions-collateral-limits.mdx new file mode 100644 index 00000000..aa127735 --- /dev/null +++ b/api-reference/perps/get-positions-collateral-limits.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /positions/collateral-limits +--- \ No newline at end of file diff --git a/api-reference/perps/get-positions.mdx b/api-reference/perps/get-positions.mdx new file mode 100644 index 00000000..103bae1b --- /dev/null +++ b/api-reference/perps/get-positions.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /positions +--- \ No newline at end of file diff --git a/api-reference/perps/get-top-traders.mdx b/api-reference/perps/get-top-traders.mdx new file mode 100644 index 00000000..d20ae6d3 --- /dev/null +++ b/api-reference/perps/get-top-traders.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /top-traders +--- \ No newline at end of file diff --git a/api-reference/perps/get-trader-stats.mdx b/api-reference/perps/get-trader-stats.mdx new file mode 100644 index 00000000..7505e88f --- /dev/null +++ b/api-reference/perps/get-trader-stats.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /trader-stats +--- \ No newline at end of file diff --git a/api-reference/perps/get-trades.mdx b/api-reference/perps/get-trades.mdx new file mode 100644 index 00000000..54d5fb78 --- /dev/null +++ b/api-reference/perps/get-trades.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml get /trades +--- \ No newline at end of file diff --git a/api-reference/perps/patch-orders-limit.mdx b/api-reference/perps/patch-orders-limit.mdx new file mode 100644 index 00000000..193d3bcf --- /dev/null +++ b/api-reference/perps/patch-orders-limit.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml patch /orders/limit +--- \ No newline at end of file diff --git a/api-reference/perps/patch-tpsl-with-fee.mdx b/api-reference/perps/patch-tpsl-with-fee.mdx new file mode 100644 index 00000000..d16eb439 --- /dev/null +++ b/api-reference/perps/patch-tpsl-with-fee.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml patch /tpsl-with-fee +--- \ No newline at end of file diff --git a/api-reference/perps/patch-tpsl.mdx b/api-reference/perps/patch-tpsl.mdx new file mode 100644 index 00000000..0a1fcb2e --- /dev/null +++ b/api-reference/perps/patch-tpsl.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml patch /tpsl +--- \ No newline at end of file diff --git a/api-reference/perps/post-jlp-burn.mdx b/api-reference/perps/post-jlp-burn.mdx new file mode 100644 index 00000000..bf568cf6 --- /dev/null +++ b/api-reference/perps/post-jlp-burn.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /jlp/burn +--- \ No newline at end of file diff --git a/api-reference/perps/post-jlp-mint.mdx b/api-reference/perps/post-jlp-mint.mdx new file mode 100644 index 00000000..1c99aa42 --- /dev/null +++ b/api-reference/perps/post-jlp-mint.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /jlp/mint +--- \ No newline at end of file diff --git a/api-reference/perps/post-lending-deposit-borrow.mdx b/api-reference/perps/post-lending-deposit-borrow.mdx new file mode 100644 index 00000000..ef67b0bb --- /dev/null +++ b/api-reference/perps/post-lending-deposit-borrow.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /lending/deposit-borrow +--- \ No newline at end of file diff --git a/api-reference/perps/post-lending-pay-withdraw.mdx b/api-reference/perps/post-lending-pay-withdraw.mdx new file mode 100644 index 00000000..f0f66315 --- /dev/null +++ b/api-reference/perps/post-lending-pay-withdraw.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /lending/pay-withdraw +--- \ No newline at end of file diff --git a/api-reference/perps/post-orders-limit.mdx b/api-reference/perps/post-orders-limit.mdx new file mode 100644 index 00000000..3b46e35f --- /dev/null +++ b/api-reference/perps/post-orders-limit.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /orders/limit +--- \ No newline at end of file diff --git a/api-reference/perps/post-positions-close-all.mdx b/api-reference/perps/post-positions-close-all.mdx new file mode 100644 index 00000000..54c17f6a --- /dev/null +++ b/api-reference/perps/post-positions-close-all.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /positions/close-all +--- \ No newline at end of file diff --git a/api-reference/perps/post-positions-decrease-with-fee.mdx b/api-reference/perps/post-positions-decrease-with-fee.mdx new file mode 100644 index 00000000..18e48338 --- /dev/null +++ b/api-reference/perps/post-positions-decrease-with-fee.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /positions/decrease-with-fee +--- \ No newline at end of file diff --git a/api-reference/perps/post-positions-decrease.mdx b/api-reference/perps/post-positions-decrease.mdx new file mode 100644 index 00000000..a271e2db --- /dev/null +++ b/api-reference/perps/post-positions-decrease.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /positions/decrease +--- \ No newline at end of file diff --git a/api-reference/perps/post-positions-increase-with-fee.mdx b/api-reference/perps/post-positions-increase-with-fee.mdx new file mode 100644 index 00000000..941a4d61 --- /dev/null +++ b/api-reference/perps/post-positions-increase-with-fee.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /positions/increase-with-fee +--- \ No newline at end of file diff --git a/api-reference/perps/post-positions-increase.mdx b/api-reference/perps/post-positions-increase.mdx new file mode 100644 index 00000000..6f663294 --- /dev/null +++ b/api-reference/perps/post-positions-increase.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /positions/increase +--- \ No newline at end of file diff --git a/api-reference/perps/post-tpsl-with-fee.mdx b/api-reference/perps/post-tpsl-with-fee.mdx new file mode 100644 index 00000000..4ddf0755 --- /dev/null +++ b/api-reference/perps/post-tpsl-with-fee.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /tpsl-with-fee +--- \ No newline at end of file diff --git a/api-reference/perps/post-tpsl.mdx b/api-reference/perps/post-tpsl.mdx new file mode 100644 index 00000000..aac5bafc --- /dev/null +++ b/api-reference/perps/post-tpsl.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /tpsl +--- \ No newline at end of file diff --git a/api-reference/perps/post-transaction-execute.mdx b/api-reference/perps/post-transaction-execute.mdx new file mode 100644 index 00000000..8835748d --- /dev/null +++ b/api-reference/perps/post-transaction-execute.mdx @@ -0,0 +1,3 @@ +--- +openapi: /openapi-spec/perps/perps.yaml post /transaction/execute +--- \ No newline at end of file diff --git a/api-reference/perps/trading-overview.mdx b/api-reference/perps/trading-overview.mdx new file mode 100644 index 00000000..3e49ce55 --- /dev/null +++ b/api-reference/perps/trading-overview.mdx @@ -0,0 +1,20 @@ +--- +title: "Trading Overview" +sidebarTitle: "Overview" +description: "Overview of Trading Endpoints in Jupiter Perps API" +--- + + + + 9 items + + + 5 items + + + 3 items + + + 6 items + + diff --git a/docs.json b/docs.json index 16e9bc94..a41218bd 100644 --- a/docs.json +++ b/docs.json @@ -169,16 +169,53 @@ "icon": "chart-line", "groups": [ { - "group": " ", - "pages": ["docs/perps/index"] + "group": "About Perps", + "pages": [ + "docs/perps/index", + "docs/perps/get-started" + ] + }, + { + "group": "Architecture", + "pages": [ + "docs/perps/jlp", + "docs/perps/oracles", + "docs/perps/fees", + "docs/perps/liquidation", + "docs/perps/jlp-lend" + ] + }, + { + "group": "Perps API", + "pages": [ + "docs/perps/transaction-execution", + { + "group": "Trading", + "pages": [ + "docs/perps/trading/position-data", + "docs/perps/trading/position-management", + "docs/perps/trading/limit-orders", + "docs/perps/trading/tpsl-orders" + ] + }, + { + "group": "JLP", + "pages": [ + "docs/perps/jlp/getting-jlp", + "docs/perps/jlp-lend/position-data", + "docs/perps/jlp-lend/position-management" + ] + } + ] }, { "group": "Perps Program", "pages": [ - "docs/perps/position-account", - "docs/perps/position-request-account", - "docs/perps/pool-account", - "docs/perps/custody-account" + "docs/perps/program/index", + "docs/perps/program/position-account", + "docs/perps/program/position-request-account", + "docs/perps/program/pool-account", + "docs/perps/program/custody-account" ] } ] @@ -418,6 +455,86 @@ } ] }, + { + "group": "Perps", + "tag": "BETA", + "pages": [ + "api-reference/perps", + { + "group": "Transaction Execution", + "pages": [ + "api-reference/perps/post-transaction-execute" + ] + }, + { + "group": "Trading", + "pages": [ + "api-reference/perps/trading-overview", + { + "group": "Informational", + "pages": [ + "api-reference/perps/get-market-stats", + "api-reference/perps/get-trader-stats", + "api-reference/perps/get-top-traders", + "api-reference/perps/get-pool-info", + "api-reference/perps/get-positions", + "api-reference/perps/get-positions-collateral-limits", + "api-reference/perps/get-orders-limit", + "api-reference/perps/get-orders-expired", + "api-reference/perps/get-trades" + ] + }, + { + "group": "Positions", + "pages": [ + "api-reference/perps/post-positions-increase", + "api-reference/perps/post-positions-increase-with-fee", + "api-reference/perps/post-positions-decrease", + "api-reference/perps/post-positions-decrease-with-fee", + "api-reference/perps/post-positions-close-all" + ] + }, + { + "group": "Limit Orders", + "pages": [ + "api-reference/perps/post-orders-limit", + "api-reference/perps/patch-orders-limit", + "api-reference/perps/delete-orders-limit" + ] + }, + { + "group": "TPSL", + "pages": [ + "api-reference/perps/post-tpsl", + "api-reference/perps/post-tpsl-with-fee", + "api-reference/perps/patch-tpsl", + "api-reference/perps/patch-tpsl-with-fee", + "api-reference/perps/delete-tpsl", + "api-reference/perps/delete-tpsl-with-fee" + ] + } + ] + }, + { + "group": "JLP", + "pages": [ + "api-reference/perps/get-jlp-info", + "api-reference/perps/post-jlp-mint", + "api-reference/perps/post-jlp-burn" + ] + }, + { + "group": "JLP Lending", + "pages": [ + "api-reference/perps/get-lending-info", + "api-reference/perps/get-lending-positions", + "api-reference/perps/get-lending-history", + "api-reference/perps/post-lending-deposit-borrow", + "api-reference/perps/post-lending-pay-withdraw" + ] + } + ] + }, { "group": "Trigger", "pages": [ diff --git a/docs/perps/fees.mdx b/docs/perps/fees.mdx new file mode 100644 index 00000000..ab42a68a --- /dev/null +++ b/docs/perps/fees.mdx @@ -0,0 +1,130 @@ +--- +title: "Fees" +description: "Understand fees involved in Jupiter Perps and JLP pool." +--- + +Jupiter Perpetuals operates on a **trader-to-LP exchange model** where the Jupiter Liquidity Pool (JLP) serves as the counterparty for all perpetual trades. The fee structure is designed to balance the interests of traders and liquidity providers while managing risk and maintaining pool stability. + +**How Fees Flow Between Traders and JLP:** + +1. **Traders pay fees** when opening/closing positions, borrowing assets, and swapping tokens. +2. **Fees are collected** by the protocol and accumulate in `feesReserves` for each custody. +3. **Fee distribution**: 75% of all fees go to JLP holders, 25% to the protocol. +4. **Reinvestment**: Fees are periodically reinvested into the pool, increasing the pool's AUM and benefiting all JLP holders through price appreciation. + +This fee model ensures that liquidity providers are compensated for providing capital and taking on the risk of being the counterparty to leveraged positions, while traders pay competitive fees for access to high-leverage trading with zero slippage execution. + +--- + +## Fee Overview + +The following table summarizes all fee types in Jupiter Perpetuals. + + +Fee parameters are subject to change, as Jupiter and third party risk auditors continue to monitor market conditions, protocol performance, pool utilization, and other factors to ensure competitive and sustainable fees. + + +| Fee Type | Rate | When Charged | Who Pays | Who Receives | +|----------|------|--------------|----------|--------------| +| **Base Fee** | 0.06% (6 BPS) | Opening/closing positions, liquidations, TP/SL, limit orders | Traders | JLP Pool (75%) + Protocol (25%) | +| **Price Impact Fee (Linear)** | Variable | Based on trade size relative to pool liquidity | Traders | JLP Pool (75%) + Protocol (25%) | +| **Price Impact Fee (Additive)** | Variable | When OI imbalance exceeds threshold | Traders | JLP Pool (75%) + Protocol (25%) | +| **Borrow Fee** | Variable (hourly) | Continuously on open positions | Traders | JLP Pool (75%) + Protocol (25%) | +| **Swap Fee** | 0.02% (2 BPS) for stables; 0.1% (10 BPS) for non-stables; Dynamic adjustment based on weightage | Swapping between JLP assets | Traders/LPs | JLP Pool (75%) + Protocol (25%) | +| **JLP Mint/Burn Fee** | Variable | Minting or burning JLP tokens | LPs | JLP Pool (75%) + Protocol (25%) | +| **Liquidation Penalty** | 100% of remaining collateral | When position is liquidated | Liquidated traders | JLP Pool (100%) | +| **Transaction Fees** | Variable | Submitting transactions | Traders | Solana Network | + +--- + +## Base Fee + +A flat rate of **0.06% (6 BPS)** is charged when performing these actions on the protocol: + +1. **Opening/Closing Positions**: When opening or closing a position +2. **Liquidations**: When positions are liquidated +3. **Take Profit / Stop Loss Orders**: When TP/SL orders execute +4. **Limit Orders**: When limit orders are filled + + +**Example Base Fee Calculation** + +$$ +\text{baseFee} = \text{tradeSize} \times \text{baseFeeRate} +$$ + +- $\text{tradeSize}$ = the size of the trade in USD, e.g. 10,000 USD +- $\text{baseFeeRate}$ = the base fee rate in BPS (0.06% = 6 BPS) +- $\text{baseFee}$ = 10,000 * 0.06% = **$6** + + +--- + +## Price Impact Fees + +1. **Linear Price Impact Fee**: Scales with trade size +2. **Additive Price Impact Fee**: Additional penalty when open interest imbalance is high + +### Rationale + +When trading on Jupiter Perpetuals, large trades don't incur price impact due to the use of oracle prices. This means the price shown to the trader is the price the trade is executed at—providing zero-slippage execution. + +This is different from orderbook exchanges where large trades consume liquidity at various price levels, resulting in worse execution prices (slippage). While this benefits traders, it creates risks for JLP holders who are exposed to potential losses from large trades. It also opens the possibility for attackers to move prices on other exchanges and profit from opening positions in Jupiter Perpetuals. + +To address this, Jupiter Perpetuals implements a **price impact fee** that simulates the price impact on traditional exchanges. The price impact fee consists of two components: a linear price impact fee and an additive price impact fee. + + +### Linear Price Impact Fee + + +$$ +\text{Linear price impact fee coefficient} = \frac{\text{trade size}}{\text{price impact fee scalar constant}} +$$ + +$$ +\text{Final linear price impact fee} = \text{trade size} \times \text{linear price impact fee coefficient} +$$ + +
+ Linear Price Impact Fee +
+ +- The linear price impact fee scales with trade size. +- The fee increases proportionally as the trade size increases. +- Each custody (SOL, ETH, BTC) has a fixed constant value (the price impact fee scalar or `pricing.tradeImpactFeeScalar` to be exact) that determines the final linear price impact fee coefficient when calculating the linear price impact fee. + - **SOL**: [`7xS2gz2bTp3fwCC7knJvUWTEU9Tycczu6VhJYKgi1wdz`](https://solscan.io/account/7xS2gz2bTp3fwCC7knJvUWTEU9Tycczu6VhJYKgi1wdz#accountData) + - **BTC**: [`5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm`](https://solscan.io/account/5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm#accountData) + - **ETH**: [`AQCGyheWPLeo6Qp9WpYS9m3Qj479t7R636N9ey1rEjEn`](https://solscan.io/account/AQCGyheWPLeo6Qp9WpYS9m3Qj479t7R636N9ey1rEjEn#accountData) + + +The `pricing.tradeImpactFeeScalar` value is scaled to BPS format in the custody accounts. To calculate against the trade size in dollar amounts, divide the scalar value by 10,000 to match the dollar amount. + + + + +**Example: Linear Price Impact Fee Calculation** + +**Position**: SOL long +**Trade size**: $10,000 +**Calculation:** + +Linear price impact fee scalar constant, normalized for dollar amounts (refer to above): +$$ +\frac{3{,}750{,}000{,}000{,}000{,}000}{10{,}000} = 375{,}000{,}000{,}000 +$$ + +Linear price impact fee coefficient: +$$ +\frac{10{,}000}{375{,}000{,}000{,}000} = 0.000000026666667 +$$ + +Final linear price impact fee: +$$ +10{,}000 \times 0.000000026666667 = \$0.00026666667 +$$ + diff --git a/docs/perps/get-started.mdx b/docs/perps/get-started.mdx new file mode 100644 index 00000000..b4a09de2 --- /dev/null +++ b/docs/perps/get-started.mdx @@ -0,0 +1,58 @@ +--- +title: "Get Started" +description: "Get started to develop with Jupiter Perpetuals." +--- + +## API Reference + +Refer to the [Perps API Reference](/api-reference/perps) for the complete API documentation. + + +## Architecture +| Component | Description | +| :-------- | :---------- | +| [**JLP**](/docs/perps/jlp) | Jupiter Liquidity Providers | +| [**Oracles**](/docs/perps/oracles) | Price oracles for the markets | +| [**Fees**](/docs/perps/fees) | Fees for the trading operations | +| [**Liquidation**](/docs/perps/liquidation) | How liquidations are handled | +| [**Perps Program**](/docs/perps/program) | The smart contract/program of Jupiter Perpetuals | + +## Transaction Execution +Refer to the [Transaction Execution](/docs/perps/transaction-execution) guide to understand how to execute transactions for both trading, mint/burn of JLP and lending/borrowing. + +## Trading Endpoints +| Endpoint | Description | +| :------- | :---------- | +| [**Position Data**](/docs/perps/trading/position-data) | Get information and data on positions. | +| [**Position Management**](/docs/perps/trading/position-management) | Manage positions by increasing, decreasing, closing, or closing all positions. | +| [**Limit Orders**](/docs/perps/trading/limit-orders) | Create, update, or cancel limit orders. | +| [**TPSL Orders**](/docs/perps/trading/tpsl-orders) | Create, update, or cancel TPSL orders. | + +## JLP Endpoints +| Endpoint | Description | +| :------- | :---------- | +| [**JLP Info**](/docs/perps/jlp/getting-jlp) | Get information on JLP tokens. | +| [**Mint JLP**](/docs/perps/jlp/getting-jlp) | Mint JLP tokens. | +| [**Burn JLP**](/docs/perps/jlp/getting-jlp) | Burn JLP tokens. | + +## JLP Lending Endpoints +| Endpoint | Description | +| :------- | :---------- | +| [**Position Data**](/docs/perps/lending/position-data) | Get information and data on lending positions. | +| [**Position Management**](/docs/perps/lending/position-management) | Manage lending positions by depositing, borrowing, repaying, withdrawing. | + +## FAQ + + + +Test + + + +Test + + + +Test + + diff --git a/docs/perps/index.mdx b/docs/perps/index.mdx index 9abf72b6..a1bcc262 100644 --- a/docs/perps/index.mdx +++ b/docs/perps/index.mdx @@ -1,20 +1,74 @@ --- -title: "About Perps API" +title: "Overview" +sidebarTitle: "Overview" +description: "Overview of Jupiter Perpetuals where you can trade with leverage up to 250x on SOL, ETH and wBTC." --- - - **WARNING** +## Features - The Perps API is still a **work in progress**, stay tuned! - +In this overview, we will cover the core features of the Jupiter Perps +and how it differs from traditional leverage trading exchanges. - - **TIP** - - In the meantime, you can use this amazing github repository to direct Anchor IDL parse the Perps Program. + + To quickstart your developer integration, you can head over to the + [Get Started](/docs/perps/get-started) guide or dive into the + [API Reference](/api-reference/perps) for the complete API documentation. + - * Fetch Perps or JLP pool data - * Interact with the Perps Program +### Trader-to-LP Exchange +**Jupiter Liquidity Providers**: Liquidity for the Jupiter Perps is provided by the JLP Pool, which holds +SOL, ETH, wBTC, and USDC as the underlying tokens. The pool provides ample +liquidity for traders to open highly-leveraged positions, while earning an +attractive return on a portion of the trading fees. - [https://github.com/julianfssen/jupiter-perps-anchor-idl-parsing](https://github.com/julianfssen/jupiter-perps-anchor-idl-parsing) - +**Traders**: Traders can deposit collateral to enter positions and borrow the rest of +the position from the pool. Subsequently, they can manage their positions +by withdrawing collateral to close their positions fully or partially. The +Jupiter Perpetuals Exchange features a simple interface and underlying +trading mechanisms to provide a safe and seamless trading experience. + +### Pool-Based Liquidity +* Liquidity comes from the JLP pool, not from resting orders. +* Traders open and close positions directly against the pool. +* Trade size is limited only by available liquidity and position-level size constraints. +* Refer to the [JLP](/docs/perps/jlp) document for more information. + +### Oracle-Based Pricing +* All trades execute at the oracle price. +* Large trades (e.g., $10 million) do not affect the price for others. +* Prices are sourced from verified oracles and are unaffected by trade size or direction. +* Refer to the [Oracles](/docs/perps/oracles) document for more information. + +### On-Chain Position Accounts +* Each user's exposure per asset and direction (long/short) is stored as a position account on-chain. +* Multiple trades on the same side (e.g., two long SOL trades) merge into a single position. +* Opening opposite positions (e.g., closing a long by shorting) does not flip exposure; it closes the existing position and realizes PnL. +* Refer to the [Position Account](/docs/perps/position-account) document for more information. + +### Immediate-or-Revert Execution +* Every trade executes in a single transaction or fails atomically. +* No partial fills, maker/taker matching, or time-in-force orders. + +### Position-Level Risk Controls +* Before execution, every trade passes a full validation layer: + * Collateral checks: minimum margin and leverage caps. + * Pool liquidity checks: ensure sufficient tokens exist to back exposure. + * Position limits: wallet-level and pool-level maximum size caps. +* Orderbooks typically handle risk at the matching engine level; Jupiter enforces it at the position and pool level. + +### Pool-Driven Fees +* Trading fees are derived from pool mechanics, not spreads or maker/taker roles. +* Open/close/price impact fees: based on pool math (swap, borrow, and price-impact fees). +* Continuous borrow fees: accrue based on the pool's open exposure, not paid between counterparties. +* No traditional funding rates; both longs and shorts pay borrow fees to the pool. +* Refer to the [Fees](/docs/perps/fees) document for more information. + +### Collateral Model +* Longs are backed by the underlying asset (e.g., SOL, ETH, wBTC). +* Shorts are backed by USDC. +* The program handles collateral assignment automatically - traders simply supply margin in their chosen deposit asset. + +### No Synthetic Flipping +* Positions are stored on-chain as PDAs, not synthetic toggles. +* Reducing or closing exposure adjusts the position account. +* You can't accidentally “flip” from long to short via over-selling; you can only close or reduce up to your existing position size. diff --git a/docs/perps/jlp-lend.mdx b/docs/perps/jlp-lend.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/perps/jlp-lend/position-data.mdx b/docs/perps/jlp-lend/position-data.mdx new file mode 100644 index 00000000..9ab4f4a8 --- /dev/null +++ b/docs/perps/jlp-lend/position-data.mdx @@ -0,0 +1,5 @@ +--- +title: "Position Data" +description: "Get information and data on JLP lending positions." +sidebarTitle: "JLP Lend Position Data" +--- \ No newline at end of file diff --git a/docs/perps/jlp-lend/position-management.mdx b/docs/perps/jlp-lend/position-management.mdx new file mode 100644 index 00000000..6bc602c0 --- /dev/null +++ b/docs/perps/jlp-lend/position-management.mdx @@ -0,0 +1,5 @@ +--- +title: "Position Management" +description: "Manage JLP lending positions by depositing, borrowing, repaying, withdrawing." +sidebarTitle: "JLP Lend Position Management" +--- \ No newline at end of file diff --git a/docs/perps/jlp.mdx b/docs/perps/jlp.mdx new file mode 100644 index 00000000..04cc061c --- /dev/null +++ b/docs/perps/jlp.mdx @@ -0,0 +1,383 @@ +--- +title: "JLP" +description: "Understand Jupiter Liquidity Providers (JLP) and how they work." +--- + +JLP (Jupiter Liquidity Provider) is the liquidity pool token that powers Jupiter Perpetuals. The JLP pool serves as the counterparty for all perpetual trades, providing liquidity for traders to open highly-leveraged positions up to 250x on SOL, WETH, and WBTC. + +When you deposit assets into the JLP pool, you receive JLP tokens representing your share of the pool. As a liquidity provider, you earn 75% of fees generated by the perpetuals exchange, these fees are automatically and directly accrued into the JLP pool. + +## How JLP Works with Perps + +The JLP pool operates as a **trader-to-LP exchange model**, where: + +### Pool-Based Liquidity +- **Single Liquidity Pool**: All liquidity comes from the JLP pool, not from resting orders or order books +- **Direct Trading**: Traders open and close positions directly against the pool +- **Unlimited Size**: Trade size is limited only by available pool liquidity and position-level constraints +- **Oracle-Based Pricing**: All trades execute at oracle prices, ensuring large trades don't affect prices for others + +### Pool Composition +The JLP pool manages several custodies (tokens) for liquidity providers: + +| Token | Custody Address | +|-------|----------------| +| **SOL** (Wrapped SOL) | [`7xS2gz2bTp3fwCC7knJvUWTEU9Tycczu6VhJYKgi1wdz`](https://solscan.io/account/7xS2gz2bTp3fwCC7knJvUWTEU9Tycczu6VhJYKgi1wdz) | +| **WWETH** (Wrapped WETHereum) | [`AQCGyheWPLeo6Qp9WpYS9m3Qj479t7R636N9ey1rEjEn`](https://solscan.io/account/AQCGyheWPLeo6Qp9WpYS9m3Qj479t7R636N9ey1rEjEn) | +| **WBTC** (Wrapped Bitcoin) | [`5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm`](https://solscan.io/account/5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm) | +| **USDC** (USD Coin) | [`G18jKKXQwBbrHeiK3C9MRXhkHsLHf7XgCSisykV46EZa`](https://solscan.io/account/G18jKKXQwBbrHeiK3C9MRXhkHsLHf7XgCSisykV46EZa) | + +Each asset has a **target weightage** that the pool maintains through rebalancing mechanisms. The pool uses these assets to: +- Provide collateral backing for long positions (SOL, WWETH, WBTC) +- Provide collateral backing for short positions (USDC) +- Cover trader profits when positions are closed +- Earn fees for liquidity providers through trading and borrowing + +### How Traders Interact with JLP +1. **Opening Positions**: When a trader opens a leveraged position, they deposit collateral and borrow the remaining position size from the JLP pool +2. **Closing Positions**: When positions are closed, profits are paid from the pool's assets, while losses are added to the pool +3. **Borrow Fees**: Traders pay continuous borrow fees to the pool based on their position size and the pool's utilization rate +4. **Trading Fees**: All open/close fees flow into the pool (with 25% going to the protocol) + +The pool's AUM (Assets Under Management) represents the total value of assets in the pool, calculated as: + +$$ +\text{AUM} = \text{USD value of owned tokens} - \text{USD value reserved for trader profits} +$$ + +--- + +## Becoming a Liquidity Provider + + +To become a JLP liquidity provider, you need to mint JLP tokens by depositing one of the supported assets (SOL, WETH, WBTC, USDC) into the pool. +- JLP can be acquired through swapping on jup.ag which finds the best price either by other DEXes or the pool itself. +- Or through the [JLP Earn](https://jup.ag/perps/jlp-earn), which mints or burns JLP tokens directly from the pool. + +For detailed instructions on minting and burning JLP tokens, refer to the [Getting JLP](/docs/perps/jlp/getting-jlp) guide. + + +--- + +## JLP Lending + + +JLP tokens can be used as collateral to borrow USDC from the pool, creating additional utility and yield opportunities for liquidity providers. + +This feature allows liquidity providers to: +- Access liquidity without selling their JLP position +- Potentially increase their yield through leverage +- Maintain exposure to JLP returns while borrowing for other purposes + +For detailed information on JLP lending mechanics, position management, and borrowing limits, refer to the [JLP Lend](/docs/perps/jlp-lend) documentation. + + +--- + +## Economics + +### Key Concepts + +With the introduction of USDC lending from the JLP, the following definitions represent the true state of the custody accounts: + +**Debt** + +$$ +\text{debt} = \frac{\max\left(\text{custody.debt} - \text{custody.borrowLendInterestsAccrued},\ 0\right)}{1{,}000{,}000{,}000} +$$ + +The custody account's `debt` field represents the tokens borrowed from the custody. +This gives the pure debt amount without accumulated interests. + + +**Theoretically Owned** + +$$ +\text{theoreticallyOwned} = \text{custody.assets.owned} + \text{debt}(\text{custody}) +$$ + +This represents the "true" owned token amount by the custody. +Borrowed tokens are not stored in `custody.assets.owned`, so this calculation provides the actual value of assets owned by the pool. + + +**Total Locked** + +$$ +totalLocked = custody.assets.locked + debt(custody) +$$ + +This represents the "true" locked token amount by the custody, including borrowed tokens: +Similar to the theoretically owned value above, this returns the actual locked token amount by the custody. + + +--- + +### Assets Under Management + +The AUM for each custody account in the pool is calculated as follows. + +**Stablecoins (USDC)** + +$$ +\text{aumUsd} = \text{theoreticallyOwned} \times \text{currentTokenPrice} +$$ + + +**Non-stablecoins (SOL, WETH, WBTC)** +1. First, calculate the global short position profit/loss (Unrealized PNL in USD). +2. Second, check if the short traders are in profit. +3. Finally, calculate the assets under management. + +$$ +\text{unrealizedShortPNL} = \frac{\text{shortSize} \times \left| \text{shortAvgPrice} - \text{currentTokenPrice} \right|}{\text{shortAvgPrice}} +$$ + +1. Global short position profit/loss (Unrealized PNL in USD): + - shortSize = `custody.assets.globalShortSizes` + - shortAvgPrice = `custody.assets.globalShortAveragePrices` + + + +2. Check if `shortAvgPrice > currentTokenPrice`. If true, short traders are in profit, otherwise they are in loss. + + + +$$ +\text{aumUsd} = \text{custody.assets.guaranteedUsd} \pm \text{unrealizedShortPNL} +$$ + +3. Assets under management for each asset: + + - If the short traders are in profit, subtract `unrealizedShortPNL` from `aumUsd`. + - Otherwise, add `unrealizedShortPNL` to `aumUsd`. + + +- The `guaranteed_usd` value in each custody account represents an estimate of the total size of all long positions. It is only an estimate as `guaranteed_usd` is only updated when positions are updated (i.e. opening / closing positions, updating collateral). It does not update in real-time when asset prices change. + +- The `guaranteed_usd` value is used to calculate the pool's AUM as well as the overall PNL for all long positions efficiently. + + + +**Total AUM** + +The Total AUM is then calculated as the sum of all the custodies' AUM. + + +$$ +\text{totalAumUsd} = \sum \text{aumUsd} +$$ + + +--- + +### Virtual Price and Market Price + +**Virtual Price** + +$$ +\text{virtualPrice} = \frac{\text{totalAumUsd}}{\text{jlpTotalSupply}} +$$ + +The virtual price represents the intrinsic value of each JLP token based on the pool's underlying assets. + + +**Market Price** + +$$ +\text{marketPrice} = \text{virtualPrice} + \text{marketAssignedPremium} +$$ + +The market price of JLP is determined by supply and demand on the open market (e.g., through DEX swaps). It can differ from the virtual price depending on market conditions. + +When the AUM limit is hit and deposits are restricted, liquidity providers will seek for circulating JLP in the open market, causing demand for JLP to exceed supply, leading to a market price premium above the virtual price. + + +You may sell your JLP at market price any time (by swapping it with other tokens on DEXes). However, if Market Price is below the Virtual Price, your JLP will be redeemed (burned) at the virtual price instead. + + + +--- + +### APR/APY Calculation + +The APR and APY for JLP are updated weekly based on the fees generated by the pool (in USD) from perps trading activities. 75% of these fees are distributed to JLP holders, excluding asset appreciation and traders' PnL. Fees are reinvested by being redeposited into the pool every hour. You can refer to [JLP Earn](https://jup.ag/perps/jlp-earn) page for more details. + +**APR Formula** + + +$$ +\text{APR} = \frac{\text{feesDistributedToJLP}}{\text{totalAumUsd}} +$$ + +- $\text{feesDistributedToJLP}$ = total USD value of 75% of perps trading fees generated over the last 7 days (excluding protocol share). +- $\text{totalAumUsd}$ = current total AUM of the pool. +- The APR is expressed as an annualized rate, updated weekly based on the prior week's fees. + + +**APY Formula** + + +$$ +\text{APY} = \left(1 + \frac{\text{APR}}{52}\right)^{52} - 1 +$$ + +- Fees are automatically compounded every hour, but the website calculates APY with a weekly compounding interval ($n = 52$). +- This APY is denominated in USD and reflects only the compounded yield from 75% of perps trading fees, not asset price appreciation or trader PnL. +- $\text{APR}$ is taken from the previous formula. +- $52$ is the number of compounding periods per year (weekly). + + +### Pool Rebalancing + +The JLP pool maintains target weightages for each asset to ensure balanced exposure and optimal risk management. Each asset has a **target weightage**—the ideal proportion relative to the pool's total AUM—and a **current weightage** that reflects the actual proportion at any given time. + +When swaps occur between JLP assets, they affect each asset's weightage: + +- **Swapping into the pool** (e.g., depositing SOL) increases that asset's current weightage +- **Swapping out of the pool** (e.g., withdrawing SOL) decreases that asset's current weightage + +For example, swapping 100 SOL for 100 USDC reduces SOL's pool size (and current weightage) while increasing USDC's pool size (and current weightage). + +The pool uses dynamic fee adjustments to incentivize swaps that move assets toward their target weightages, while discouraging swaps that move them further away. This mechanism protects JLP holders by maintaining pool balance and rewards them when swaps help rebalance the pool. For details on how fees adjust, see the [Fees](/docs/perps/fees) documentation. +- **Risk Management**: Balanced exposure prevents over-concentration in any single asset, reducing vulnerability to extreme price movements +- **Liquidity Optimization**: Proper asset distribution ensures the pool can efficiently serve both long and short traders +- **Fee Generation**: Rebalanced pools can better accommodate trading activity, leading to more consistent fee generation + +--- + +### Global Realized PNL + +1. Longs: uses locked tokens value minus guaranteed USD (collateral-based). +2. Shorts: uses size × absolute price difference divided by average entry price (price-difference-based). + + +Most accurate way to calculate the unrealized PNL for all open long/short positions is to loop through all open positions (by fetching them from onchain accounts) and use the unrealized PNL calculation shown below. + + +**Calculating Global Unrealized PNL for Longs** + +To get an estimate of the global unrealized PNL for longs: + + + + +$$ +\text{guaranteedUsd} = \text{custody.assets.guaranteedUsd} +$$ + +- [Using the custody account](/docs/perps/program/custody-account) +- Get the `assets.guaranteedUsd` field which stores the value of + `position.sizeUsd - position.collateralUsd` for all open long positions for the custody. +- Note that a position's `sizeUsd` value is only updated when a trade is made, which is the + same for `guaranteedUsd` as well. It does *not* update in real-time when the custody's price changes. + + + + + +$$ +\text{lockedTokensUsd} = \text{custody.assets.locked} \times \text{currentTokenPriceUsd} +$$ + +- Multiply `custody.assets.locked` by the custody's current price to get the USD value of the tokens locked + by the pool to pay off traders' profits + + + + + +$$ +\text{globalUnrealizedLongPNL} = \text{lockedTokensUsd} - \text{guaranteedUsd} +$$ + +- Subtract `guaranteedUsd` from `lockedTokensUsd` to get the estimate of unrealized PNL for all open long positions. +- Note that the final value is greater than the actual unrealized PNL as it includes traders' collateral + + + + + +**Calculating Global Unrealized PNL for Shorts** + +To get an estimate of the global unrealized PNL for shorts: + + + + +$$ +\text{globalShortSizes} = \text{custody.assets.globalShortSizes} +$$ + +$$ +\text{globalShortAveragePrices} = \text{custody.assets.globalShortAveragePrices} +$$ + +- [Using the custody account](/docs/perps/program/custody-account) +- Get the `assets.globalShortSizes` field which represents the total USD value of all open short positions. +- Get the `assets.globalShortAveragePrices` field which represents the average entry price (in USD) of all open short positions. + + + + + +$$ +\text{priceDifferenceRatio} = \frac{ + \left| \text{globalShortAveragePrices} - \text{currentTokenPriceUsd} \right| +}{ + \text{globalShortAveragePrices} +} +$$ + +- Calculate the absolute price difference ratio between the average entry price and the current token price. +- This represents the percentage change in price since the average entry. + + + + + +$$ +\text{globalUnrealizedShortPNL} = \text{globalShortSizes} \times \text{priceDifferenceRatio} +$$ + +- Multiply `globalShortSizes` by `priceDifferenceRatio` to get the estimate of unrealized PNL for all open short positions. + + + + +--- + +### Yield + +The JLP token adopts a growth-focused approach, similar to accumulating ETFs like VWRA or ARKK. Rather than distributing yield through airdrops or additional token mints, the JLP token's value is designed to appreciate over time. This appreciation is driven by the growth of the JLP pool's AUM, which is used to derive the virtual price as shown above. + +**75% of all fees generated** from Jupiter Perpetuals trading, token swaps, and JLP minting/burning are reinvested directly into the JLP pool. This mechanism continuously enhances the pool's liquidity and value for token holders. + +**The remaining 25% of fees** is allocated to Jupiter as protocol fees, supporting ongoing development and maintenance. + +For example, if trading activities generate 10 SOL in fees, 7.5 SOL would be added to the JLP pool, increasing its SOL holdings and AUM. + +Fees generated by the pool are reinvested directly back into the JLP pool, mirroring how accumulating ETFs reinvest dividends. This reinvestment strategy compounds the pool's growth, steadily increasing the JLP token's price and intrinsic value. + +--- + +### Exposure + +The intrinsic value of the JLP token is linked to the price movements of the liquidity pool's underlying tokens (SOL, WETH, BTC, USDC). + +As a JLP holder, your portfolio is exposed to market movements, particularly to the performance of the non-stablecoin tokens: SOL, WETH, and BTC. If these tokens decrease in price, the value of your JLP position will likely decrease as well. + +That said, JLP holders earn yield from fees generated by trading activities. When traders incur losses, these are reinvested into the JLP pool, benefiting JLP holders. Conversely, when traders profit, it comes at the expense of the JLP pool. + +The JLP usually outperforms its underlying assets during sideways or bearish market conditions since traders often struggle to be profitable in bear markets. However, during strong bull markets, the situation can reverse. Traders may open more long positions which can lead to trader profitability at the expense of JLP holders. + +--- + +### Risk Considerations + +JLP holders are exposed to risks that can impact their portfolio: + +| **Risk** | **Description** | +|---------------------------|-----------------| +| **Market Volatility** | Rapid price movements can negatively impact the JLP. Extreme market events or black swan scenarios may cause correlations between assets to break down, potentially amplifying losses instead of mitigating them. | +| **Counterparty Risk** | The JLP pool poses a counterparty risk to JLP holders, as smart contract vulnerabilities or platform issues could potentially impact the ability to maintain or close hedge positions. That said, Jupiter is working with leading firms in the field to audit and maintain our contracts to protect the Jupiter Perpetuals exchange and JLP holders. | +| **Opportunity Cost** | Capital allocated to acquiring JLP could potentially earn higher returns if allocated elsewhere. In bull markets for example, JLP may underperform compared to simply holding the underlying assets. JLP holders should thoroughly research and understand the benefits and risks of the JLP token before acquiring them. | diff --git a/docs/perps/jlp/getting-jlp.mdx b/docs/perps/jlp/getting-jlp.mdx new file mode 100644 index 00000000..666ae69e --- /dev/null +++ b/docs/perps/jlp/getting-jlp.mdx @@ -0,0 +1,5 @@ +--- +title: "Getting JLP" +description: "Get information, mint and burn JLP tokens." +sidebarTitle: "Getting JLP" +--- \ No newline at end of file diff --git a/docs/perps/liquidation.mdx b/docs/perps/liquidation.mdx new file mode 100644 index 00000000..366d492c --- /dev/null +++ b/docs/perps/liquidation.mdx @@ -0,0 +1,4 @@ +--- +title: "Liquidation" +description: "How liquidations are handled." +--- \ No newline at end of file diff --git a/docs/perps/oracles.mdx b/docs/perps/oracles.mdx new file mode 100644 index 00000000..afdbb1a6 --- /dev/null +++ b/docs/perps/oracles.mdx @@ -0,0 +1,4 @@ +--- +title: "Oracles" +description: "Understand the oracles used for the pricing of the markets." +--- \ No newline at end of file diff --git a/docs/perps/custody-account.mdx b/docs/perps/program/custody-account.mdx similarity index 100% rename from docs/perps/custody-account.mdx rename to docs/perps/program/custody-account.mdx diff --git a/docs/perps/program/index.mdx b/docs/perps/program/index.mdx new file mode 100644 index 00000000..cdc9de35 --- /dev/null +++ b/docs/perps/program/index.mdx @@ -0,0 +1,4 @@ +--- +title: "Overview" +description: "Overview of the Jupiter Perps Program." +--- \ No newline at end of file diff --git a/docs/perps/pool-account.mdx b/docs/perps/program/pool-account.mdx similarity index 100% rename from docs/perps/pool-account.mdx rename to docs/perps/program/pool-account.mdx diff --git a/docs/perps/position-account.mdx b/docs/perps/program/position-account.mdx similarity index 100% rename from docs/perps/position-account.mdx rename to docs/perps/program/position-account.mdx diff --git a/docs/perps/position-request-account.mdx b/docs/perps/program/position-request-account.mdx similarity index 100% rename from docs/perps/position-request-account.mdx rename to docs/perps/program/position-request-account.mdx diff --git a/docs/perps/trading/limit-orders.mdx b/docs/perps/trading/limit-orders.mdx new file mode 100644 index 00000000..b47fa0a9 --- /dev/null +++ b/docs/perps/trading/limit-orders.mdx @@ -0,0 +1,4 @@ +--- +title: "Limit Orders" +description: "Create, update, or cancel limit orders." +--- \ No newline at end of file diff --git a/docs/perps/trading/position-data.mdx b/docs/perps/trading/position-data.mdx new file mode 100644 index 00000000..11cd4ab4 --- /dev/null +++ b/docs/perps/trading/position-data.mdx @@ -0,0 +1,4 @@ +--- +title: "Position Data" +description: "Get information and data on trading positions." +--- \ No newline at end of file diff --git a/docs/perps/trading/position-management.mdx b/docs/perps/trading/position-management.mdx new file mode 100644 index 00000000..db74839d --- /dev/null +++ b/docs/perps/trading/position-management.mdx @@ -0,0 +1,4 @@ +--- +title: "Position Management" +description: "Manage trading positions by increasing, decreasing, closing, or closing all positions." +--- \ No newline at end of file diff --git a/docs/perps/trading/tpsl-orders.mdx b/docs/perps/trading/tpsl-orders.mdx new file mode 100644 index 00000000..2df23250 --- /dev/null +++ b/docs/perps/trading/tpsl-orders.mdx @@ -0,0 +1,4 @@ +--- +title: "TPSL Orders" +description: "Create, update, or cancel TPSL orders." +--- \ No newline at end of file diff --git a/docs/perps/transaction-execution.mdx b/docs/perps/transaction-execution.mdx new file mode 100644 index 00000000..6197a102 --- /dev/null +++ b/docs/perps/transaction-execution.mdx @@ -0,0 +1,188 @@ +--- +title: "Transaction Execution" +description: "Understand how to execute transactions for both trading, mint/burn of JLP and lending/borrowing." +--- + +## Overview + +Many operations in the Jupiter Perps API require **keeper-signed transactions** to be executed. These transactions cannot be submitted directly through standard Solana RPC calls. Instead, they must be sent to the `/transaction/execute` endpoint, where a keeper will sign and execute them on your behalf. + + +Refer to the [Transaction Execution](/api-reference/perps/post-transaction-execute) endpoint for the complete API documentation. + + +## When to Use Transaction Execution + +All transactional operations in the Jupiter Perps API require the transaction execution endpoint. The following operations may require the transaction execution endpoint: + +- **Position Management** (`increase-position`, `decrease-position`) +- **Limit Orders** (`limit-order`) +- **TPSL Orders** (`tpsl`, `tpsl-with-fee`) +- And others + +When you call any of these operation endpoints, the response will include: + +- `serializedTxBase64`: The serialized transaction ready to be signed +- `transactionType`: Either `"legacy"` or `"instant"` +- `requireKeeperSignature`: Boolean indicating if keeper signature is required + +## Transaction Types + +### Instant Transactions + +When `transactionType` is `"instant"` or `requireKeeperSignature` is `true`, you **must** use the `/transaction/execute` endpoint. These transactions require a keeper to sign and execute them. + +### Legacy Transactions + +When `transactionType` is `"legacy"` and `requireKeeperSignature` is `false`, you can submit the transaction directly through standard Solana RPC methods (e.g., `sendTransaction`). + +## Workflow + +### Step 1: Create the Transaction + +Call the appropriate operation endpoint (e.g., `POST /tpsl`, `POST /positions/increase`) with your parameters: + +```typescript +const response = await fetch('https://api.jup.ag/perps/v1/tpsl', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + walletAddress: 'YOUR_WALLET_ADDRESS', + positionPubkey: 'POSITION_PUBKEY', + tpsl: [/* your TPSL config */], + transactionType: 'instant' // or 'mixed' + }) +}); + +const data = await response.json(); +``` + +### Step 2: Check Transaction Type + +Examine the response to determine how to proceed: + +```typescript +if (data.transactionType === 'instant' || data.requireKeeperSignature) { + // Proceed to Step 3 - use transaction execution endpoint +} else { + // Submit directly via RPC + await connection.sendRawTransaction(transaction.serialize()); +} +``` + +### Step 3: Sign the Transaction + +Deserialize and sign the transaction with your wallet: + +```typescript +import { Transaction } from '@solana/web3.js'; + +const transaction = Transaction.from( + Buffer.from(data.serializedTxBase64, 'base64') +); + +// Sign with your wallet +transaction.sign(wallet); + +// Serialize the signed transaction +const signedSerializedTx = transaction.serialize({ + requireAllSignatures: false, + verifySignatures: false +}); + +const signedTxBase64 = Buffer.from(signedSerializedTx).toString('base64'); +``` + +### Step 4: Execute via Transaction Endpoint + +Send the signed transaction to the `/transaction/execute` endpoint with the appropriate `action`: + +```typescript +const executeResponse = await fetch('https://api.jup.ag/perps/v1/transaction/execute', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + action: 'tpsl', // or 'limit-order', 'increase-position', etc. + serializedTxBase64: signedTxBase64 + }) +}); + +const result = await executeResponse.json(); +// result.txid contains the transaction ID +``` + +## Supported Actions + +The `action` parameter in `/transaction/execute` must match one of these values: + +- `tpsl` - Take profit / Stop loss orders +- `tpsl-with-fee` - TPSL orders with integrator fees +- `limit-order` - Limit orders +- `increase-position` - Increase position size +- `increase-position-with-fee` - Increase position with integrator fees +- `decrease-position` - Decrease position size +- `decrease-position-with-fee` - Decrease position with integrator fees + +## Important Notes + +1. **Transaction Expiry**: Transactions include blockhash metadata (`txMetadata`) that expires. Ensure you execute the transaction promptly after receiving it. + +2. **Serializing Transaction**: When serializing transactions for the execution endpoint, use `requireAllSignatures: false` since the keeper will add its signature. + +3. **Error Handling**: The execution endpoint may return errors if: + - The transaction is invalid or expired + - The keeper cannot execute the transaction + - The action type doesn't match the transaction + +4. **Transaction ID**: Upon successful execution, you'll receive a `txid` that you can use to track the transaction on-chain. + +## Example: Complete TPSL Workflow + +```typescript expandable +// 1. Create TPSL request +const createResponse = await fetch('https://api.jup.ag/perps/v1/tpsl', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + walletAddress: wallet.publicKey.toString(), + positionPubkey: positionPubkey, + tpsl: [{ + requestType: 'tp', + triggerPrice: '20000000', // $20.00 + receiveToken: 'USDC', + entirePosition: true + }], + transactionType: 'instant' + }) +}); + +const createData = await createResponse.json(); + +// 2. Check if execution endpoint is needed +if (createData.requireKeeperSignature) { + // 3. Deserialize and sign + const transaction = Transaction.from( + Buffer.from(createData.serializedTxBase64, 'base64') + ); + transaction.sign(wallet); + + const signedTxBase64 = Buffer.from( + transaction.serialize({ requireAllSignatures: false }) + ).toString('base64'); + + // 4. Execute via transaction endpoint + const executeResponse = await fetch('https://api.jup.ag/perps/v1/transaction/execute', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + action: 'tpsl', + serializedTxBase64: signedTxBase64 + }) + }); + + const executeResult = await executeResponse.json(); + console.log('Transaction ID:', executeResult.txid); +} else { + // Submit directly via RPC +} +``` diff --git a/docs/ultra/get-started.mdx b/docs/ultra/get-started.mdx index dd8531c8..edd9db7e 100644 --- a/docs/ultra/get-started.mdx +++ b/docs/ultra/get-started.mdx @@ -3,16 +3,23 @@ title: "Get Started" description: "Get started with the Ultra Swap API." --- -## Overview - -| Step | Endpoint | Description | -| :--- | :------- | :---------- | -| 1 | [**Get Order**](/docs/ultra/get-order) | Request for a quote and swap transaction. | -| 2 | [**Execute Order**](/docs/ultra/execute-order) | Sign and execute the swap transaction. | -| - | [**Search Token**](/docs/ultra/search-token) | Search for a token by its symbol, name or mint address. | -| - | [**Get Holdings**](/docs/ultra/get-holdings) | Request for token balances of an account. | -| - | [**Get Shield**](/docs/ultra/get-shield) | Enhanced security feature to provide critical token information contributing to better informed trading decisions. | -| - | [**API Reference**](/api-reference/ultra) | Reference for the Ultra Swap API endpoints. | +## API Reference + +Refer to the [Ultra Swap API Reference](/api-reference/ultra) for the complete API documentation. + + +## Swap Endpoints +| Endpoint | Description | +| :------- | :---------- | +| [**Get Order**](/docs/ultra/get-order) | Request for a quote and swap transaction. | +| [**Execute Order**](/docs/ultra/execute-order) | Sign and execute the swap transaction. | + +## Data Endpoints +| Endpoint | Description | +| :------- | :---------- | +| [**Search Token**](/docs/ultra/search-token) | Search for a token by its symbol, name or mint address. | +| [**Get Holdings**](/docs/ultra/get-holdings) | Request for token balances of an account. | +| [**Get Shield**](/docs/ultra/get-shield) | Enhanced security feature to provide critical token information contributing to better informed trading decisions. | ## Guides diff --git a/openapi-spec/perps/perps.yaml b/openapi-spec/perps/perps.yaml new file mode 100644 index 00000000..decb4358 --- /dev/null +++ b/openapi-spec/perps/perps.yaml @@ -0,0 +1,6111 @@ +openapi: 3.1.0 +info: + title: Jupiter Perpetuals API + version: 1.0.0 + description: | + Jupiter Perpetuals API Schema +servers: + - url: https://api.jup.ag/perps/v1 + description: Jupiter Perpetuals API endpoint + + +paths: + /market-stats: + description: Fetches 24-hour market stats for the given market + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: mint + description: Mint address for the given market + schema: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: Mint address for the given market + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + price: + type: string + description: Current USD price for the given market + example: '123.00' + priceChange24H: + type: string + description: Current USD 24-hour price change (%) for the given market + example: '-20.00' + priceHigh24H: + type: string + description: USD value for the 24-hour high price for the given market + example: '123.00' + priceLow24H: + type: string + description: USD value for the 24-hour low price for the given market + example: '123.00' + volume: + type: string + description: >- + USD value for the 24-hour total volume for the given + market + example: '48123049.00' + required: + - price + - priceChange24H + - priceHigh24H + - priceLow24H + - volume + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /orders/expired: + description: Fetches expired orders for the wallet address + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: walletAddress + description: Public key for the wallet to fetch expired orders + schema: + type: string + description: Public key for the wallet to fetch expired orders + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + serializedTxs: + type: array + items: + type: object + properties: + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) + containing the instructions and given parameters for + the close position request instruction. The + transaction can be deserialized, signed by the owner + of `walletAddress` and submitted onchain to close + the position request + positionRequestPubkey: + type: string + description: The public key / address for the position request. + required: + - serializedTxBase64 + - positionRequestPubkey + description: >- + An array of base64-serialized transactions and the + `positionRequestPubkey` to close all expired orders. + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + close position request transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed close position request transaction. + required: + - blockhash + - lastValidBlockHeight + description: >- + Contains blockhash metadata for the serialized transaction + to submit and confirm the transactions. + required: + - serializedTxs + - txMetadata + description: >- + An array of base64-serialized transactions and transaction + metadata to close all expired orders. + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /orders/limit: + description: Returns a serialized transaction to create a limit order. + delete: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + positionRequestPubkey: + type: string + description: >- + Public key / account address for the position request + account for the limit order. + required: + - positionRequestPubkey + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the close limit + order request. The transaction can be deserialized, signed + by the owner of `walletAddress` and submitted onchain to + execute the close limit order request + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the + transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + positionPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + positionRequestPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position request. Use this address to find the + position request account onchain + requireKeeperSignature: + type: + - boolean + - 'null' + description: '' + required: + - serializedTxBase64 + - txMetadata + - positionPubkey + - positionRequestPubkey + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + get: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + walletAddress: + type: string + description: Public key for the wallet to limit orders + required: + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + count: + type: number + dataList: + type: array + items: + type: object + properties: + collateralMint: + type: string + description: >- + The mint address for the limit order's collateral + token / custody + collateralCustody: + type: string + description: The public key for the collateral custody account + collateralUsd: + type: string + description: >- + The collateral value (USD) expressed as a raw + integer with 6 decimal places. + example: '1234000000' + collateralUsdAtTriggerPrice: + type: string + description: >- + The collateral value (USD) at the trigger price (raw + value with 6 decimal places). + example: '1234000000' + collateralTokenAmount: + type: string + description: >- + The collateral amount for the limit order scaled to + the token mint's decimals. + custody: + type: string + description: The mint address for the limit order custody + executed: + type: boolean + description: >- + `executed` is true when the limit order has been + executed, `false` otherwise. + inputMint: + type: string + description: >- + The mint address for the token used to create the + limit order. + liquidationPriceUsd: + type: string + description: >- + The liquidation price (USD) expressed as a raw + integer with 6 decimal places. + example: '13240000' + marketMint: + type: string + description: >- + The mint address for the limit order's token / + custody. + maxSizeUsdDelta: + type: string + description: >- + The maximum size (USD) for the limit order (raw + value with 6 decimal places). + example: '1234000000' + minSizeUsdDelta: + type: string + description: >- + The minimum size (USD) for the limit order (raw + value with 6 decimal places). + example: '1234000000' + openTime: + type: string + description: The UNIX timestamp when the limit order was created + positionPubkey: + type: string + description: >- + The public key / account address for the limit + order's open position + positionRequestPubkey: + type: string + description: >- + The public key / account address for the limit + order's position request + side: + type: string + enum: + - long + - short + sizeUsdDelta: + type: string + description: >- + The size (USD) of the limit order (raw value with 6 + decimal places). + triggerPrice: + type: + - string + - 'null' + description: >- + The price (USD) at which the limit order is executed + (raw value with 6 decimal places). + triggerToLiquidationPercent: + type: + - string + - 'null' + description: >- + Percentage buffer between the limit order trigger + price and position liquidation price. Calculated as + ((triggerPrice - liquidationPrice) / + liquidationPrice) * 100. + example: '5.75' + required: + - collateralMint + - collateralCustody + - collateralUsd + - collateralUsdAtTriggerPrice + - collateralTokenAmount + - custody + - executed + - inputMint + - liquidationPriceUsd + - marketMint + - maxSizeUsdDelta + - minSizeUsdDelta + - openTime + - positionPubkey + - positionRequestPubkey + - side + - sizeUsdDelta + - triggerPrice + - triggerToLiquidationPercent + required: + - count + - dataList + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + asset: + type: string + enum: + - BTC + - ETH + - SOL + description: The asset or market to trade against for the limit order. + example: SOL + includeSerializedTx: + type: boolean + default: true + description: >- + Sets whether to return a serialized transaction + (`serializedTxBase64`) in the response. + inputToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: >- + The token symbol for the input token used to fund the limit + order. + example: USDC + inputTokenAmount: + type: string + description: >- + The amount of tokens for the input token. NOTE: The token + amount needs to be an integer and must conform to the token + mint decimals specified onchain. For example, to deposit 1 + SOL, the value would be '1000000000' (9 decimals). + example: '1000000000' + leverage: + type: string + description: >- + Leverage of the limit order. Either provide leverage or + sizeUsdDelta. + example: '10' + side: + type: string + enum: + - long + - short + description: Required when creating a limit order request. + sizeUsdDelta: + type: string + description: >- + The amount in USD for the size of the limit order (raw value + with 6 decimal places). Either provide leverage or + sizeUsdDelta. + example: '10000000' + triggerPrice: + type: string + description: >- + Trigger price at which the limit order will be executed (raw + value with 6 decimal places). For example, to set a trigger + price of $20, pass in 20000000. + example: '20000000' + walletAddress: + type: string + description: >- + The wallet address / public key for the trader. Required + when creating a limit order that returns a serialized + transaction. + required: + - asset + - inputToken + - inputTokenAmount + - side + - triggerPrice + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + quote: + type: object + properties: + averagePriceUsd: + type: string + description: >- + The average price for the position in USD (raw value + with 6 decimal places) + example: '10000000' + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '1124450000' + leverage: + type: string + description: The leverage amount for the position + example: '2.99' + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + openFeeUsd: + type: string + description: >- + The total fee in USD for opening the position or + depositing collateral including base fees, borrowing + fees, and price impact fees (raw value with 6 decimal + places) + example: '100000' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + depositing collateral to the position (raw value with + 6 decimal places) + example: '100000' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + increase (raw value with 6 decimal places) + example: '100000000' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the increase (raw value with 6 decimal places) + example: '10000000' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for opening the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '100' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee in USD for opening the position + based on the position size (raw value with 6 decimal + places). For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '1124450000' + sizeTokenDelta: + type: string + description: >- + The change in the position's size in the token amount + for the position's collateral token. + example: '14420000' + required: + - averagePriceUsd + - collateralUsdDelta + - leverage + - liquidationPriceUsd + - openFeeUsd + - outstandingBorrowFeeUsd + - positionCollateralUsd + - positionSizeUsd + - priceImpactFeeBps + - priceImpactFeeUsd + - side + - sizeUsdDelta + - sizeTokenDelta + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the limit order. The + transaction can be deserialized, signed by the owner of + `walletAddress` and submitted onchain to execute the + request + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + limit order transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed limit order transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for creating the position + request (1 SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - positionPubkey + - quote + - serializedTxBase64 + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + patch: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + positionRequestPubkey: + type: string + description: The public key for the limit order position request. + triggerPrice: + type: string + description: >- + Trigger price at which the limit order will be executed (raw + value with 6 decimal places). For example, to set a trigger + price of $20, pass in 20000000. + example: '20000000' + required: + - positionRequestPubkey + - triggerPrice + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + positionRequestPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position request. Use this address to find the + position request account onchain + quote: + type: object + properties: + averagePriceUsd: + type: string + description: >- + The average price for the position in USD (raw value + with 6 decimal places) + example: '10000000' + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '1124450000' + leverage: + type: string + description: The leverage amount for the position + example: '2.99' + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + openFeeUsd: + type: string + description: >- + The total fee in USD for opening the position or + depositing collateral including base fees, borrowing + fees, and price impact fees (raw value with 6 decimal + places) + example: '100000' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + depositing collateral to the position (raw value with + 6 decimal places) + example: '100000' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + increase (raw value with 6 decimal places) + example: '100000000' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the increase (raw value with 6 decimal places) + example: '10000000' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for opening the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '100' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee in USD for opening the position + based on the position size (raw value with 6 decimal + places). For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '1124450000' + sizeTokenDelta: + type: string + description: >- + The change in the position's size in the token amount + for the position's collateral token. + example: '14420000' + required: + - averagePriceUsd + - collateralUsdDelta + - leverage + - liquidationPriceUsd + - openFeeUsd + - outstandingBorrowFeeUsd + - positionCollateralUsd + - positionSizeUsd + - priceImpactFeeBps + - priceImpactFeeUsd + - side + - sizeUsdDelta + - sizeTokenDelta + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the update limit + order request. The transaction can be deserialized, signed + by the owner of `walletAddress` and submitted onchain to + execute the update limit order request + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + limit order transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed limit order transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for creating the position + request (1 SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - positionPubkey + - positionRequestPubkey + - quote + - serializedTxBase64 + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions: + description: Fetches the open positions for the given wallet address + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: includeClosedPositions + description: Set to true to return closed positions + schema: + type: boolean + default: false + description: Set to true to return closed positions + - in: query + name: walletAddress + description: Public key for the wallet to fetch trades + schema: + type: string + description: Public key for the wallet to fetch trades + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + dataList: + type: array + items: + type: object + properties: + asset: + type: string + enum: + - BTC + - ETH + - SOL + description: >- + The asset or market being traded against for the + position. + example: SOL + assetMint: + type: string + description: The mint address for the position asset. + example: So11111111111111111111111111111111111111112 + collateralToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + - USDT + description: >- + The token symbol for the collateral backing the + position. + example: SOL + collateralMint: + type: string + description: The mint address for the collateral token. + example: So11111111111111111111111111111111111111112 + positionPubkey: + type: string + description: The public key / address for the position + example: 815wh1VLC8D7ZWMa3uB7GgjHFetANuML2dPrJiLV1nVF + side: + type: string + enum: + - long + - short + description: Side for the position + leverage: + type: string + description: Leverage amount for the position + example: '21.30' + sizeUsd: + type: string + description: >- + Raw USD value of the position's trade size + (including leverage) + example: '1234567800' + sizeTokenAmount: + type: string + description: >- + Raw token amount for the position's size scaled to + the custody token's mint decimals + example: '250000000' + collateralUsd: + type: string + description: Raw USD value of the position's collateral size + example: '250000000' + valueUsd: + type: string + description: >- + Raw USD value of the currently open position + including opening, closing, and borrowing fees + incurred + example: '120000000' + entryPriceUsd: + type: string + description: Raw USD value of the position's entry price + example: '123450000' + markPriceUsd: + type: string + description: Raw USD value of the position's mark price + example: '125000000' + liquidationPriceUsd: + type: string + description: Raw USD value of the position's liquidation price + example: '113450000' + openFeesUsd: + type: string + description: >- + Raw fee for opening the position in the integer + format corresponding to 6 decimal places (USD terms) + example: '100000' + closeFeesUsd: + type: string + description: >- + Raw fee for closing the position in the integer + format corresponding to 6 decimal places (USD terms) + example: '100000' + borrowFeesUsd: + type: string + description: >- + Raw outstanding borrow fees for the position in the + integer format corresponding to 6 decimal places + (USD terms) + example: '100000' + totalFeesUsd: + type: string + description: >- + Raw total fees for the position in the integer + format corresponding to 6 decimal places (USD terms) + example: '200000' + pnlBeforeFeesUsd: + type: string + description: >- + Raw value of the position's PNL before fees in the + integer format corresponding to 6 decimal places + (USD terms) + example: '1045000' + pnlBeforeFeesPct: + type: string + description: >- + The PNL change (%) from closing the position before + fees. + example: '20.24' + pnlAfterFeesUsd: + type: string + description: >- + Raw value of the position's PNL after fees in the + integer format corresponding to 6 decimal places + (USD terms) + example: '1045000' + pnlAfterFeesPct: + type: string + description: >- + The PNL change (%) from closing the position after + fees. + example: '-20.24' + createdTime: + type: number + description: UNIX timestamp of when the trade was created + example: 1722851463 + updatedTime: + type: number + example: 1722851463 + tpslRequests: + type: array + items: + type: object + properties: + positionRequestPubkey: + type: string + description: >- + The public key / address for the TP / SL + position request account + requestType: + type: string + enum: + - tp + - sl + description: >- + Returns `tp` if it is a take profit request, + `sl` if it is a stop loss request + desiredMint: + type: string + description: >- + The mint address for the TP / SL position + request account desired mint + example: So11111111111111111111111111111111111111112 + desiredToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + - USDT + description: >- + The token symbol for the TP / SL position + request account desired mint + example: SOL + collateralUsdDelta: + type: string + description: >- + Raw collateral delta (USD) for the TP / SL in + the integer format corresponding to 6 decimal + places + example: '1234000000' + entirePosition: + type: boolean + description: >- + Whether the TP / SL request closes the entire + position + sizeUsd: + type: string + description: >- + Raw close size for the TP / SL in integer + format corresponding to the 6 decimal places + used by the USDC and USDT token mint + example: '1234000000' + sizePercentage: + type: string + description: >- + The percentage / ratio TP / SL size to the + position size + example: '12.34' + triggerPriceUsd: + type: + - string + - 'null' + description: >- + Raw trigger price for the TP / SL request in + integer format corresponding to the 6 decimals + places used by the USDC and USDT token mint + example: '20000000' + openTime: + type: string + description: >- + Unix timestamp of when the TP / SL request was + created + example: '1722851463' + required: + - positionRequestPubkey + - requestType + - desiredMint + - desiredToken + - collateralUsdDelta + - entirePosition + - sizeUsd + - sizePercentage + - triggerPriceUsd + - openTime + description: The active TP / SL requests for the position + required: + - asset + - assetMint + - collateralToken + - collateralMint + - positionPubkey + - side + - leverage + - sizeUsd + - sizeTokenAmount + - collateralUsd + - valueUsd + - entryPriceUsd + - markPriceUsd + - liquidationPriceUsd + - openFeesUsd + - closeFeesUsd + - borrowFeesUsd + - totalFeesUsd + - pnlBeforeFeesUsd + - pnlBeforeFeesPct + - pnlAfterFeesUsd + - pnlAfterFeesPct + - createdTime + - updatedTime + - tpslRequests + count: + type: number + required: + - dataList + - count + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/close-all: + description: >- + Returns an array of serialized transactions to close all open positions + for the given wallet address. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + walletAddress: + type: string + description: >- + The wallet address / public key for the trader to close all + open positions + required: + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + serializedTxs: + type: array + items: + type: object + properties: + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) + containing the instructions and given parameters for + the close position instruction. The transaction can + be deserialized, signed by the owner of + `walletAddress` and submitted onchain to close the + position. + positionRequestPubkey: + type: string + description: >- + The public key / address for the position request to + close the position. + required: + - serializedTxBase64 + - positionRequestPubkey + description: >- + An array of base64-serialized transactions and the + `positionRequestPubkey` to close all positions. + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + close position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed close position transaction. + required: + - blockhash + - lastValidBlockHeight + description: >- + Contains blockhash metadata for the serialized transaction + to submit and confirm the transactions. + required: + - serializedTxs + - txMetadata + description: >- + An array of base64-serialized transactions and transaction + metadata to close all positions. + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/collateral-limits: + description: >- + Returns the minimum and maximum token amounts for collateral deposits, as + well as the maximum token amount for collateral withdrawals. + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: inputMint + description: >- + The mint address for the input token to deposit as collateral (e.g. + 'So11111111111111111111111111111111111111112' for 'SOL') + schema: + type: string + description: >- + The mint address for the input token to deposit as collateral + (e.g. 'So11111111111111111111111111111111111111112' for 'SOL') + example: So11111111111111111111111111111111111111112 + required: true + - in: query + name: positionPubkey + description: >- + The public key for the open position. Use the `GET positions` + endpoint to fetch the public key for the trader's open positions. + schema: + type: string + description: >- + The public key for the open position. Use the `GET positions` + endpoint to fetch the public key for the trader's open positions. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + maxCollateralDepositTokenAmount: + type: string + description: >- + The maximum token amount that can be deposited as + collateral for the given input mint token. + maxCollateralDepositUsd: + type: string + description: >- + The maximum amount (USD) that can be deposited as + collateral for the given input mint token. The value is an + integer corresponding to the 6 decimals places used by the + USDC and USDT token mint. + minCollateralDepositTokenAmount: + type: string + description: >- + The minimum token amount that can be deposited as + collateral for the given input mint token. + minCollateralDepositUsd: + type: string + description: >- + The minimum amount (USD) that can be deposited as + collateral for the given input mint token. The value is an + integer corresponding to the 6 decimals places used by the + USDC and USDT token mint. + maxCollateralWithdrawalTokenAmount: + type: string + description: >- + The maximum collateral token amount that can be withdrawed + from the open position. + maxCollateralWithdrawalUsd: + type: string + description: >- + The maximum collateral (USD) that can be withdrawed from + the open position. The value is an integer corresponding + to the 6 decimals places used by the USDC and USDT token + mint. + minCollateralWithdrawalTokenAmount: + type: string + description: >- + The minimum collateral token amount that can be withdrawed + from the open position. + minCollateralWithdrawalUsd: + type: string + description: >- + The minimum collateral (USD) that can be withdrawed from + the open position. The value is an integer corresponding + to the 6 decimals places used by the USDC and USDT token + mint. + required: + - maxCollateralDepositTokenAmount + - maxCollateralDepositUsd + - minCollateralDepositTokenAmount + - minCollateralDepositUsd + - maxCollateralWithdrawalTokenAmount + - maxCollateralWithdrawalUsd + - minCollateralWithdrawalTokenAmount + - minCollateralWithdrawalUsd + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/decrease: + description: >- + Uses the `decreasePositionParams` object from calling `GET + /positions/decrease/quote` and returns a base64-serialized transaction for + the request, the position request PDA, and the position PDA that acts as + the unique identifier for the position. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + collateralUsdDelta: + type: + - string + - 'null' + description: >- + The amount of collateral to withdraw in USD from the + position. Must be an integer representing the USD amount + multiplied by 10^6 (1 million) to align with the 6 decimal + places used for USDC/USDT tokens on-chain. For example, to + decrease by $10 USD, set 'collateralUsdDelta' to 10000000; + for $20.50 USD, set 'collateralUsdDelta' to 20500000. + example: '10000000' + entirePosition: + type: boolean + default: false + description: >- + When set to `true`, this will close the position and + transfer the remaining collateral and realised profits (if + the position is profitable) to the trader. + example: false + maxSlippageBps: + type: string + default: '200' + description: >- + The maximum slippage in (BPS) for the asset's price when + executing the trade + example: '100' + positionPubkey: + type: string + description: >- + The public key for the open position. Use the `GET + positions` endpoint to fetch the public key for the trader's + open positions. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + priorityFeeMicroLamports: + type: string + description: >- + Custom priority fee in microlamports for the transaction + (1,000,000 microlamports = 1 lamport). If not set, the API + will automatically set the optimal priority fee + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: The token to receive. + sizeUsdDelta: + type: + - string + - 'null' + description: >- + The amount in USD to decrease the position size by. Must be + an integer representing the USD amount multiplied by 10^6 (1 + million) to align with the 6 decimal places used for + USDC/USDT tokens on-chain. For example, to decrease by $10 + USD, set 'sizeUsdDelta' to 10000000; for $20.50 USD, set + 'sizeUsdDelta' to 20500000. + example: '10000000' + required: + - positionPubkey + - receiveToken + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: string + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + quote: + type: object + properties: + closeFeeUsd: + type: string + description: >- + The base close fee for closing the position or + withdrawing collateral (raw value with 6 decimal + places) + example: '100000' + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '10000000' + leverage: + type: string + description: >- + The leverage amount for the position after the + decrease + example: '2.99' + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + closing the position (raw value with 6 decimal places) + example: '100000' + pnlAfterFeesUsd: + type: string + description: >- + The position PNL after fees (raw value with 6 decimal + places) + example: '1045000' + pnlAfterFeesPercent: + type: string + description: >- + The PNL change (%) from closing the position after + fees + example: '-20.24' + pnlBeforeFeesUsd: + type: string + description: >- + The position PNL before fees (raw value with 6 decimal + places) + example: '1045000' + pnlBeforeFeesPercent: + type: string + description: >- + The PNL change (%) from closing the position before + fees + example: '20.24' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + decrease (raw value with 6 decimal places) + example: '100000000' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the decrease (raw value with 6 decimal places) + example: '10000000' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for closing the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '1.3301' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee for closing the position based on + the position size (raw value with 6 decimal places). + For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '10000000' + totalFeeUsd: + type: string + description: >- + The total fee in USD for closing or withdrawing + collateral including base fees, borrowing fees, and + price impact fees (raw value with 6 decimal places) + example: '100000' + transferAmountToken: + type: string + description: >- + The collateral token amount to transfer to the owner + after withdrawing collateral or closing the position + (raw value) + example: '100000000' + transferAmountUsd: + type: string + description: >- + The collateral token amount in USD to transfer to the + owner (raw value with 6 decimal places) + example: '10000000' + transferTokenMint: + type: string + description: >- + The mint address for the token used to transfer the + collateral withdrawal or closing position amount + example: So11111111111111111111111111111111111111112 + required: + - closeFeeUsd + - collateralUsdDelta + - leverage + - liquidationPriceUsd + - outstandingBorrowFeeUsd + - pnlAfterFeesUsd + - pnlAfterFeesPercent + - pnlBeforeFeesUsd + - pnlBeforeFeesPercent + - positionCollateralUsd + - positionSizeUsd + - priceImpactFeeBps + - priceImpactFeeUsd + - side + - sizeUsdDelta + - totalFeeUsd + - transferAmountToken + - transferAmountUsd + - transferTokenMint + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for the transaction (1 + SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - positionPubkey + - quote + - serializedTxBase64 + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/increase: + description: >- + Uses the `increasePositionParams` object from calling `GET + /positions/increase/quote` and returns a base64-serialized transaction for + the request, the position request PDA, and the position PDA that acts as + the unique identifier for the position. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + asset: + type: string + enum: + - BTC + - ETH + - SOL + description: The asset or market to trade against + example: SOL + inputToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: >- + The token symbol for the input token used to fund the + position + example: SOL + inputTokenAmount: + type: string + description: >- + The amount of tokens for the input token to open the + position or deposit collateral. NOTE: The token amount needs + to be an integer and must conform to the token mint decimals + specified onchain. For example, to deposit 1 SOL, the value + would be '1000000000' (9 decimals) + example: '1000000000' + leverage: + type: string + description: >- + Leverage of the increase position, up to 1 decimal place. + Either provide 'leverage' or 'sizeUsdDelta' to open a trade. + Min leverage is '1.1'. Max leverage for SOL is 250.0 + example: '11.5' + maxSlippageBps: + type: string + description: >- + The maximum slippage in (BPS) for the asset's price when + executing trade + example: '100' + priorityFeeMicroLamports: + type: string + description: >- + Custom priority fee in microlamports for the transaction + (1,000,000 microlamports = 1 lamport). If not set, the API + will automatically set the optimal priority fee + side: + type: string + enum: + - long + - short + description: Side for the trade + sizeUsdDelta: + type: string + description: >- + The amount in USD to increase the position size by. Must be + an integer representing the USD amount multiplied by 10^6 (1 + million) to align with the 6 decimal places used for + USDC/USDT tokens on-chain. For example, to increase the + position size by $10 USD, set 'sizeUsdDelta' to 10000000; + for $0.50 USD, set 'sizeUsdDelta' to 500000. Either provide + 'leverage' or 'sizeUsdDelta'. + example: '10000000' + tpsl: + type: + - array + - 'null' + items: + type: object + properties: + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: The token to receive when the TPSL is executed. + triggerPrice: + type: string + description: >- + Trigger price at which the TP / SL request will be + executed. The value must be an integer corresponding + to 6 decimal places. For example, to set a trigger + price of $20, pass in 20000000 + example: '20000000' + requestType: + type: string + enum: + - tp + - sl + description: >- + Pass in `tp` to set a take profit request or `sl` to + set a stop loss request + required: + - receiveToken + - triggerPrice + - requestType + maxItems: 2 + description: >- + TPSL requests to set. TPSL requests can only be set for + positions that 150x leverage or below. Only 2 TPSLs can be + set at a time. + walletAddress: + type: string + description: >- + The wallet address / public key for the trader, Required + when opening a new position. + required: + - asset + - inputToken + - inputTokenAmount + - maxSlippageBps + - side + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + quote: + type: object + properties: + averagePriceUsd: + type: string + description: >- + The average price for the position in USD (raw value + with 6 decimal places) + example: '10000000' + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '1124450000' + leverage: + type: string + description: The leverage amount for the position + example: '2.99' + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + openFeeUsd: + type: string + description: >- + The total fee in USD for opening the position or + depositing collateral including base fees, borrowing + fees, and price impact fees (raw value with 6 decimal + places) + example: '100000' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + depositing collateral to the position (raw value with + 6 decimal places) + example: '100000' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + increase (raw value with 6 decimal places) + example: '100000000' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the increase (raw value with 6 decimal places) + example: '10000000' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for opening the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '100' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee in USD for opening the position + based on the position size (raw value with 6 decimal + places). For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '1124450000' + sizeTokenDelta: + type: string + description: >- + The change in the position's size in the token amount + for the position's collateral token. + example: '14420000' + required: + - averagePriceUsd + - collateralUsdDelta + - leverage + - liquidationPriceUsd + - openFeeUsd + - outstandingBorrowFeeUsd + - positionCollateralUsd + - positionSizeUsd + - priceImpactFeeBps + - priceImpactFeeUsd + - side + - sizeUsdDelta + - sizeTokenDelta + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the increase + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the increase position request + tpsl: + type: array + items: + type: object + properties: + hasProfit: + type: boolean + description: Whether the TPSL request is profitable + pnlUsd: + type: string + description: The estimated PNL (USD) delta for the TPSL request + pnlPercent: + type: string + description: The estimated PNL percentage for the TPSL request + pubkey: + type: string + description: >- + The pubkey for the TPSL. Use this address to find + the TPSL account onchain + requestType: + type: string + enum: + - tp + - sl + description: The type of TPSL request + required: + - hasProfit + - pnlUsd + - pnlPercent + - pubkey + - requestType + description: TPSL requests created with the increase position + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + increase position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed increase position transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for creating the position + account (1 SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - positionPubkey + - quote + - serializedTxBase64 + - tpsl + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/increase-with-fee: + description: >- + Uses the `increasePositionParams` object from calling `GET + /positions/increase/quote` and returns a base64-serialized transaction for + the request, the position request PDA, and the position PDA that acts as + the unique identifier for the position. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + asset: + type: string + enum: + - BTC + - ETH + - SOL + description: >- + The asset or market to trade against. Required when opening + a new position. 'SOL' = + 'So11111111111111111111111111111111111111112', 'ETH' = + '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs', 'BTC' = + '3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh' + example: SOL + feeToken: + type: string + enum: + - USDC + description: >- + The token symbol for the fee token. Currently only USDC is + supported. Must be the same as input token. + feeTokenAmount: + type: string + description: >- + The amount of fee tokens to send to `feeReceiver`. The value + must match the token mint decimals specified in `feeToken` + (e.g., for USDC with 6 decimals, 1000000 = 1 USDC) + example: '1000000' + feeReceiver: + type: string + description: >- + The token address (ATA) to receive the fee specified in + `feeTokenAmount`. The ATA must match the token mint + specified in `feeToken` + inputToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: >- + The token symbol for the input token used to fund the + position. Must be the same as fee token. + example: SOL + inputTokenAmount: + type: string + description: >- + The amount of tokens for the input token to open the + position or deposit collateral. NOTE: The token amount needs + to be an integer and must conform to the token mint decimals + specified onchain. For example, to deposit 1 SOL, the value + would be '1000000000' (9 decimals) + example: '1000000000' + leverage: + type: string + description: >- + Leverage of the increase position, up to 1 decimal place. + Either provide 'leverage' or 'sizeUsdDelta' to open a trade. + Min leverage is '1.1'. Max leverage for SOL is 100.0. Max + leverage for BTC / ETH is 150.0 + example: '11.5' + maxSlippageBps: + type: string + description: >- + The maximum slippage in (BPS) for the custody token price + when executing the decrease position trade + example: '100' + priorityFeeMicroLamports: + type: string + description: >- + Custom priority fee in microlamports for the transaction + (1,000,000 microlamports = 1 lamport). If not set, the API + will automatically set the optimal priority fee + side: + type: string + enum: + - long + - short + description: Required when opening a new position + sizeUsdDelta: + type: string + description: >- + The amount in USD to increase the position size by. Must be + an integer representing the USD amount multiplied by 10^6 (1 + million) to align with the 6 decimal places used for + USDC/USDT tokens on-chain. For example, to increase the + position size by $10 USD, set 'sizeUsdDelta' to 10000000; + for $0.50 USD, set 'sizeUsdDelta' to 500000. Either provide + leverage or sizeUsdDelta. + example: '10000000' + tpsl: + type: + - array + - 'null' + items: + type: object + properties: + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: The token to receive when the TPSL is executed. + triggerPrice: + type: string + description: >- + Trigger price at which the TP / SL request will be + executed. The value must be an integer corresponding + to 6 decimal places. For example, to set a trigger + price of $20, pass in 20000000 + example: '20000000' + requestType: + type: string + enum: + - tp + - sl + description: >- + Pass in `tp` to set a take profit request or `sl` to + set a stop loss request + required: + - receiveToken + - triggerPrice + - requestType + description: TPSL requests to set + walletAddress: + type: string + description: >- + The wallet address / public key for the trader, Required + when opening a new position. + required: + - asset + - feeToken + - feeTokenAmount + - feeReceiver + - inputToken + - inputTokenAmount + - maxSlippageBps + - side + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: + - string + - 'null' + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + quote: + type: object + properties: + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '1124450000' + collateralUsdDeltaFormatted: + type: string + description: >- + The change in collateral amount in USD (human-readable + format) + example: '1124.45' + leverage: + type: string + description: The leverage amount for the position + example: '2.99' + integratorFeeTokenMint: + type: string + description: The token mint for the integrator fee token + integratorFeeTokenAmount: + type: string + description: The amount of the integrator fee token + integratorFeeUsd: + type: string + description: >- + The estimated integrator fee in USD (raw value with 6 + decimal places) + integratorFeeUsdFormatted: + type: string + description: >- + The estimated integrator fee in USD (human-readable + format) + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + liquidationPriceUsdFormatted: + type: string + description: The liquidation price in USD (human-readable format) + example: '13.24' + openFeeUsd: + type: string + description: >- + The total fee in USD for opening the position or + depositing collateral including base fees, borrowing + fees, and price impact fees (raw value with 6 decimal + places) + example: '100000' + openFeeUsdFormatted: + type: string + description: >- + The total fee in USD for opening the position or + depositing collateral including base fees, borrowing + fees, and price impact fees (human-readable format) + example: '0.1000' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + depositing collateral to the position (raw value with + 6 decimal places) + example: '100000' + outstandingBorrowFeeUsdFormatted: + type: string + description: >- + The outstanding borrow fees due / to be paid on + depositing collateral to the position (human-readable + format) + example: '0.1000' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + increase (raw value with 6 decimal places) + example: '100000000' + positionCollateralUsdFormatted: + type: string + description: >- + The total position collateral size in USD after the + increase (human-readable format) + example: '100.00' + positionPriceUsd: + type: string + description: >- + The position's average price in USD (raw value with 6 + decimal places) + example: '2990000' + positionPriceUsdFormatted: + type: string + description: >- + The position's average price in USD (human-readable + format) + example: '2.99' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the increase (raw value with 6 decimal places) + example: '10000000' + positionSizeUsdFormatted: + type: string + description: >- + The total position size in USD including leverage + after the increase (human-readable format) + example: '10.00' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for opening the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '1.3301' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee in USD for opening the position + based on the position size (raw value with 6 decimal + places). For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + priceImpactFeeUsdFormatted: + type: string + description: >- + The price impact fee in USD for opening the position + based on the position size (human-readable format). + For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '0.0133' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '1124450000' + sizeUsdDeltaFormatted: + type: string + description: >- + The change in position size in USD (human-readable + format) + example: '1124.45' + required: + - collateralUsdDelta + - collateralUsdDeltaFormatted + - leverage + - integratorFeeTokenMint + - integratorFeeTokenAmount + - integratorFeeUsd + - integratorFeeUsdFormatted + - liquidationPriceUsd + - liquidationPriceUsdFormatted + - openFeeUsd + - openFeeUsdFormatted + - outstandingBorrowFeeUsd + - outstandingBorrowFeeUsdFormatted + - positionCollateralUsd + - positionCollateralUsdFormatted + - positionPriceUsd + - positionPriceUsdFormatted + - positionSizeUsd + - positionSizeUsdFormatted + - priceImpactFeeBps + - priceImpactFeeUsd + - priceImpactFeeUsdFormatted + - side + - sizeUsdDelta + - sizeUsdDeltaFormatted + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the increase + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the increase position request + tpsl: + type: array + items: + type: object + properties: + hasProfit: + type: boolean + description: Whether the TPSL request is profitable + pnlUsd: + type: string + description: The estimated PNL (USD) delta for the TPSL request + pnlUsdFormatted: + type: string + description: The estimated PNL (USD) delta for the TPSL request + pnlPercent: + type: string + description: The estimated PNL percentage for the TPSL request + pubkey: + type: string + description: >- + The pubkey for the TPSL. Use this address to find + the TPSL account onchain + requestType: + type: string + enum: + - tp + - sl + description: The type of TPSL request + required: + - hasProfit + - pnlUsd + - pnlUsdFormatted + - pnlPercent + - pubkey + - requestType + description: TPSL requests created with the increase position + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + increase position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed increase position transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for creating the position + account (1 SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - positionPubkey + - quote + - serializedTxBase64 + - tpsl + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /positions/decrease-with-fee: + description: >- + Uses the `decreasePositionParams` object from calling `GET + /positions/decrease/quote` and returns a base64-serialized transaction for + the request, the position request PDA, and the position PDA that acts as + the unique identifier for the position. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + collateralUsdDelta: + type: + - string + - 'null' + description: >- + The amount of collateral to withdraw in USD from the + position. Must be an integer representing the USD amount + multiplied by 10^6 (1 million) to align with the 6 decimal + places used for USDC/USDT tokens on-chain. For example, to + decrease by $10 USD, set 'collateralUsdDelta' to 10000000; + for $20.50 USD, set 'collateralUsdDelta' to 20500000. + example: '10000000' + entirePosition: + type: boolean + default: false + description: >- + When set to `true`, this will close the position and + transfer the remaining collateral and realised profits (if + the position is profitable) to the trader. + example: false + feeToken: + type: string + enum: + - USDC + description: >- + The token symbol for the fee token. Currently only USDC is + supported + feeTokenAmount: + type: string + description: >- + The amount of fee tokens to send to `feeReceiver`. The value + must match the token mint decimals specified in `feeToken` + (e.g., for USDC with 6 decimals, 1000000 = 1 USDC) + example: '1000000' + feeReceiver: + type: string + description: >- + The token address (ATA) to receive the fee specified in + `feeTokenAmount`. The ATA must match the token mint + specified in `feeToken` + maxSlippageBps: + type: string + default: '200' + description: >- + The maximum slippage in (BPS) for the token swap (if + required) and the token price when executing the increase + position trade + example: '100' + positionPubkey: + type: string + description: >- + The public key for the open position. Use the `GET + positions` endpoint to fetch the public key for the trader's + open positions. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + priorityFeeMicroLamports: + type: string + description: >- + Custom priority fee in microlamports for the transaction + (1,000,000 microlamports = 1 lamport). If not set, the API + will automatically set the optimal priority fee + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: The token to receive. + sizeUsdDelta: + type: + - string + - 'null' + description: >- + The amount in USD to decrease the position size by. Must be + an integer representing the USD amount multiplied by 10^6 (1 + million) to align with the 6 decimal places used for + USDC/USDT tokens on-chain. For example, to decrease by $10 + USD, set 'sizeUsdDelta' to 10000000; for $20.50 USD, set + 'sizeUsdDelta' to 20500000. + example: '10000000' + required: + - feeToken + - feeTokenAmount + - feeReceiver + - positionPubkey + - receiveToken + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + positionPubkey: + type: string + description: >- + The unique identifier (i.e. a program derived address) for + the position account. Use this address to find the + position account onchain. + quote: + type: object + properties: + closeFeeUsd: + type: string + description: >- + The base close fee for closing the position or + withdrawing collateral (raw value with 6 decimal + places) + example: '100000' + closeFeeUsdFormatted: + type: string + description: >- + The base close fee for closing the position or + withdrawing collateral (human-readable format) + example: '0.1000' + collateralUsdDelta: + type: string + description: >- + The change in collateral amount in USD (raw value with + 6 decimal places) + example: '10000000' + collateralUsdDeltaFormatted: + type: string + description: >- + The change in collateral amount in USD (human-readable + format) + example: '10.00' + integratorFeeTokenMint: + type: string + description: The token mint for the integrator fee token + integratorFeeTokenAmount: + type: string + description: The amount of the integrator fee token + integratorFeeUsd: + type: string + description: >- + The estimated integrator fee in USD (raw value with 6 + decimal places) + integratorFeeUsdFormatted: + type: string + description: >- + The estimated integrator fee in USD (human-readable + format) + leverage: + type: string + description: >- + The leverage amount for the position after the + decrease + example: '2.99' + liquidationPriceUsd: + type: string + description: >- + The liquidation price in USD (raw value with 6 decimal + places) + example: '13240000' + liquidationPriceUsdFormatted: + type: string + description: The liquidation price in USD (human-readable format) + example: '13.24' + outstandingBorrowFeeUsd: + type: string + description: >- + The outstanding borrow fees due / to be paid on + closing the position (raw value with 6 decimal places) + example: '100000' + outstandingBorrowFeeUsdFormatted: + type: string + description: >- + The outstanding borrow fees due / to be paid on + closing the position (human-readable format) + example: '0.1000' + pnlAfterFeesUsd: + type: string + description: >- + The position PNL after fees (raw value with 6 decimal + places) + example: '1045000' + pnlAfterFeesUsdFormatted: + type: string + description: The position PNL after fees (human-readable format) + example: '1.045' + pnlAfterFeesPercent: + type: string + description: >- + The PNL change (%) from closing the position after + fees + example: '-20.24' + pnlBeforeFeesUsd: + type: string + description: >- + The position PNL before fees (raw value with 6 decimal + places) + example: '1045000' + pnlBeforeFeesUsdFormatted: + type: string + description: The position PNL before fees (human-readable format) + example: '1.045' + pnlBeforeFeesPercent: + type: string + description: >- + The PNL change (%) from closing the position before + fees + example: '20.24' + positionCollateralUsd: + type: string + description: >- + The total position collateral size in USD after the + decrease (raw value with 6 decimal places) + example: '100000000' + positionCollateralUsdFormatted: + type: string + description: >- + The total position collateral size in USD after the + decrease (human-readable format) + example: '100.00' + positionSizeUsd: + type: string + description: >- + The total position size in USD including leverage + after the decrease (raw value with 6 decimal places) + example: '10000000' + positionSizeUsdFormatted: + type: string + description: >- + The total position size in USD including leverage + after the decrease (human-readable format) + example: '10.00' + priceImpactFeeBps: + type: string + description: >- + The price impact fee bps for closing the position + based on the position size. For more info on how the + price impact fee calculation works: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '1.3301' + priceImpactFeeUsd: + type: string + description: >- + The price impact fee for closing the position based on + the position size (raw value with 6 decimal places). + For more info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '13301' + priceImpactFeeUsdFormatted: + type: string + description: >- + The price impact fee for closing the position based on + the position size (human-readable format). For more + info: + https://www.jupresear.ch/t/jupiter-perpetuals-price-impact-fee-mechanism/17140 + example: '0.0133' + side: + type: string + enum: + - long + - short + description: The position side + example: long + sizeUsdDelta: + type: string + description: >- + The change in position size in USD (raw value with 6 + decimal places) + example: '10000000' + sizeUsdDeltaFormatted: + type: string + description: >- + The change in position size in USD (human-readable + format) + example: '10.00' + totalFeeUsd: + type: string + description: >- + The total fee in USD for closing or withdrawing + collateral including base fees, borrowing fees, and + price impact fees (raw value with 6 decimal places) + example: '100000' + totalFeeUsdFormatted: + type: string + description: >- + The total fee in USD for closing or withdrawing + collateral including base fees, borrowing fees, and + price impact fees (human-readable format) + example: '0.1000' + transferAmountToken: + type: string + description: >- + The collateral token amount to transfer to the owner + after withdrawing collateral or closing the position + (raw value) + example: '100000000' + transferAmountUsd: + type: string + description: >- + The collateral token amount in USD to transfer to the + owner (raw value with 6 decimal places) + example: '10000000' + transferAmountUsdFormatted: + type: string + description: >- + The collateral token amount in USD to transfer to the + owner (human-readable format) + example: '10.00' + transferTokenMint: + type: string + description: >- + The mint address for the token used to transfer the + collateral withdrawal or closing position amount + example: So11111111111111111111111111111111111111112 + required: + - closeFeeUsd + - closeFeeUsdFormatted + - collateralUsdDelta + - collateralUsdDeltaFormatted + - integratorFeeTokenMint + - integratorFeeTokenAmount + - integratorFeeUsd + - integratorFeeUsdFormatted + - leverage + - liquidationPriceUsd + - liquidationPriceUsdFormatted + - outstandingBorrowFeeUsd + - outstandingBorrowFeeUsdFormatted + - pnlAfterFeesUsd + - pnlAfterFeesUsdFormatted + - pnlAfterFeesPercent + - pnlBeforeFeesUsd + - pnlBeforeFeesUsdFormatted + - pnlBeforeFeesPercent + - positionCollateralUsd + - positionCollateralUsdFormatted + - positionSizeUsd + - positionSizeUsdFormatted + - priceImpactFeeBps + - priceImpactFeeUsd + - priceImpactFeeUsdFormatted + - side + - sizeUsdDelta + - sizeUsdDeltaFormatted + - totalFeeUsd + - totalFeeUsdFormatted + - transferAmountToken + - transferAmountUsd + - transferAmountUsdFormatted + - transferTokenMint + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: >- + The transaction fee in lamports (1 SOL = 1,000,000,000 + lamports) + example: '5000' + accountRentLamports: + type: string + description: >- + The account rent in lamports for the transaction (1 + SOL = 1,000,000,000 lamports) + example: '2039280' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - positionPubkey + - quote + - serializedTxBase64 + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /pool-info: + description: Fetches the perpetuals base pool config info for the given market + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: mint + description: The token mint address for the perpetuals market + schema: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: The token mint address for the perpetuals market + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + longAvailableLiquidity: + type: string + description: >- + USD value of the available liquidity for long positions + for the market + example: '2500000' + longBorrowRatePercent: + type: string + description: >- + Base borrow rate (%) for long positions. More info on how + the borrow rate is calculated here: + https://station.jup.ag/guides/perpetual-exchange/how-it-works#hourly-borrow-rate + example: '0.0026' + longUtilizationPercent: + type: string + description: Utilization rate (%) for long positions + example: '26.00' + shortAvailableLiquidity: + type: string + description: >- + USD value of the available liquidity for short positions + for the market + example: '2500000' + shortBorrowRatePercent: + type: string + description: >- + Base borrow rate (%) for short positions. More info on how + the borrow rate is calculated here: + https://station.jup.ag/guides/perpetual-exchange/how-it-works#hourly-borrow-rate + example: '0.0026' + shortUtilizationPercent: + type: string + description: Utilization rate (%) for short positions + example: '26.00' + openFeePercent: + type: string + description: Base open fee (%) for the market + example: '0.06' + maxRequestExecutionSec: + type: string + description: >- + The maximum duration that a position request can be active + (in seconds) before it is considered invalid. + maxPriceImpactFeePercent: + type: string + description: The maximum price impact fee (%) + required: + - longAvailableLiquidity + - longBorrowRatePercent + - longUtilizationPercent + - shortAvailableLiquidity + - shortBorrowRatePercent + - shortUtilizationPercent + - openFeePercent + - maxRequestExecutionSec + - maxPriceImpactFeePercent + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /jlp-info: + description: Fetches the JLP token info + get: + security: + - ApiKeyAuth: [] + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + aumUsd: + type: string + description: Total AUM in USD (raw value) + example: '123456789000000' + aumUsdFormatted: + type: string + description: Total AUM in USD (formatted) + example: '123,456.79' + aumLimitUsd: + type: string + description: AUM limit in USD (raw value) + example: '500000000000000' + aumLimitUsdFormatted: + type: string + description: AUM limit in USD (formatted) + example: '500,000' + jlpPriceUsd: + type: string + description: JLP price in USD (raw value) + example: '1234567' + jlpPriceUsdFormatted: + type: string + description: JLP price in USD (formatted) + example: '1.2346' + jlpTotalSupply: + type: string + description: Total JLP token supply + example: '100000000000' + jlpTotalSupplyFormatted: + type: string + description: Total JLP token supply (formatted) + example: '100,000' + jlpAprBps: + type: string + description: JLP APR in BPS + example: '100' + jlpAprPct: + type: string + description: JLP APR in percentage + example: '10.00' + jlpApyBps: + type: string + description: JLP APY in BPS + example: '100' + jlpApyPct: + type: string + description: JLP APY in percentage + example: '10.00' + jlpAprLastUpdatedTimestamp: + type: string + description: JLP APR last updated UNIX timestamp + example: '1715404800' + jlpRealizedFeeUsd: + type: string + description: >- + JLP realized fee in USD since the last APR / APY + calculation + example: '100000000' + custodies: + type: array + items: + type: object + properties: + pubkey: + type: string + description: Custody public key + example: '11111111111111111111111111111111' + symbol: + type: string + description: Token symbol + example: SOL + name: + type: string + description: Token name + example: Wrapped SOL + mint: + type: string + description: Token mint + example: So11111111111111111111111111111111111111112 + aumUsd: + type: string + description: Custody AUM in USD (raw value) + example: '12345678900000' + aumUsdFormatted: + type: string + description: Custody AUM in USD (formatted) + example: '123456.79' + aumTokenAmount: + type: string + description: Custody AUM in token amount + example: '123456789' + aumTokenAmountFormatted: + type: string + description: Custody AUM in token amount (formatted) + example: '123,456.79' + currentWeightagePct: + type: string + description: Current weight percentage + example: '25.50' + targetWeightagePct: + type: string + description: Target weight percentage + example: '30.00' + utilizationPct: + type: string + description: Utilization percentage + example: '45.20' + owned: + type: string + description: >- + Tokens owned by the JLP pool scaled to the token's + mint decimals + example: '123456789' + locked: + type: string + description: >- + Tokens locked by the JLP pool for trader's + collateral and leverage scaled to the token's mint + decimals + example: '123456789' + guaranteedUsd: + type: string + description: >- + Current long sizes for the token scaled to the USDC + decimals (6) + example: '123456789' + globalShortSizes: + type: string + description: >- + Current short sizes for the token scaled to the USDC + decimals (6) + example: '123456789' + globalShortAveragePrice: + type: string + description: >- + Average price of all short positions for the token + scaled to the USDC decimals (6) + example: '123456789' + shortPnlDelta: + type: string + description: Short PnL delta scaled to the USDC decimals (6) + example: '123456789' + shortTradersHasProfit: + type: boolean + description: >- + Boolean to indicate whether short traders are in + profit + example: true + totalStakedAmountLamports: + type: string + description: Total staked SOL lamports (zero for other assets) + example: '123456789' + totalStakedAmountUsd: + type: string + description: >- + Total staked SOL lamports in USD scaled to 6 decimal + places as per the USDC mint (zero for other assets) + example: '123456789' + totalStakedAmountUsdFormatted: + type: string + description: >- + Formatted total staked SOL lamports in USD scaled to + 6 decimal places as per the USDC mint (zero for + other assets) + example: '123456789' + required: + - pubkey + - symbol + - name + - mint + - aumUsd + - aumUsdFormatted + - aumTokenAmount + - aumTokenAmountFormatted + - currentWeightagePct + - targetWeightagePct + - utilizationPct + - owned + - locked + - guaranteedUsd + - globalShortSizes + - globalShortAveragePrice + - shortPnlDelta + - shortTradersHasProfit + - totalStakedAmountLamports + - totalStakedAmountUsd + - totalStakedAmountUsdFormatted + description: List of custody information + required: + - aumUsd + - aumUsdFormatted + - aumLimitUsd + - aumLimitUsdFormatted + - jlpPriceUsd + - jlpPriceUsdFormatted + - jlpTotalSupply + - jlpTotalSupplyFormatted + - jlpAprBps + - jlpAprPct + - jlpApyBps + - jlpApyPct + - jlpAprLastUpdatedTimestamp + - jlpRealizedFeeUsd + - custodies + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /trades: + description: Fetches the trade history for the given wallet address + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: action + schema: + type: string + enum: + - Increase + - Decrease + - in: query + name: createdAtAfter + description: >- + Fetches trades with a 'createdAt' date that is greater or equal to + the given 'createdAtAfter' UNIX timestamp' + schema: + type: string + description: >- + Fetches trades with a 'createdAt' date that is greater or equal to + the given 'createdAtAfter' UNIX timestamp' + - in: query + name: createdAtBefore + description: >- + Fetches trades with a 'createdAt' date that is less than the given + 'createdAtBefore' UNIX timestamp' + schema: + type: string + description: >- + Fetches trades with a 'createdAt' date that is less than the given + 'createdAtBefore' UNIX timestamp' + - in: query + name: end + description: >- + The index of the last row to retrieve. This parameter specifies the + ending point for fetching rows from the dataset. It is exclusive, + meaning that the row at this index will not be included in the + results. + schema: + type: number + default: 20 + description: >- + The index of the last row to retrieve. This parameter specifies + the ending point for fetching rows from the dataset. It is + exclusive, meaning that the row at this index will not be included + in the results. + - in: query + name: mint + description: Mint address for the underlying position of the trade + schema: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: Mint address for the underlying position of the trade + - in: query + name: side + schema: + type: string + enum: + - long + - short + - in: query + name: start + description: >- + The index of the first row to retrieve. This parameter specifies the + starting point for fetching rows from the dataset. It is inclusive, + meaning that the row at this index will be included in the results + schema: + type: number + default: 0 + description: >- + The index of the first row to retrieve. This parameter specifies + the starting point for fetching rows from the dataset. It is + inclusive, meaning that the row at this index will be included in + the results + - in: query + name: walletAddress + description: >- + Public key for the wallet to fetch trades (required unless txid is + provided) + schema: + type: string + description: >- + Public key for the wallet to fetch trades (required unless txid is + provided) + - in: query + name: txid + description: Transaction ID for the trade to fetch directly + schema: + type: string + description: Transaction ID for the trade to fetch directly + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + count: + type: number + dataList: + type: array + items: + type: object + properties: + action: + type: string + enum: + - Increase + - Decrease + collateralUsdDelta: + type: string + description: >- + The collateral delta / change value (USD) for the + trade. `collateralUsdDelta` is negative for + collateral deposits and positive for collateral + withdrawals + example: '250.00' + createdTime: + type: number + description: UNIX timestamp of when the trade was created + example: 1722851463 + baseFee: + type: string + description: USD value of the base open / close fee for the trade + example: '0.45' + borrowFee: + type: string + description: USD value of the borrow fee for the trade + example: '0.45' + liquidationFee: + type: string + description: >- + USD value of the liquidation penalty for the + liquidation + example: '0.45' + priceImpactFee: + type: string + description: USD value of the price impact fee for the trade + example: '0.45' + fee: + type: string + description: >- + USD value of the fees paid (including the + liquidation penalty) for the trade + example: '0.45' + integratorFeeTokenAmount: + type: + - string + - 'null' + description: The fee token amount collected by the integrator + integratorFeeTokenMint: + type: + - string + - 'null' + description: >- + The mint address for the fee token collected by the + integrator + mint: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: >- + Mint address for the underlying position of the + trade + orderType: + type: string + enum: + - Market + - Trigger + - Liquidation + description: >- + 'Market' orders are orders placed by the trader. + 'Trigger' orders are orders executed by the keeper + for TP/SL requests. 'Liquidation' orders are also + executed by keeper when a position reaches its + liquidation price + owner: + type: string + description: The public key / address for the owner + pnl: + type: + - string + - 'null' + description: >- + USD value of the trade profit / loss. The PNL value + shown is before fees (i.e. it does not minus + opening, closing, borrowing, and price impact fees). + 'pnlUsd' is null for collateral deposits and + withdrawals as the realised PNL is unchanged + example: '24.13' + pnlPercentage: + type: + - string + - 'null' + description: >- + PNL percentage of the trade profit / loss. The PNL + percentage shown is before fees (i.e. it does not + minus opening, closing, borrowing, and price impact + fees). 'pnlPercentage' is null for collateral + deposits and withdrawals as the realised PNL is + unchanged + example: '24.13' + positionName: + type: string + enum: + - SOL-PERP + - ETH-PERP + - BTC-PERP + positionPubkey: + type: string + description: The public key / address for the position + price: + type: string + description: USD value of the position's entry price + example: '123.45' + side: + type: string + enum: + - long + - short + size: + type: string + description: >- + USD value of the position's trade size (including + leverage) + example: '12345.68' + transactionFeeLamports: + type: + - string + - 'null' + description: >- + The total transaction fee (lamports) paid for the + transaction + example: '5000' + priorityFeeLamports: + type: + - string + - 'null' + description: The priority fee (lamports) paid for the transaction + example: '2000' + swapFeeBps: + type: + - string + - 'null' + description: The swap fee (BPS) paid for the trade + example: '30' + swapFeeUsd: + type: + - string + - 'null' + description: The estimated swap fee ($) paid for the trade + example: '30' + swapFeeTokenAmount: + type: + - string + - 'null' + description: >- + The estimated swap fee (in the token amount) paid + for the trade + example: '100000' + swapFeeTokenMint: + type: + - string + - 'null' + description: The token mint address for the swap fee + txHash: + type: string + description: Transaction ID for the trade + example: >- + 4sjjb5kKAWAtXg1MQausgyqDx1Q5mU79a6EigxjjLYmCqBrNUE123XuoKr7Qir6ahBbLoSLLzT8gznxC2cgss5gR + updatedTime: + type: number + example: 1722851463 + required: + - action + - collateralUsdDelta + - createdTime + - baseFee + - borrowFee + - liquidationFee + - priceImpactFee + - fee + - mint + - orderType + - owner + - positionName + - positionPubkey + - price + - side + - size + - txHash + - updatedTime + required: + - count + - dataList + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /transaction/execute: + description: >- + Executes the serialized transaction passed to the endpoint which requires + the keeper to sign the and execute the transaction. + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + action: + type: string + enum: + - tpsl + - tpsl-with-fee + - limit-order + - increase-position + - increase-position-with-fee + - decrease-position + - decrease-position-with-fee + description: The action for the serialized transaction to be executed + serializedTxBase64: + type: string + description: Serialise signed transaction from user. + required: + - action + - serializedTxBase64 + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + action: + type: string + description: The action for the serialized transaction to be executed + txid: + type: string + description: The transaction id of the request + required: + - action + - txid + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /tpsl: + description: Returns a serialized transaction to create a TP/SL + delete: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + positionRequestPubkey: + type: string + description: The public key for the TP / SL request + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + required: + - positionRequestPubkey + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + requireKeeperSignature: + type: boolean + description: >- + When `requireKeeperSignature` is true, the transaction + must be signed, serialized, and sent to the the `POST + /transaction/execute` endpoint to execute the transaction. + When `requireKeeperSignature` is `false`, the transaction + can be submitted through the `sendTransaction` RPC call as + usual + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + transactionType: + type: string + enum: + - legacy + description: >- + Returns the type of serialized transaction to execute the + action. If the transaction type is `legacy`, the + transaction must be submitted by the client itself through + the RPC. If the transaction type is `instant`, the + transaction must be sent to the `POST + /transaction/execute` endpoint. + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - requireKeeperSignature + - serializedTxBase64 + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + walletAddress: + type: string + description: The public key for owner of the position. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + positionPubkey: + type: string + description: >- + The public key for the open position. Use the `GET + positions` endpoint to fetch the public key for the trader's + open positions. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + tpsl: + type: array + items: + type: object + properties: + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: >- + The token to receive when the TPSL is executed. Only + BTC, ETH, SOL, and USDC are currently supported. + entirePosition: + type: boolean + default: false + description: >- + Pass in `true` to close the entire position or `false` + to close a portion of the position (partial TPSL) + example: false + sizeUsdDelta: + type: + - string + - 'null' + description: >- + The amount in USD to decrease the position size by + (raw value with 6 decimal places). Required when + 'entirePosition' is false. + example: '10000000' + triggerPrice: + type: string + description: >- + Trigger price at which the TP / SL request will be + executed (raw value with 6 decimal places). For + example, to set a trigger price of $20, pass in + 20000000. + example: '20000000' + requestType: + type: string + enum: + - tp + - sl + description: >- + Pass in `tp` to set a take profit request or `sl` to + set a stop loss request + required: + - receiveToken + - triggerPrice + - requestType + maxItems: 20 + description: TPSL requests to set. + transactionType: + type: string + enum: + - instant + - mixed + default: instant + description: >- + Sets the type of serialized transaction to execute the + action. + required: + - walletAddress + - positionPubkey + - tpsl + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + tpslPubkeys: + type: array + items: + type: string + description: The position request account pubkeys for the TP / SL + requireKeeperSignature: + type: boolean + description: >- + When `requireKeeperSignature` is true, the transaction + must be signed, serialized, and sent to the the `POST + /transaction/execute` endpoint to execute the transaction. + When `requireKeeperSignature` is `false`, the transaction + can be submitted through the `sendTransaction` RPC call as + usual + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + tpslRequests: + type: array + items: + type: object + properties: + estimatedPnlUsd: + type: string + description: The estimated PNL (USD) for the TPSL request + estimatedPnlPercent: + type: string + description: The estimated PNL percentage for the TPSL request + hasProfit: + type: boolean + description: Whether the TPSL request has profit + requestType: + type: string + enum: + - tp + - sl + description: The type of TPSL request + positionRequestPubkey: + type: string + description: >- + The unique identifier (i.e. a program derived + address) for the position request. Use this address + to find the position request account onchain + required: + - estimatedPnlUsd + - estimatedPnlPercent + - hasProfit + - requestType + - positionRequestPubkey + description: >- + TPSL requests created with the increase position. Only + returned when TPSL is requested. + transactionType: + type: string + enum: + - legacy + - instant + description: >- + Returns the type of serialized transaction to execute the + action. If the transaction type is `legacy`, the + transaction must be submitted by the client itself through + the RPC. If the transaction type is `instant`, the + transaction must be sent to the `POST + /transaction/execute` endpoint. + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - tpslPubkeys + - requireKeeperSignature + - serializedTxBase64 + - tpslRequests + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + patch: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + positionRequestPubkey: + type: string + description: The public key for the TP / SL request + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + triggerPrice: + type: string + description: >- + Trigger price at which the TP / SL request will be executed + (raw value with 6 decimal places). For example, to set a + trigger price of $20, pass in 20000000. + example: '20000000' + transactionType: + type: string + enum: + - instant + - mixed + default: instant + description: >- + Sets the type of serialized transaction to execute the + action. If the transaction type is `instant`, the + transaction must be sent to the `POST /transaction/execute` + endpoint. If the transaction type is `mixed`, the + `transactionType` returned in the response will be either + `legacy` or `instant`. + required: + - positionRequestPubkey + - triggerPrice + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + requireKeeperSignature: + type: boolean + description: >- + When `requireKeeperSignature` is true, the transaction + must be signed, serialized, and sent to the the `POST + /transaction/execute` endpoint to execute the transaction. + When `requireKeeperSignature` is `false`, the transaction + can be submitted through the `sendTransaction` RPC call as + usual + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + tpslRequests: + type: array + items: + type: object + properties: + estimatedPnlUsd: + type: string + description: The estimated PNL (USD) for the TPSL request + estimatedPnlPercent: + type: string + description: The estimated PNL percentage for the TPSL request + hasProfit: + type: boolean + description: Whether the TPSL request has profit + requestType: + type: string + enum: + - tp + - sl + description: The type of TPSL request + positionRequestPubkey: + type: string + description: >- + The unique identifier (i.e. a program derived + address) for the position request. Use this address + to find the position request account onchain + required: + - estimatedPnlUsd + - estimatedPnlPercent + - hasProfit + - requestType + - positionRequestPubkey + description: TPSL requests updated + transactionType: + type: string + enum: + - legacy + - instant + description: >- + Returns the type of serialized transaction to execute the + action. If the transaction type is `legacy`, the + transaction must be submitted by the client itself through + the RPC. If the transaction type is `instant`, the + transaction must be sent to the `POST + /transaction/execute` endpoint. + txMetadata: + type: object + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: Contains relevant metadata for the serialized transaction. + required: + - requireKeeperSignature + - serializedTxBase64 + - tpslRequests + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /tpsl-with-fee: + description: Returns a serialized transaction to create a TP/SL and charge fees + delete: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + feeReceiver: + type: string + description: >- + The token address (ATA) to receive the fee specified in + `feeTokenAmount`. The ATA must match the token mint + specified in `feeToken` + feeToken: + type: string + enum: + - USDC + description: >- + The token symbol for the fee token. Currently only USDC is + supported. + feeTokenAmount: + type: string + description: >- + The amount of fee tokens to send to `feeReceiver`. The value + must match the token mint decimals specified in `feeToken` + (e.g., for USDC with 6 decimals, 1000000 = 1 USDC) + example: '1000000' + tpslPubkey: + type: string + description: >- + The public key for the position request account (TPSL) to + cancel + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + required: + - feeReceiver + - feeToken + - feeTokenAmount + - tpslPubkey + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + integratorFeeTokenMint: + type: string + description: The token mint for the integrator fee token + integratorFeeTokenAmount: + type: string + description: The amount of the integrator fee token + integratorFeeUsd: + type: string + description: >- + The estimated integrator fee in USD (raw value with 6 + decimal places) + integratorFeeUsdFormatted: + type: string + description: >- + The estimated integrator fee in USD (human-readable + format) + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions to cancel the TPSL request + transactionType: + type: string + enum: + - legacy + description: >- + The transaction can be signed and submitted through the + RPC + txMetadata: + type: object + properties: + accountRentLamports: + type: string + description: The account rent in lamports for the transaction + example: '0' + blockhash: + type: string + description: The blockhash used for the serialized transaction + lastValidBlockHeight: + type: string + description: The block height used for the serialized transaction + transactionFeeLamports: + type: string + description: The transaction fee in lamports + example: '5000' + required: + - accountRentLamports + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + description: Contains relevant metadata for the serialized transaction. + required: + - integratorFeeTokenMint + - integratorFeeTokenAmount + - integratorFeeUsd + - integratorFeeUsdFormatted + - serializedTxBase64 + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + feeReceiver: + type: string + description: >- + The token address (ATA) to receive the fee specified in + `feeTokenAmount`. The ATA must match the token mint + specified in `feeToken` + feeToken: + type: string + enum: + - USDC + description: >- + The token symbol for the fee token. Currently only USDC is + supported. Must be the same as input token. + feeTokenAmount: + type: string + description: >- + The amount of fee tokens to send to `feeReceiver`. The value + must match the token mint decimals specified in `feeToken` + (e.g., for USDC with 6 decimals, 1000000 = 1 USDC) + example: '1000000' + positionPubkey: + type: string + description: >- + The public key for the open position. Use the `GET + positions` endpoint to fetch the public key for the trader's + open positions. + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + tpsl: + type: array + items: + type: object + properties: + entirePosition: + type: boolean + default: false + description: >- + When set to `true`, this will close the position and + transfer the remaining collateral and realised profits + (if the position is profitable) to the trader. + example: false + receiveToken: + type: string + enum: + - BTC + - ETH + - SOL + - USDC + description: >- + The token to receive when the TPSL is executed. Must + be the asset itself or USDC. + requestType: + type: string + enum: + - tp + - sl + description: >- + Pass in `tp` to set a take profit request or `sl` to + set a stop loss request + sizeUsdDelta: + type: + - string + - 'null' + description: >- + The amount in USD to decrease the position size by. + Must be an integer representing the USD amount + multiplied by 10^6 (1 million) to align with the 6 + decimal places used for USDC/USDT tokens on-chain. For + example, to decrease by $10 USD, set 'sizeUsdDelta' to + 10000000; for $20.50 USD, set 'sizeUsdDelta' to + 20500000. + example: '10000000' + triggerPrice: + type: string + description: >- + Trigger price at which the TP / SL request will be + executed. The value must be an integer corresponding + to 6 decimal places. For example, to set a trigger + price of $20, pass in 20000000 + example: '20000000' + required: + - receiveToken + - requestType + - triggerPrice + description: TPSL requests to set + walletAddress: + type: string + description: >- + The wallet address / public key for the trader, Required + when opening a new position. + required: + - feeReceiver + - feeToken + - feeTokenAmount + - positionPubkey + - tpsl + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + integratorFeeTokenMint: + type: string + description: The token mint for the integrator fee token + integratorFeeTokenAmount: + type: string + description: The amount of the integrator fee token + integratorFeeUsd: + type: string + description: >- + The estimated integrator fee in USD (raw value with 6 + decimal places) + integratorFeeUsdFormatted: + type: string + description: >- + The estimated integrator fee in USD (human-readable + format) + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the decrease + position request. The transaction can be deserialized, + signed by the owner of `walletAddress` and submitted + onchain to execute the decrease position request + tpslPubkeys: + type: array + items: + type: string + description: The position request account pubkeys for the TP / SL + transactionType: + type: string + enum: + - instant + description: >- + Returns the type of serialized transaction to execute the + action. If the transaction type is `legacy`, the + transaction must be submitted by the client itself through + the RPC. If the transaction type is `instant`, the + transaction must be sent to the `POST + /transaction/execute` endpoint. + txMetadata: + type: object + properties: + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0' + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the signed + decrease position transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + signed decrease position transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + required: + - accountRentLamports + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + description: Contains relevant metadata for the serialized transaction. + required: + - integratorFeeTokenMint + - integratorFeeTokenAmount + - integratorFeeUsd + - integratorFeeUsdFormatted + - serializedTxBase64 + - tpslPubkeys + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + patch: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + feeReceiver: + type: string + description: >- + The token address (ATA) to receive the fee specified in + `feeTokenAmount`. The ATA must match the token mint + specified in `feeToken` + feeToken: + type: string + enum: + - USDC + description: >- + The token symbol for the fee token. Currently only USDC is + supported. + feeTokenAmount: + type: string + description: >- + The amount of fee tokens to send to `feeReceiver`. The value + must match the token mint decimals specified in `feeToken` + (e.g., for USDC with 6 decimals, 1000000 = 1 USDC) + example: '1000000' + tpslPubkey: + type: string + description: The public key for the position request account (TPSL) + example: 5HHB8sCKjWPU2zr3p4Lg49mQiaPQiHbCjHW7jgVzp583 + triggerPrice: + type: string + description: >- + New trigger price at which the TP / SL request will be + executed. The value must be an integer corresponding to 6 + decimal places. For example, to set a trigger price of $20, + pass in 20000000 + example: '20000000' + required: + - feeReceiver + - feeToken + - feeTokenAmount + - tpslPubkey + - triggerPrice + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + integratorFeeTokenMint: + type: string + description: The token mint for the integrator fee token + integratorFeeTokenAmount: + type: string + description: The amount of the integrator fee token + integratorFeeUsd: + type: string + description: >- + The estimated integrator fee in USD (raw value with 6 + decimal places) + integratorFeeUsdFormatted: + type: string + description: >- + The estimated integrator fee in USD (human-readable + format) + serializedTxBase64: + type: string + description: >- + The serialized transaction (base64 encoded) containing the + instructions to update the TPSL request + transactionType: + type: string + enum: + - instant + description: Always returns `instant` for fee-based transactions + txMetadata: + type: object + properties: + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0' + blockhash: + type: string + description: The blockhash used for the serialized transaction + lastValidBlockHeight: + type: string + description: The block height used for the serialized transaction + transactionFeeLamports: + type: string + description: The transaction fee in lamports + example: '5000' + required: + - accountRentLamports + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + description: Contains relevant metadata for the serialized transaction. + required: + - integratorFeeTokenMint + - integratorFeeTokenAmount + - integratorFeeUsd + - integratorFeeUsdFormatted + - serializedTxBase64 + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /lending/deposit-borrow: + description: Endpoint to deposit JLP and borrow USDC + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + depositTokenAmount: + type: string + description: >- + JLP token amount to deposit based on the JLP mint decimals + (6)` + borrowMint: + type: string + enum: + - EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v + description: Mint address for the borrow token + default: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v + borrowTokenAmount: + type: string + description: >- + Token amount for the borrow based on the mint decimals for + the borrow token defined in `borrowMint` + walletAddress: + type: string + description: Public key for the wallet to deposit / borrow + required: + - depositTokenAmount + - borrowTokenAmount + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + borrowSizeUsd: + type: string + description: >- + The borrowed amount (including interest) in USD formatted + to 6 decimals as per the USDC mint + borrowSizeTokenAmount: + type: string + description: >- + The borrowed amount (including interest) in the token + amount formatted to the borrowed token mint decimals + borrowTokenMint: + type: string + description: The mint address for the borrowed token + collateralTokenAmount: + type: string + description: Locked JLP token amount as collateral + collateralTokenUsd: + type: string + description: >- + Locked JLP token amount as collateral in USD formatted to + 6 decimals as per the USDC mint + maxBorrowTokenAmount: + type: string + description: >- + Maximum borrow amount in the token amount formatted to the + borrowed token mint decimals + maxBorrowTokenAmountBeforeBorrow: + type: string + description: >- + Maximum borrow amount in the token amount formatted to the + borrowed token mint decimals after deposit + maxBorrowUsd: + type: string + description: >- + Maximum borrow amount in USD formatted to 6 decimals as + per the USDC mint + maxWithdrawUsd: + type: string + description: >- + The maximum withdrawable amount in USD formatted to 6 + decimals as per the USDC mint + maxWithdrawTokenAmount: + type: string + description: The maximum withdrawable JLP token amount + maxRepayTokenAmount: + type: string + description: The maximum repayable USDC token amount for this position + liquidationPriceUsd: + type: string + description: >- + The JLP price at which the borrow position will be + liquidated in the token amount + ltvBps: + type: string + description: >- + LTV (loan-to-value) in basis points. A higher LTV express + a higher risk of liquidation + ltvPercentage: + type: string + description: >- + LTV (loan-to-value) percentage. A higher LTV express a + higher risk of liquidation + positionPubkey: + type: string + description: Pubkey for the borrow lending position + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the borrow / deposit + request. The transaction can be deserialized, signed by + the owner of `walletAddress` and submitted onchain. + requireKeeperSignature: + type: boolean + description: Whether the transaction requires a keeper signature + transactionType: + type: string + enum: + - legacy + - instant + description: The type of transaction + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the + transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - borrowSizeUsd + - borrowSizeTokenAmount + - borrowTokenMint + - collateralTokenAmount + - collateralTokenUsd + - maxBorrowTokenAmount + - maxBorrowTokenAmountBeforeBorrow + - maxBorrowUsd + - maxWithdrawUsd + - maxWithdrawTokenAmount + - maxRepayTokenAmount + - liquidationPriceUsd + - ltvBps + - ltvPercentage + - positionPubkey + - serializedTxBase64 + - requireKeeperSignature + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /lending/pay-withdraw: + description: Endpoint to repay debt with USDC and withdraw JLP + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + repayMint: + type: string + enum: + - EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v + description: Mint address for the payment token + default: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v + repayTokenAmount: + type: string + description: Token amount to pay for the position's debt + withdrawTokenAmount: + type: string + description: The JLP token amount to withdraw from the position + walletAddress: + type: string + description: Public key for the wallet to pay / withdraw + required: + - repayTokenAmount + - withdrawTokenAmount + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + borrowSizeUsd: + type: string + description: >- + The borrowed amount (including interest) in USD formatted + to 6 decimals as per the USDC mint + borrowSizeTokenAmount: + type: string + description: >- + The borrowed amount (including interest) in the token + amount formatted to the borrowed token mint decimals + borrowTokenMint: + type: string + description: The mint address for the borrowed token + collateralTokenAmount: + type: string + description: Locked JLP token amount as collateral + collateralTokenUsd: + type: string + description: >- + Locked JLP token amount as collateral in USD formatted to + 6 decimals as per the USDC mint + maxBorrowTokenAmount: + type: string + description: >- + Maximum borrow amount in the token amount formatted to the + borrowed token mint decimals + maxBorrowUsd: + type: string + description: >- + Maximum borrow amount in USD formatted to 6 decimals as + per the USDC mint + maxWithdrawUsd: + type: string + description: >- + The maximum withdrawable amount in USD formatted to 6 + decimals as per the USDC mint + maxWithdrawTokenAmount: + type: string + description: The maximum withdrawable JLP token amount + maxWithdrawTokenAmountBeforeWithdraw: + type: string + description: The maximum withdrawable JLP token amount before repaying + maxRepayTokenAmount: + type: string + description: The maximum repayable USDC token amount for this position + liquidationPriceUsd: + type: string + description: >- + The JLP price at which the borrow position will be + liquidated in the token amount + ltvBps: + type: string + description: >- + LTV (loan-to-value) in basis points. A higher LTV express + a higher risk of liquidation + ltvPercentage: + type: string + description: >- + LTV (loan-to-value) percentage. A higher LTV express a + higher risk of liquidation + positionPubkey: + type: string + description: Pubkey for the borrow lending position + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the borrow / deposit + request. The transaction can be deserialized, signed by + the owner of `walletAddress` and submitted onchain. + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the + transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + requireKeeperSignature: + type: boolean + description: Whether this transaction requires a keeper signature + transactionType: + type: string + const: legacy + description: The type of transaction + required: + - borrowSizeUsd + - borrowSizeTokenAmount + - borrowTokenMint + - collateralTokenAmount + - collateralTokenUsd + - maxBorrowTokenAmount + - maxBorrowUsd + - maxWithdrawUsd + - maxWithdrawTokenAmount + - maxWithdrawTokenAmountBeforeWithdraw + - maxRepayTokenAmount + - liquidationPriceUsd + - ltvBps + - ltvPercentage + - positionPubkey + - serializedTxBase64 + - txMetadata + - requireKeeperSignature + - transactionType + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /lending/positions: + description: Fetches the borrow lending positions for the given wallet address + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: walletAddress + description: Public key for the wallet to pay / withdraw + schema: + type: string + description: Public key for the wallet to pay / withdraw + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + dataList: + type: array + items: + type: object + properties: + borrowSizeUsd: + type: string + description: >- + The borrowed amount (including interest) for this + position in USD formatted to 6 decimals as per the + USDC mint + borrowSizeTokenAmount: + type: string + description: >- + The borrowed amount (including interest) for this + position in the token amount formatted to the + borrowed token mint decimals + borrowTokenMint: + type: string + description: The mint address for the borrowed token + maxBorrowTokenAmount: + type: string + description: >- + The maximum borrowable USDC token amount for this + position + maxBorrowUsd: + type: string + description: >- + Maximum borrow amount for this position in USD + formatted to 6 decimals as per the USDC mint + maxWithdrawUsd: + type: string + description: >- + The maximum withdrawable amount for this position in + USD formatted to 6 decimals as per the USDC mint + maxWithdrawTokenAmount: + type: string + description: >- + The maximum withdrawable JLP token amount for this + position + maxRepayTokenAmount: + type: string + description: >- + The maximum repayable USDC token amount for this + position + ltvBps: + type: string + description: >- + LTV (loan-to-value) percentage for the borrow + lending position. A higher LTV express a higher risk + of liquidation for the position + ltvPercentage: + type: string + description: >- + LTV (loan-to-value) percentage for the borrow + lending position. A higher LTV express a higher risk + of liquidation for the position + liquidationPriceUsd: + type: string + description: >- + The JLP price at which the borrow position will be + liquidated in the token amount + collateralTokenAmount: + type: string + description: >- + Locked JLP token amount as collateral in the borrow + lending position + collateralUsd: + type: string + description: >- + Locked JLP token amount as collateral in the borrow + lending position in USD formatted to 6 decimals as + per the USDC mint + positionPubkey: + type: string + description: Pubkey for the borrow lending position + required: + - borrowSizeUsd + - borrowSizeTokenAmount + - borrowTokenMint + - maxBorrowTokenAmount + - maxBorrowUsd + - maxWithdrawUsd + - maxWithdrawTokenAmount + - maxRepayTokenAmount + - ltvBps + - ltvPercentage + - liquidationPriceUsd + - collateralTokenAmount + - collateralUsd + - positionPubkey + count: + type: number + required: + - dataList + - count + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /lending/info: + description: Fetches global stats and info for the borrow lending pool + get: + security: + - ApiKeyAuth: [] + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + currentJlpPriceUsd: + type: string + description: >- + The current JLP price in USD formatted to 6 decimals as + per the USDC mint + borrowTokenMint: + type: string + description: The mint address for the borrow token + availableLiquidityUsd: + type: string + description: >- + Available liquidity for borrowing in USD formatted to 6 + decimals + availableLiquidityTokenAmount: + type: string + description: >- + Available liquidity for borrowing in token amount + formatted to token decimals + totalSupplyUsd: + type: string + description: Total supply in USD formatted to 6 decimals + totalSupplyTokenAmount: + type: string + description: Total supply in token amount formatted to token decimals + utilizationRateBps: + type: string + description: Current utilization rate in basis points (borrowed/total) + utilizationRatePercentage: + type: string + description: Current utilization rate as a percentage + borrowApr: + type: string + description: Current borrow APR as a percentage + liquidationMarginBps: + type: string + description: Liquidation margin threshold in basis points + liquidationMarginPercentage: + type: string + description: Liquidation margin as a percentage + liquidationPenaltyBps: + type: string + description: Liquidation penalty in basis points + liquidationPenaltyPercentage: + type: string + description: Liquidation penalty as a percentage + maxLtvBps: + type: string + description: Maximum LTV in basis points + maxLtvPercentage: + type: string + description: Maximum LTV as a percentage + required: + - currentJlpPriceUsd + - borrowTokenMint + - availableLiquidityUsd + - availableLiquidityTokenAmount + - totalSupplyUsd + - totalSupplyTokenAmount + - utilizationRateBps + - utilizationRatePercentage + - borrowApr + - liquidationMarginBps + - liquidationMarginPercentage + - liquidationPenaltyBps + - liquidationPenaltyPercentage + - maxLtvBps + - maxLtvPercentage + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /lending/history: + description: Fetches borrow lending history for the given wallet address + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: walletAddress + description: Filter by wallet address + schema: + type: string + description: Filter by wallet address + - in: query + name: borrowPositionPubkey + description: Filter by specific borrow position pubkey + schema: + type: string + description: Filter by specific borrow position pubkey + - in: query + name: transactionType + description: Filter by transaction type + schema: + type: string + enum: + - DepositCollateral + - WithdrawCollateral + - Borrow + - Repay + - Liquidation + description: Filter by transaction type + - in: query + name: createdAtAfter + description: >- + Fetches transactions with a 'createdAt' date that is greater or + equal to the given 'createdAtAfter' UNIX timestamp + schema: + type: string + description: >- + Fetches transactions with a 'createdAt' date that is greater or + equal to the given 'createdAtAfter' UNIX timestamp + - in: query + name: createdAtBefore + description: >- + Fetches transactions with a 'createdAt' date that is less than the + given 'createdAtBefore' UNIX timestamp + schema: + type: string + description: >- + Fetches transactions with a 'createdAt' date that is less than the + given 'createdAtBefore' UNIX timestamp + - in: query + name: start + description: >- + The index of the first row to retrieve. This parameter specifies the + starting point for fetching rows from the dataset. It is inclusive, + meaning that the row at this index will be included in the results + schema: + type: number + default: 0 + description: >- + The index of the first row to retrieve. This parameter specifies + the starting point for fetching rows from the dataset. It is + inclusive, meaning that the row at this index will be included in + the results + - in: query + name: end + description: >- + The index of the last row to retrieve. This parameter specifies the + ending point for fetching rows from the dataset. It is exclusive, + meaning that the row at this index will not be included in the + results. + schema: + type: number + default: 20 + description: >- + The index of the last row to retrieve. This parameter specifies + the ending point for fetching rows from the dataset. It is + exclusive, meaning that the row at this index will not be included + in the results. + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + dataList: + type: array + items: + type: object + properties: + txHash: + type: string + description: Solana transaction signature + transactionType: + type: string + enum: + - DepositCollateral + - WithdrawCollateral + - Borrow + - Repay + - Liquidation + description: Type of lending transaction + walletAddress: + type: string + description: Wallet address that initiated the transaction + borrowPositionPubkey: + type: string + description: Borrow position account pubkey + createdTime: + type: number + description: UNIX timestamp of when the transaction was created + tokenAmount: + type: string + description: >- + Token amount for the borrow / withdraw / repay / + deposit depending on the transaction type + tokenMint: + type: string + description: >- + Mint address of the token for the borrow / withdraw + / repay / deposit depending on the transaction type + required: + - txHash + - transactionType + - walletAddress + - borrowPositionPubkey + - createdTime + - tokenAmount + - tokenMint + description: List of lending transactions + count: + type: number + description: Total number of transactions matching the filter criteria + required: + - dataList + - count + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /top-traders: + description: Returns traders by top PNL and top volume according to the given period. + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: marketMint + description: Mint address for the given market to filter top trader data + schema: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: Mint address for the given market to filter top trader data + required: true + - in: query + name: year + description: The year for the week to query + schema: + type: string + description: The year for the week to query + required: true + - in: query + name: week + description: The week number (1-53) or "current" for the current week + schema: + anyOf: + - type: string + const: current + - type: string + description: The week number (1-53) or "current" for the current week + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + marketMint: + type: string + description: The market mint to filter top traders by. + totalVolumeUsd: + type: string + description: The total volume (USD) for the market. + startTimestamp: + type: number + description: >- + The start timestamp for the week (UNIX timestamp in + seconds). + endTimestamp: + type: number + description: >- + The end timestamp for the week (UNIX timestamp in + seconds). + topTradersByPnl: + type: array + items: + type: object + properties: + totalVolumeUsd: + type: string + description: The total volume (USD) for the trader. + totalPnlUsd: + type: string + description: The total PNL (USD) for the trader. + owner: + type: string + description: The wallet address for the trader. + required: + - totalVolumeUsd + - totalPnlUsd + - owner + description: The top 50 traders sorted by PNL in descending order. + topTradersByVolume: + type: array + items: + type: object + properties: + totalVolumeUsd: + type: string + description: The total volume (USD) for the trader. + totalPnlUsd: + type: string + description: The total PNL (USD) for the trader. + owner: + type: string + description: The wallet address for the trader. + required: + - totalVolumeUsd + - totalPnlUsd + - owner + description: The top 50 traders sorted by volume in descending order. + required: + - marketMint + - totalVolumeUsd + - startTimestamp + - endTimestamp + - topTradersByPnl + - topTradersByVolume + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /trader-stats: + description: Returns stats for the given trader + get: + security: + - ApiKeyAuth: [] + parameters: + - in: query + name: walletAddress + description: The pubkey of trader to get volume data + schema: + type: string + description: The pubkey of trader to get volume data + required: true + - in: query + name: marketMint + description: Mint address for the given market to filter top trader data + schema: + type: string + enum: + - So11111111111111111111111111111111111111112 + - 7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs + - 3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh + description: Mint address for the given market to filter top trader data + required: true + - in: query + name: year + description: The year for the week to query + schema: + type: string + description: The year for the week to query + required: true + - in: query + name: week + description: The week number (1-53) or "current" for the current week + schema: + anyOf: + - type: string + const: current + - type: string + description: The week number (1-53) or "current" for the current week + required: true + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + totalVolumeUsd: + type: string + description: The total volume (USD) for the trader. + totalPnlUsd: + type: string + description: The total PNL (USD) for the trader. + startTimestamp: + type: number + description: >- + The start timestamp for the week (UNIX timestamp in + seconds). + endTimestamp: + type: number + description: >- + The end timestamp for the week (UNIX timestamp in + seconds). + required: + - totalVolumeUsd + - totalPnlUsd + - startTimestamp + - endTimestamp + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /jlp/burn: + description: Endpoint to burn JLP + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + burnTokenAmount: + type: string + description: >- + The amount of JLP tokens to burn scaled to 6 decimal places + as per the JLP mint + receiveToken: + type: string + enum: + - WBTC + - ETH + - SOL + - USDC + description: Token to receive from burning JLP + walletAddress: + type: string + description: Public key for the wallet to burn JLP + required: + - burnTokenAmount + - receiveToken + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + burnFeeBps: + type: string + description: JLP burn fee (BPS) + burnFeePercent: + type: string + description: JLP burn fee (%) + burnFeeTokenAmount: + type: string + description: JLP burn fee in the receive token + receiveToken: + type: string + description: The receive token from burning JLP + receiveTokenAmount: + type: string + description: >- + The amount of the receive token to receive from burning + JLP after fees + receiveTokenCustody: + type: string + description: The receive token's custody pubkey + receiveTokenMint: + type: string + description: The receive token's mint pubkey + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the borrow / deposit + request. The transaction can be deserialized, signed by + the owner of `walletAddress` and submitted onchain. + transactionType: + type: string + enum: + - legacy + description: The type of transaction + default: legacy + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the + transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - burnFeeBps + - burnFeePercent + - burnFeeTokenAmount + - receiveToken + - receiveTokenAmount + - receiveTokenCustody + - receiveTokenMint + - serializedTxBase64 + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + /jlp/mint: + description: Endpoint to mint JLP + post: + security: + - ApiKeyAuth: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + depositToken: + type: string + enum: + - WBTC + - ETH + - SOL + - USDC + description: Token to deposit to mint JLP + depositTokenAmount: + type: string + description: The amount of the deposit token to deposit to mint JLP + walletAddress: + type: string + description: Public key for the wallet to mint JLP + required: + - depositToken + - depositTokenAmount + - walletAddress + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + mintFeeBps: + type: string + description: JLP mint fee (BPS) + mintFeePercent: + type: string + description: JLP mint fee (%) + mintTokenAmount: + type: string + description: The amount of JLP minted (after fees) + serializedTxBase64: + type: + - string + - 'null' + description: >- + The serialized transaction (base64 encoded) containing the + instructions and given parameters for the mint request. + The transaction can be deserialized, signed by the owner + of `walletAddress` and submitted onchain. + transactionType: + type: string + enum: + - legacy + description: The type of transaction + default: legacy + txMetadata: + type: + - object + - 'null' + properties: + blockhash: + type: string + description: >- + The blockhash used for the serialized transaction. + This blockhash must be used when submitting the + transaction. + lastValidBlockHeight: + type: string + description: >- + The block height used for the serialized transaction. + This block height must be used when submitting the + transaction. + transactionFeeLamports: + type: string + description: The transaction fee (in lamports) in decimal format. + example: '0.5' + accountRentLamports: + type: string + description: The account rent (in lamports) for the transaction + example: '0.5' + required: + - blockhash + - lastValidBlockHeight + - transactionFeeLamports + - accountRentLamports + description: >- + Contains relevant metadata for the serialized transaction. + Null if no wallet address passed in. + required: + - mintFeeBps + - mintFeePercent + - mintTokenAmount + - serializedTxBase64 + - transactionType + - txMetadata + '400': + description: 400 Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '404': + description: 404 Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '422': + description: 422 Unprocessable entity + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' + '500': + description: 500 Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/errorSchema' +components: + securitySchemes: + ApiKeyAuth: + type: apiKey + in: header + name: x-api-key + description: Get API key via https://portal.jup.ag + schemas: + errorSchema: + type: object + properties: + code: + type: string + message: + type: string + required: + - code + - message + description: Error object + example: + code: http_error + message: >- + Invalid path /hello-world. Consult the OpenAPI documentation for the + list of valid routes: https://perps-api.jup.ag/v1/docs diff --git a/static/images/linear-price-impact-fee.png b/static/images/linear-price-impact-fee.png new file mode 100644 index 00000000..df52c9d5 Binary files /dev/null and b/static/images/linear-price-impact-fee.png differ