jup-ag · 0xYankee-Raccoons · Oct 30, 2025
diff --git a/api-reference/perps.mdx b/api-reference/perps.mdx
@@ -0,0 +1,5 @@
+---
+title: "Perps (Beta)"
+sidebarTitle: "Overview"
+description: "Overview of Jupiter Perps API"
+---
diff --git a/api-reference/perps/delete-tpsl.mdx b/api-reference/perps/delete-tpsl.mdx
@@ -0,0 +1,5 @@
+---
+title: "DELETE TPSL"
+sidebarTitle: "TPSL"
+openapi: /openapi-spec/perps/perps.yaml delete /tpsl
+---
diff --git a/api-reference/perps/get-market-stats.mdx b/api-reference/perps/get-market-stats.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Market Stats"
+sidebarTitle: "Market Stats"
+openapi: /openapi-spec/perps/perps.yaml get /market-stats
+---
diff --git a/api-reference/perps/get-ordersexpired.mdx b/api-reference/perps/get-ordersexpired.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Orders Expired"
+sidebarTitle: "Orders Expired"
+openapi: /openapi-spec/perps/perps.yaml get /orders/expired
+---
diff --git a/api-reference/perps/get-pool-info.mdx b/api-reference/perps/get-pool-info.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Pool Info"
+sidebarTitle: "Pool Info"
+openapi: /openapi-spec/perps/perps.yaml get /pool-info
+---
diff --git a/api-reference/perps/get-positions.mdx b/api-reference/perps/get-positions.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Positions"
+sidebarTitle: "Positions"
+openapi: /openapi-spec/perps/perps.yaml get /positions
+---
diff --git a/api-reference/perps/get-positionscollateral-limits.mdx b/api-reference/perps/get-positionscollateral-limits.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Positions Collateral Limits"
+sidebarTitle: "Positions Collateral Limits"
+openapi: /openapi-spec/perps/perps.yaml get /positions/collateral-limits
+---
diff --git a/api-reference/perps/get-top-traders.mdx b/api-reference/perps/get-top-traders.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Top Traders"
+sidebarTitle: "Top Traders"
+openapi: /openapi-spec/perps/perps.yaml get /top-traders
+---
diff --git a/api-reference/perps/get-trader-stats.mdx b/api-reference/perps/get-trader-stats.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Trader Stats"
+sidebarTitle: "Trader Stats"
+openapi: /openapi-spec/perps/perps.yaml get /trader-stats
+---
diff --git a/api-reference/perps/get-trades.mdx b/api-reference/perps/get-trades.mdx
@@ -0,0 +1,5 @@
+---
+title: "GET Trades"
+sidebarTitle: "Trades"
+openapi: /openapi-spec/perps/perps.yaml get /trades
+---
diff --git a/api-reference/perps/others/get-jlp-info.mdx b/api-reference/perps/others/get-jlp-info.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml get /jlp-info
+---
diff --git a/api-reference/perps/others/get-lendinghistory.mdx b/api-reference/perps/others/get-lendinghistory.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml get /lending/history
+---
diff --git a/api-reference/perps/others/get-lendinginfo.mdx b/api-reference/perps/others/get-lendinginfo.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml get /lending/info
+---
diff --git a/api-reference/perps/others/get-lendingpositions.mdx b/api-reference/perps/others/get-lendingpositions.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml get /lending/positions
+---
diff --git a/api-reference/perps/others/post-jlpburn.mdx b/api-reference/perps/others/post-jlpburn.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml post /jlp/burn
+---
diff --git a/api-reference/perps/others/post-jlpmint.mdx b/api-reference/perps/others/post-jlpmint.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml post /jlp/mint
+---
diff --git a/api-reference/perps/others/post-lendingdeposit-borrow.mdx b/api-reference/perps/others/post-lendingdeposit-borrow.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml post /lending/deposit-borrow
+---
diff --git a/api-reference/perps/others/post-lendingpay-withdraw.mdx b/api-reference/perps/others/post-lendingpay-withdraw.mdx
@@ -0,0 +1,3 @@
+---
+openapi: /openapi-spec/perps/perps.yaml post /lending/pay-withdraw
+---
diff --git a/api-reference/perps/patch-tpsl.mdx b/api-reference/perps/patch-tpsl.mdx
@@ -0,0 +1,5 @@
+---
+title: "PATCH TPSL"
+sidebarTitle: "TPSL"
+openapi: /openapi-spec/perps/perps.yaml patch /tpsl
+---
diff --git a/api-reference/perps/post-positionsclose-all.mdx b/api-reference/perps/post-positionsclose-all.mdx
@@ -0,0 +1,5 @@
+---
+title: "POST Positions Close All"
+sidebarTitle: "Positions Close All"
+openapi: /openapi-spec/perps/perps.yaml post /positions/close-all
+---
diff --git a/api-reference/perps/post-positionsdecrease.mdx b/api-reference/perps/post-positionsdecrease.mdx
@@ -0,0 +1,5 @@
+---
+title: "POST Positions Decrease"
+sidebarTitle: "Positions Decrease"
+openapi: /openapi-spec/perps/perps.yaml post /positions/decrease
+---
diff --git a/api-reference/perps/post-positionsincrease.mdx b/api-reference/perps/post-positionsincrease.mdx
@@ -0,0 +1,5 @@
+---
+title: "POST Positions Increase"
+sidebarTitle: "Positions Increase"
+openapi: /openapi-spec/perps/perps.yaml post /positions/increase
+---
diff --git a/api-reference/perps/post-tpsl.mdx b/api-reference/perps/post-tpsl.mdx
@@ -0,0 +1,5 @@
+---
+title: "POST TPSL"
+sidebarTitle: "TPSL"
+openapi: /openapi-spec/perps/perps.yaml post /tpsl
+---
diff --git a/docs.json b/docs.json
@@ -158,8 +158,15 @@
             "icon": "chart-line",
             "groups": [
               {
-                "group": " ",
-                "pages": ["docs/perps/index"]
+                "group": "About Perps",
+                "pages": [
+                  "docs/perps/index",
+                  "docs/perps/get-started",
+                  "docs/perps/jlp",
+                  "docs/perps/oracles",
+                  "docs/perps/fees",
+                  "docs/perps/liquidation"
+                ]
               },
               {
                 "group": "Perps Program",
@@ -391,6 +398,27 @@
                   }
                 ]
               },
+              {
+                "group": "Perps",
+                "tag": "BETA",
+                "pages": [
+                  "api-reference/perps",
+                  "api-reference/perps/get-positions",
+                  "api-reference/perps/post-positionsincrease",
+                  "api-reference/perps/post-positionsdecrease",
+                  "api-reference/perps/post-positionsclose-all",
+                  "api-reference/perps/post-tpsl",
+                  "api-reference/perps/patch-tpsl",
+                  "api-reference/perps/delete-tpsl",
+                  "api-reference/perps/get-ordersexpired",
+                  "api-reference/perps/get-market-stats",
+                  "api-reference/perps/get-positionscollateral-limits",
+                  "api-reference/perps/get-trades",
+                  "api-reference/perps/get-top-traders",
+                  "api-reference/perps/get-trader-stats",
+                  "api-reference/perps/get-pool-info"
+                ]
+              },
               {
                 "group": "Trigger",
                 "pages": [

diff --git a/docs/perps/fees.mdx b/docs/perps/fees.mdx
diff --git a/docs/perps/get-started.mdx b/docs/perps/get-started.mdx
@@ -0,0 +1,46 @@
+---
+title: "Get Started"
+description: "Get started to develop with Jupiter Perpetuals."
+---
+
+## API Reference
+<Note>
+Refer to the [Perps API Reference](/api-reference/perps) for the complete API documentation.
+</Note>
+
+## 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. |
+
+## FAQ
+
+<AccordionGroup>
+<Accordion title="Can I add custom integrator fees to Ultra Swap API?">
+
+* **Integrator without custom fees**: Do note that when your users swap using Ultra Swap, we take 5 to 10 bps of the swap amount as a fee.
+* **Integrator with custom fees**: If you are an integrator, you can add custom integrator fees via Ultra Swap API and Jupiter will take 20% of the integrator fees. Please refer to the [Add Fees To Ultra Swap](/docs/ultra/add-fees-to-ultra) guide for more information.
+</Accordion>
+
+<Accordion title="Can I modify Ultra Swap transactions?">
+* No, you cannot modify Ultra Swap transactions.
+* Ultra Swap is intended to use as is, without any modifications.
+</Accordion>
+
+<Accordion title="What is the rate limit for Ultra Swap API?">
+* Dynamic Rate Limits are now applied to Ultra Swap API.
+
+  * No Pro plans or payment needed.
+  * Simply generate the universal API Key via [Portal](https://portal.jup.ag)
+  * Rate limits scale together with your swap volume.
+  * [Read more about Ultra Swap API Dynamic Rate Limit](/portal/rate-limit).
+</Accordion>
+</AccordionGroup>
diff --git 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>
-  **WARNING**
+## Features
 
-  The Perps API is still a **work in progress**, stay tuned!
-</Warning>
+In this overview, we will cover the core features of the Jupiter Perps 
+and how it differs from traditional leverage trading exchanges.
 
-<Tip>
-  **TIP**
-
-  In the meantime, you can use this amazing github repository to direct Anchor IDL parse the Perps Program.
+<Note>
+  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.
+</Note>
 
-  * 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)
-</Tip>
+**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.mdx b/docs/perps/jlp.mdx
diff --git a/docs/perps/liquidation.mdx b/docs/perps/liquidation.mdx
diff --git a/docs/perps/oracles.mdx b/docs/perps/oracles.mdx
diff --git 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
+<Note>
+Refer to the [Ultra Swap API Reference](/api-reference/ultra) for the complete API documentation.
+</Note>
+
+## 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