jup-ag · 0xYankee-Raccoons · May 20, 2025 · Apr 21, 2025 · Apr 22, 2025 · Apr 22, 2025
diff --git a/docs/101-ultra-api/README.md b/docs/101-ultra-api/README.md
@@ -18,10 +18,11 @@ The Jupiter Ultra API is the *only* API you ever need to experience or build the
 | **Best liquidity engine** | Aggregates across multiple liquidity sources, both Jupiter's proprietary routing engines and third-party liquidity sources, for the best possible price.<br/><br />Including Jupiter's Metis Routing Engine, Jupiter Z (RFQ), and others. |
 | **Blazing fast** | 95% of all swaps are executed under 2 seconds via our proprietary transaction sending engine. |
 | **MEV-protected** | The lowest incidence of MEV attacks across all existing applications, by far. |
+| **Shielded** | Enhanced security feature via Shield API to provide critical token information during token selection, to help provide an informed trading decision. |
 | **Real-Time Slippage Estimator** | Intelligently derives the best possible slippage to use at the time of execution, balancing between trade success and price protection. |
 | **Gasless Support** | Enables gasless transactions for users with certain tokens and trade sizes, you can identify this via the secondary signer in the transaction. |
 | **One-stop shop** | Retrieve the user's balances, get a quote, execute the trade, and get the results of the trade, all within Ultra API without touching a single RPC or any other external API. |
-| **World class support** | We handle the complexities of RPC connections, transaction landing, slippage protection and more. |
+| **World class support** | We handle the complexities of RPC connections, transaction landing, slippage protection and more. | |
 
 ## What About Swap API?
 

diff --git a/docs/300-tool-kits/README.md b/docs/300-tool-kits/README.md
@@ -20,8 +20,8 @@ Jupiter Tool Kits are a collection of developer tools and SDKs that help you int
 
 ## Jupiter Tool Kits
 
-- [**Swap Terminal**](/docs/tool-kits/swap-terminal): A ready-to-use swap interface that can be embedded into any website.
-- [**Unified Wallet Kit**](/docs/tool-kits/unified-wallet-kit): A wallet interface that can be embedded into any website.
+- [**Swap Terminal**](/docs/tool-kits/terminal/): A ready-to-use swap interface that can be embedded into any website.
+- [**Unified Wallet Kit**](/docs/tool-kits/wallet-kit/): A wallet interface that can be embedded into any website.
 
 ## Community Contributions
 

diff --git a/docs/300-tool-kits/terminal/README.md b/docs/300-tool-kits/terminal/README.md
@@ -0,0 +1,56 @@
+---
+sidebar_label: "Introduction"
+description: "An overview of Jupiter Swap Terminal and its core features."
+title: "Introduction to Terminal"
+---
+
+![Jupiter Terminal Hero](/terminal/demo/terminal.png)
+
+Jupiter Terminal is an open-source, lightweight, plug-and-play version of Jupiter that allows you to seamlessly integrate end-to-end swap functionality into your application with minimal effort - with just a few lines of code, you can embed a fully functional swap interface directly into your website while providing the same powerful Ultra Mode swap experience found on https://jup.ag.
+
+:::info Terminal Playground
+Try out the [Terminal Playground](https://terminal.jup.ag/playground) to experience the full swap features and see the different customization options with code snippets.
+
+To view the open-source code, visit the [GitHub repository](https://github.com/jup-ag/terminal).
+:::
+
+:::info Quick Start
+To quick start your integration, check out the [Next.js](/docs/tool-kits/terminal/nextjs-app-example), [React](/docs/tool-kits/terminal/react-app-example) or [HTML](/docs/tool-kits/terminal/html-app-example) app examples.
+:::
+
+## Key Features
+
+- **Seamless Integration**: Embed Jupiter's swap functionality directly into your application without redirects.
+- **Multiple Display Options**: Choose between integrated, widget, or modal display modes.
+- **Customizable Options**: Configure the terminal to match your application's needs.
+- **RPC-less**: Integrate Terminal without any RPCs, Ultra handles transaction sending, wallet balances and token information.
+- **Ultra Mode**: Access to all features of Ultra Mode, read more about it in the [Ultra API docs](/docs/ultra-api/).
+
+## Getting Started
+
+When integrating Terminal, there are a few integration methods to think about, and choose the one that best fits your application's architecture and requirements.
+
+### Integration Methods
+
+- **Using Window Object** - Simplest way to add and initialize Terminal.
+- [**Using NPM Package**](https://www.npmjs.com/package/@jup-ag/terminal) - Install via `npm install @jup-ag/terminal` and initialize as a module (will require you to maintain its dependencies).
+
+### Wallet Integration
+
+- **Wallet Standard Support**: For applications without existing wallet provider, Terminal will provide a wallet adapter and connection - powered by [Unified Wallet Kit](/docs/tool-kits/wallet-kit/).
+- **Passthrough Wallet**: For applications with existing wallet provider(s), set `enableWalletPassthrough=true` with context, and Terminal will allow the application to pass through the existing wallet provider's connection to Terminal.
+
+### Adding Fees to Terminal
+
+- **Referral Account**: You can create a referral account via [scripts](/docs/ultra-api/add-fees-to-ultra) or [Referral Dashboard](https://referral.jup.ag).
+- **Referral Fee**: You can set the referral fee and account in the `formProps` interface when you initialize the Terminal.
+
+### Quick Start Guides
+
+In the next sections, we'll walk you through the steps to integrate Jupiter Terminal into different types of web applications from scratch.
+
+- [Next.js](/docs/tool-kits/terminal/nextjs-app-example)
+- [React](/docs/tool-kits/terminal/react-app-example)
+- [HTML](/docs/tool-kits/terminal/html-app-example)
+
+By integrating Jupiter Terminal into your application, you can seamlessly integrate a fully functional swap interface into your application with minimal effort, while staying at the forefront of Solana DeFi innovation.
diff --git a/docs/300-tool-kits/terminal/customization.md b/docs/300-tool-kits/terminal/customization.md
@@ -0,0 +1,247 @@
+---
+sidebar_label: "Customizing Terminal"
+description: "Learn how to customize Jupiter Terminal's appearance and behavior."
+title: "Customizing Terminal"
+---
+
+<head>
+    <title>Customizing Terminal</title>
+    <meta name="twitter:card" content="summary" />
+</head>
+
+Try out the [Terminal Playground](https://terminal.jup.ag/playground) to experience the full swap features and see the different customization options with code snippets.
+
+For the full customization options, you can refer to the [repository](https://github.com/jup-ag/terminal/blob/main/src/types/index.d.ts).
+
+If you are using TypeScript, you can use the type declaration file to get the full type definitions for the Terminal.
+
+<details>
+  <summary>
+    Full TypeScript Declaration
+  </summary>
+
+```typescript
+declare global {
+    interface Window {
+        Jupiter: JupiterTerminal;
+    }
+}
+
+export type WidgetPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
+export type WidgetSize = 'sm' | 'default';
+export type SwapMode = "ExactInOrOut" | "ExactIn" | "ExactOut";
+export type DEFAULT_EXPLORER = 'Solana Explorer' | 'Solscan' | 'Solana Beach' | 'SolanaFM';
+
+export interface FormProps {
+    swapMode?: SwapMode;
+    initialAmount?: string;
+    initialInputMint?: string;
+    initialOutputMint?: string;
+    fixedAmount?: boolean;
+    fixedMint?: string;
+    referralAccount?: string;
+    referralFee?: number;
+}
+
+export interface IInit {
+    localStoragePrefix?: string;
+    formProps?: FormProps;
+    defaultExplorer?: DEFAULT_EXPLORER;
+    autoConnect?: boolean;
+    displayMode?: 'modal' | 'integrated' | 'widget';
+    integratedTargetId?: string;
+    widgetStyle?: {
+        position?: WidgetPosition;
+        size?: WidgetSize;
+    };
+    containerStyles?: CSSProperties;
+    containerClassName?: string;
+    enableWalletPassthrough?: boolean;
+    passthroughWalletContextState?: WalletContextState;
+    onRequestConnectWallet?: () => void | Promise<void>;
+    onSwapError?: ({
+        error,
+        quoteResponseMeta,
+    }: {
+        error?: TransactionError;
+        quoteResponseMeta: QuoteResponse | null;
+    }) => void;
+    onSuccess?: ({
+        txid,
+        swapResult,
+        quoteResponseMeta,
+    }: {
+        txid: string;
+        swapResult: SwapResult;
+        quoteResponseMeta: QuoteResponse | null;
+    }) => void;
+    onFormUpdate?: (form: IForm) => void;
+    onScreenUpdate?: (screen: IScreen) => void;
+}
+
+export interface JupiterTerminal {
+    _instance: JSX.Element | null;
+    init: (props: IInit) => void;
+    resume: () => void;
+    close: () => void;
+    root: Root | null;
+    enableWalletPassthrough: boolean;
+    onRequestConnectWallet: IInit['onRequestConnectWallet'];
+    store: ReturnType<typeof createStore>;
+    syncProps: (props: { passthroughWalletContextState?: IInit['passthroughWalletContextState'] }) => void;
+    onSwapError: IInit['onSwapError'];
+    onSuccess: IInit['onSuccess'];
+    onFormUpdate: IInit['onFormUpdate'];
+    onScreenUpdate: IInit['onScreenUpdate'];
+    localStoragePrefix: string;
+}
+
+export { };
+```
+
+</details>
+
+## Display Modes
+
+Jupiter Terminal offers three distinct display modes to suit different use cases:
+
+### 1. Integrated Mode
+
+The integrated mode embeds the terminal directly into your application's layout. This is ideal for creating a seamless swap experience within your dApp.
+
+```typescript
+{
+  displayMode: "integrated",
+  integratedTargetId: string, // Required: ID of the container element
+  containerStyles?: {
+    width?: string,
+    height?: string,
+    borderRadius?: string,
+    overflow?: string
+  },
+  containerClassName?: string
+}
+```
+
+### 2. Widget Mode
+
+The widget mode creates a floating terminal that can be positioned in different corners of the screen. Perfect for quick access to swaps without taking up too much space.
+
+```typescript
+{
+  displayMode: "widget",
+  widgetStyle?: {
+    position?: "top-left" | "top-right" | "bottom-left" | "bottom-right",
+    size?: "sm" | "default"
+  },
+}
+```
+
+### 3. Modal Mode
+
+The modal mode displays the terminal in a popup overlay. This is useful when you want to keep the terminal hidden until needed.
+
+```typescript
+{
+  displayMode: "modal",
+}
+```
+
+## Form Props Configuration
+
+The `formProps` object allows you to customize the initial state and behavior of the swap form! This can be useful for use cases like fixed token swaps for memecoin communities or fixed amount payments.
+
+```typescript
+{
+  displayMode: "modal",
+  formProps?: {
+    swapMode?: SwapMode, // Set the swap mode to "ExactIn", "ExactOut", or default to "ExactInOrOut"
+
+    initialAmount?: string, // Pre-fill the swap amount (e.g. "100")
+    initialInputMint?: string, // Pre-select the input token by its mint address
+    initialOutputMint?: string, // Pre-select the output token by its mint address
+
+    fixedAmount?: boolean, // When true, users cannot change the swap amount
+    fixedMint?: string, // Lock one side of the swap to a specific token by its mint address
+
+    referralAccount?: string, // Set the referral account for the swap
+    referralFee?: number, // Set the referral fee for the swap
+  }
+}
+```
+
+## Wallet Integration
+
+Jupiter Terminal supports third-party wallet integration through the `enableWalletPassthrough` prop. This allows your application to pass through an existing wallet provider's connection in your application to Terminal. If you do not have an existing wallet provider, Terminal will provide a wallet adapter and connection - powered by [Unified Wallet Kit](/docs/tool-kits/wallet-kit/).
+
+```typescript
+{
+  // When true, wallet connection are handled by your dApp,
+  // and use `syncProps()` to syncronise wallet state with Terminal.
+  enableWalletPassthrough?: boolean,
+
+  // When enableWalletPassthrough is true, this allows Terminal 
+  // to callback your app's wallet connection flow
+  onRequestConnectWallet?: () => void | Promise<void>;
+}
+```
+
+## Event Handling
+
+Jupiter Terminal provides event handlers to track swap operations:
+
+```typescript
+{
+  onSuccess: ({ txid, swapResult, quoteResponseMeta }) => {
+    // Handle successful swap
+    console.log("Swap successful:", txid);
+  },
+  onSwapError: ({ error, quoteResponseMeta }) => {
+    // Handle swap errors
+    console.error("Swap failed:", error);
+  }
+}
+```
+
+## Examples
+
+### Fixed SOL Swap
+
+```typescript
+window.Jupiter.init({
+  displayMode: "integrated",
+  integratedTargetId: "swap-container",
+  formProps: {
+    initialInputMint: "So11111111111111111111111111111111111111112", // SOL
+    initialOutputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
+    fixedMint: "So11111111111111111111111111111111111111112",
+  },
+});
+```
+
+### Payment Integration
+
+```typescript
+window.Jupiter.init({
+  displayMode: "modal",
+  formProps: {
+    swapMode: "ExactOut",
+    initialAmount: "10",
+    fixedAmount: true,
+    initialOutputMint: "YOUR_TOKEN_MINT",
+    fixedMint: "YOUR_TOKEN_MINT",
+  },
+});
+```
+
+### Floating Widget
+
+```typescript
+window.Jupiter.init({
+  displayMode: "widget",
+  widgetStyle: {
+    position: "bottom-right",
+    size: "sm",
+  },
+});
+```
diff --git a/docs/300-tool-kits/terminal/faq.md b/docs/300-tool-kits/terminal/faq.md
@@ -0,0 +1,54 @@
+---
+sidebar_label: "FAQ"
+description: "Terminal FAQ"
+title: "FAQ"
+---
+
+<head>
+    <title>Terminal FAQ</title>
+    <meta name="twitter:card" content="summary" />
+</head>
+
+**1. How do I feature request or get support?**
+
+- For feature requests, please open an issue on the [GitHub repository](https://github.com/jup-ag/terminal/issues) and tag us on Discord.
+- For support, please join the [Discord server](https://discord.gg/jup) and get help in the developer channels.
+
+**2. How do I add fees to Terminal?**
+
+- **Creating Referral Account and Token Accounts**: You can create via [scripts](/docs/ultra-api/add-fees-to-ultra) or [Referral Dashboard](https://referral.jup.ag).
+- **Adding to FormProps**: You can set the referral account and fee in the [`formProps` interface](/docs/tool-kits/terminal/customization#form-props-configuration) when you initialize the Terminal.
+
+**3. Integrated Mode: Token Search Modal Collapses Terminal**
+
+- Ensure you establish a fixed height for the terminal container under `containerStyles`
+
+```typescript
+{
+   displayMode: "integrated",
+   integratedTargetId: "jupiter-terminal",
+   containerStyles: {
+      height: "500px",
+   },
+}
+```
+
+## Best Practices for Customization
+
+**1. Responsive Design**
+
+   - Use percentage-based widths for container styles
+   - Test on different screen sizes
+   - Consider mobile-first design
+
+**2. User Experience**
+
+   - Position widgets in easily accessible locations
+   - Consider fixed token pairs for specific use cases
+   - Implement proper error handling and prompts
+
+**3. Security**
+
+   - Use environment variables for sensitive data
+   - Implement proper error boundaries
+   - Validate user inputs