### Quick start

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-information.mdx

A quick start example using curl to search for tokens by query.

```bash
curl -X GET "https://api.jup.ag/tokens/v2/search?query=JUP" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Install Libraries

Source: https://github.com/jup-ag/docs/blob/main/get-started/environment-setup.mdx

Install @solana/web3.js (v1) for transaction handling and @solana/spl-token for SPL token operations.

```bash
npm install @solana/web3.js@1 @solana/spl-token bs58
```

--------------------------------

### Install the package

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/react-app-example.mdx

Command to install the @jup-ag/plugin package using npm.

```bash
npm install @jup-ag/plugin
```

--------------------------------

### Full Referral SDK Example

Source: https://github.com/jup-ag/docs/blob/main/ultra/add-fees-to-ultra.mdx

This example demonstrates the complete workflow for setting up and managing referral accounts and fees using the referral SDK. It includes initializing referral accounts, setting up token accounts for specific tokens, and claiming all accrued fees. Ensure you have the necessary dependencies installed and replace placeholder values with your actual project and account details.

```javascript
import { ReferralProvider } from "@jup-ag/referral-sdk";
import { Connection, Keypair, PublicKey, sendAndConfirmTransaction, sendAndConfirmRawTransaction } from "@solana/web3.js";
import fs from 'fs';

const connection = new Connection("https://api.mainnet-beta.solana.com");
const privateKeyArray = JSON.parse(fs.readFileSync('/Path/to/.config/solana/id.json', 'utf8').trim());
const wallet = Keypair.fromSecretKey(new Uint8Array(privateKeyArray));

const provider = new ReferralProvider(connection);
const projectPubKey = new PublicKey('DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc');

async function initReferralAccount() {
  const transaction = await provider.initializeReferralAccountWithName({
    payerPubKey: wallet.publicKey,
    partnerPubKey: wallet.publicKey,
    projectPubKey: projectPubKey,
    name: "insert-name-here",
  });

  const referralAccount = await connection.getAccountInfo(
    transaction.referralAccountPubKey,
  );

  if (!referralAccount) {
    const signature = await sendAndConfirmTransaction(connection, transaction.tx, [wallet]);
    console.log('signature:', `https://solscan.io/tx/${signature}`);
    console.log('created referralAccountPubkey:', transaction.referralAccountPubKey.toBase58());
  } else {
    console.log(
      `referralAccount ${transaction.referralAccountPubKey.toBase58()} already exists`,
    );
  }
}

async function initReferralTokenAccount() {
  const mint = new PublicKey("So11111111111111111111111111111111111111112"); // the token mint you want to collect fees in

  const transaction = await provider.initializeReferralTokenAccountV2({
    payerPubKey: wallet.publicKey,
    referralAccountPubKey: new PublicKey("insert-referral-account-pubkey-here"), // you get this from the initReferralAccount function
    mint,
  });

    const referralTokenAccount = await connection.getAccountInfo(
      transaction.tokenAccount,
    );

    if (!referralTokenAccount) {
      const signature = await sendAndConfirmTransaction(connection, transaction.tx, [wallet]);
      console.log('signature:', `https://solscan.io/tx/${signature}`);
      console.log('created referralTokenAccountPubKey:', transaction.tokenAccount.toBase58());
      console.log('mint:', mint.toBase58());
    } else {
      console.log(
        `referralTokenAccount ${transaction.tokenAccount.toBase58()} for mint ${mint.toBase58()} already exists`,
      );
    }
}

async function claimAllTokens() {
  const transactions = await provider.claimAllV2({
    payerPubKey: wallet.publicKey,
    referralAccountPubKey: new PublicKey("insert-referral-account-pubkey-here"),
  })

  // Send each claim transaction one by one.
  for (const transaction of transactions) {
    transaction.sign([wallet]);

    const signature = await sendAndConfirmRawTransaction(connection, transaction.serialize(), [wallet]);
    console.log('signature:', `https://solscan.io/tx/${signature}`);
  }
}

// initReferralAccount(); // you should only run this once
// initReferralTokenAccount();
// claimAllTokens();
  
```

--------------------------------

### Full Code Example

Source: https://github.com/jup-ag/docs/blob/main/lend/borrow/create-position.mdx

This example demonstrates how to create a lend/borrow position by loading a keypair, getting the create-position instruction, building the transaction, and sending it.

```typescript
import {
    Connection,
    Keypair,
    Transaction,
    sendAndConfirmTransaction,
} from "@solana/web3.js";
import { getInitPositionIx } from "@jup-ag/lend/borrow";
import fs from "fs";
import path from "path";

const KEYPAIR_PATH = "/path/to/your/keypair.json"; // Path to your local keypair file (update this path)
const RPC_URL = "https://api.mainnet-beta.solana.com"; // RPC endpoint
const VAULT_ID = 1; // Target vault (market); check protocol docs for vault IDs

function loadKeypair(keypairPath: string): Keypair {
    const fullPath = path.resolve(keypairPath);
    const secret = JSON.parse(fs.readFileSync(fullPath, "utf8"));
    return Keypair.fromSecretKey(new Uint8Array(secret));
}

// 1. Load user keypair and establish connection
const userKeypair = loadKeypair(KEYPAIR_PATH);
const connection = new Connection(RPC_URL, { commitment: "confirmed" });
const signer = userKeypair.publicKey;

// 2. Get create-position instruction from SDK
const { ix, nftId } = await getInitPositionIx({
    vaultId: VAULT_ID,
    connection,
    signer,
});

// 3. Build the transaction with latest blockhash and add create-position instruction
// This prepares the transaction ready to be signed and sent (legacy transaction)
const latestBlockhash = await connection.getLatestBlockhash();
const transaction = new Transaction({
    feePayer: signer,
    ...latestBlockhash,
});
transaction.add(ix);

// 4. Sign and send the transaction
const signature = await sendAndConfirmTransaction(connection, transaction, [userKeypair]);
console.log("Create position successful! Position ID (nftId):", nftId);
console.log("Signature:", signature);
```

--------------------------------

### Create React Project

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/react-app-example.mdx

Command to create a new React project with TypeScript template and start the development server.

```bash
npx create-react-app plugin-demo --template typescript
cd plugin-demo
npm start
```

--------------------------------

### Method 2: Using @jup-ag/plugin Package

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/nextjs-app-example.mdx

This code snippet demonstrates how to initialize the Jupiter Plugin by installing and importing the @jup-ag/plugin package in a Next.js component.

```bash
npm install @jup-ag/plugin

```

```javascript
"use client";

import React, { useEffect } from "react";
import "@jup-ag/plugin/css";

export default function PluginComponent() {
  useEffect(() => {
    import("@jup-ag/plugin").then((mod) => {
      const { init } = mod;
      init({
        displayMode: "widget",
        integratedTargetId: "jupiter-plugin",
      });
    });
  }, []);

  return (
    <div>
      <h1>Jupiter Plugin Demo</h1>
      <div id="jupiter-plugin" />
    </div>
  );
}

```

--------------------------------

### Create a New Next.js Project

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/nextjs-app-example.mdx

Creates a new Next.js project with the TypeScript template and starts the development server.

```bash
npx create-next-app@latest plugin-demo --typescript
cd plugin-demo
npm run dev
```

--------------------------------

### GET /squads/v5/order Request Example

Source: https://github.com/jup-ag/docs/blob/main/swap/multisig.mdx

Example of how to call the GET /squads/v5/order endpoint to initiate a multisig swap.

```typescript
import { Jupiter } from "@jup-ag/core";

const jupiter = new Jupiter.Core({
  cluster: "mainnet-beta", // or "devnet", "testnet"
});

async function getMultisigOrder() {
  const inputMint = "So11111111111111111111111111111111111111112"; // SOL
  const outputMint = "EPjFWdd5AufqSSqeM2qN1xzyb2AR8G9AEiVvWzWjVz2"; // USDC
  const amount = "1000000"; // 1 SOL in lamports
  const taker = "YOUR_VAULT_PDA"; // Your Squads V5 vault PDA
  const settingsPda = "YOUR_SETTINGS_PDA"; // Your Squads V5 settings PDA
  const signers = "SIGNER_1_PUBKEY,SIGNER_2_PUBKEY,SIGNER_3_PUBKEY"; // Comma-separated signer public keys, first is fee payer

  try {
    const order = await jupiter.swap.getSquadsV5Order({
      inputMint,
      outputMint,
      amount,
      taker,
      settingsPda,
      signers,
    });

    console.log("Order details:", order);
    // order.transaction is the base64 encoded transaction ready to be signed
    // order.requestId is the UUID to pass to the execute endpoint
  } catch (error) {
    console.error("Error getting multisig order:", error);
  }
}

getMultisigOrder();
```

--------------------------------

### Run the Project

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/html-app-example.mdx

Command to run the project using http-server.

```bash
http-server
```

--------------------------------

### Get all verified tokens

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-information.mdx

Example of getting all verified tokens using JavaScript.

```javascript
const response = await fetch(
  'https://api.jup.ag/tokens/v2/tag?query=verified',
  {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  }
);
const verifiedTokens = await response.json();
```

--------------------------------

### Set up dependencies and wallet for signing

Source: https://github.com/jup-ag/docs/blob/main/ultra/execute-order.mdx

This snippet shows how to set up dependencies and a development wallet for signing transactions.

```bash
npm install @solana/web3.js@1
```

--------------------------------

### Get all verified tokens

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-information.mdx

Example of getting all verified tokens using curl.

```bash
curl -X GET "https://api.jup.ag/tokens/v2/tag?query=verified" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Install Dependencies

Source: https://github.com/jup-ag/docs/blob/main/ultra/add-fees-to-ultra.mdx

Install the necessary SDKs for referral functionality and Solana interactions.

```bash
npm install @jup-ag/referral-sdk
npm install @solana/web3.js@1 # Using v1 of web3.js instead of v2
```

--------------------------------

### Get price for a single token

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-price.mdx

Example of how to get the price for a single token using cURL, JavaScript, and Python.

```bash
curl -X GET "https://api.jup.ag/price/v3?ids=So11111111111111111111111111111111111111112" \
  -H "x-api-key: YOUR_API_KEY"
```

```javascript
const response = await fetch(
  'https://api.jup.ag/price/v3?ids=So11111111111111111111111111111111111111112',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const prices = await response.json();
const solPrice = prices['So11111111111111111111111111111111111111112'].usdPrice;
console.log(`SOL: $${solPrice}`);
```

```python
import requests

response = requests.get(
    'https://api.jup.ag/price/v3',
    params={'ids': 'So11111111111111111111111111111111111111112'},
    headers={'x-api-key': 'YOUR_API_KEY'}
)
response.raise_for_status()
prices = response.json()
sol_price = prices['So11111111111111111111111111111111111111112']['usdPrice']
print(f"SOL: ${sol_price}")
```

--------------------------------

### Successful example response

Source: https://github.com/jup-ag/docs/blob/main/ultra/get-balances.mdx

An example of a successful response when fetching token balances.

```json
{
  "SOL": {
    "amount": "0",
    "uiAmount": 0,
    "slot": 324307186,
    "isFrozen": false
  }
}
```

--------------------------------

### Failed example response

Source: https://github.com/jup-ag/docs/blob/main/ultra/get-holdings.mdx

An example of a failed response from the holdings endpoint, indicating an invalid address.

```json
{
  "error": "Invalid address"
}
```

--------------------------------

### Create a New HTML Project

Source: https://github.com/jup-ag/docs/blob/main/tool-kits/plugin/html-app-example.mdx

Commands to create a new project directory and touch an index.html file.

```bash
mkdir plugin-democd
plugin-demotouch
index.html
```

--------------------------------

### Development Wallet using Solana CLI keyfile

Source: https://github.com/jup-ag/docs/blob/main/get-started/environment-setup.mdx

Load a development wallet from the Solana CLI keyfile.

```javascript
import { Keypair } from '@solana/web3.js';
import fs from 'fs';

const privateKeyArray = JSON.parse(
  fs.readFileSync('/Path/to/.config/solana/id.json', 'utf8').trim()
);
const wallet = Keypair.fromSecretKey(new Uint8Array(privateKeyArray));
```

--------------------------------

### Install Referral SDK

Source: https://github.com/jup-ag/docs/blob/main/swap/order-and-execute.mdx

Install the Jupiter Referral SDK using npm. This is the first step before setting up referral accounts.

```bash
npm install @jup-ag/referral-sdk
```

--------------------------------

### Successful example response

Source: https://github.com/jup-ag/docs/blob/main/ultra/get-holdings.mdx

An example of a successful response from the holdings endpoint, showing native SOL balance and token holdings.

```json
{
    "amount": "1000000000",
    "uiAmount": 1,
    "uiAmountString": "1",
    "tokens": {
        "jupSoLaHXQiZZTSfEWMTRRgpnyFm8f6sZdosWBjx93v": [
            {
                "account": "tokenaccountaddress",
                "amount": "1000000000",
                "uiAmount": 1,
                "uiAmountString": "1",
                "isFrozen": false,
                "isAssociatedTokenAccount": true,
                "decimals": 9,
                "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
            }
        ]
    }
}
```

--------------------------------

### HTML Example

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-embed-a-swap-widget.mdx

A complete HTML file demonstrating how to initialize the Jupiter Plugin with the integrated display mode.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Jupiter Plugin Demo</title>
    <script src="https://plugin.jup.ag/plugin-v1.js" data-preload defer></script>
</head>
<body>
    <h1>Jupiter Plugin Demo</h1>
    <div id="jupiter-plugin"></div>

    <script>
        window.onload = function() {
            window.Jupiter.init({
                displayMode: "integrated",
                integratedTargetId: "jupiter-plugin",
            });
        };
    </script>
</body>
</html>
```

--------------------------------

### Example API Response for Prices

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-price.mdx

An example of the JSON response structure returned by the Jupiter API for token prices.

```json
{
  "So11111111111111111111111111111111111111112": {
    "createdAt": "2024-06-05T08:55:25.527Z",
    "liquidity": 621679197.67,
    "usdPrice": 147.48,
    "blockId": 348004023,
    "decimals": 9,
    "priceChange24h": 1.29
  },
  "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN": {
    "createdAt": "2024-06-07T10:56:42.584Z",
    "liquidity": 3036749.38,
    "usdPrice": 0.85,
    "blockId": 348004026,
    "decimals": 6,
    "priceChange24h": 2.15
  }
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/jup-ag/docs/blob/main/lend/advanced/multiply.mdx

Install necessary Solana web3, Jupiter Lend SDKs, and BN for amounts.

```bash
npm install @solana/web3.js bn.js @jup-ag/lend @jup-ag/lend-read
```

--------------------------------

### Next.js Example

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-embed-a-swap-widget.mdx

A Next.js page demonstrating how to initialize the Jupiter Plugin using the Script component and onReady.

```tsx
"use client";
import { useEffect } from "react";
import Script from "next/script";

export default function SwapPage() {
  return (
    <>
      <Script
        src="https://plugin.jup.ag/plugin-v1.js"
        data-preload
        strategy="afterInteractive"
        onReady={() => {
          window.Jupiter.init({
            displayMode: "integrated",
            integratedTargetId: "jupiter-plugin",
          });
        }}
      />
      <h1>Jupiter Plugin Demo</h1>
      <div id="jupiter-plugin" />
    </>
  );
}
```

--------------------------------

### Set up Development Wallet via .env file

Source: https://github.com/jup-ag/docs/blob/main/studio/create-token.mdx

Configure a development wallet using a .env file to store your private key.

```javascript
// index.js
import { Keypair } from '@solana/web3.js';
import dotenv from 'dotenv';
require('dotenv').config();

const wallet = Keypair.fromSecretKey(bs58.decode(process.env.PRIVATE_KEY || ''));
```

```dotenv
# .env
PRIVATE_KEY=''
```

--------------------------------

### Full Withdraw Example

Source: https://github.com/jup-ag/docs/blob/main/lend/earn/withdraw.mdx

This example demonstrates how to withdraw assets from Jupiter Lend using the SDK. It covers loading the keypair, getting withdraw instructions, building and signing the transaction, and sending it.

```typescript
import {
    Connection,
    Keypair,
    PublicKey,
    Transaction,
    sendAndConfirmTransaction,
} from "@solana/web3.js";
import BN from "bn.js";
import { getWithdrawIxs } from "@jup-ag/lend/earn";
import fs from "fs";
import path from "path";

const KEYPAIR_PATH = "/path/to/your/keypair.json"; // Path to your local keypair file (update this path)
const ASSET_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"); // Asset mint to withdraw (USDC for example)
const WITHDRAW_AMOUNT = new BN(10_000_000); // Amount to withdraw, in smallest units (e.g., 1 USDC = 1_000_000)
const RPC_URL = "https://api.mainnet-beta.solana.com"; // RPC endpoint

function loadKeypair(keypairPath: string): Keypair {
    const fullPath = path.resolve(keypairPath);
    const secret = JSON.parse(fs.readFileSync(fullPath, "utf8"));
    return Keypair.fromSecretKey(new Uint8Array(secret));
}

// 1. Load user keypair and establish connection
const userKeypair = loadKeypair(KEYPAIR_PATH);
const connection = new Connection(RPC_URL, { commitment: "confirmed" });
const signer = userKeypair.publicKey;

// 2. Get withdraw instructions from SDK
const { ixs: withdrawIxs } = await getWithdrawIxs({
    connection,
    signer,
    asset: ASSET_MINT,
    amount: WITHDRAW_AMOUNT,
});

if (!withdrawIxs?.length) {
    throw new Error("No withdraw instructions returned by Jupiter Lend SDK.");
}

// 3. Build the transaction with latest blockhash and add withdraw instructions
const latestBlockhash = await connection.getLatestBlockhash();
const transaction = new Transaction({
    feePayer: signer,
    ...latestBlockhash,
});
transaction.add(...withdrawIxs);
transaction.sign(userKeypair);


// 4. Sign and send the transaction
const signature = await sendAndConfirmTransaction(connection, transaction, [userKeypair]);
console.log("Withdraw successful! Signature:", signature);

```

--------------------------------

### Get Operate Instructions

Source: https://github.com/jup-ag/docs/blob/main/lend/borrow/cpi.mdx

Example of using `getOperateIx` to resolve CPI accounts for frontend/client code.

```typescript
import { getOperateIx } from "@jup-ag/lend/borrow";
import { BN } from "bn.js";

const { 
  ixs,
  addressLookupTableAccounts,
  nftId,
  accounts,
  remainingAccounts,
  remainingAccountsIndices,
} = await getOperateIx({
  colAmount: new BN(1000000000),
  debtAmount: new BN(500000000),
  connection,
  positionId: nftId,
  signer: userPublicKey,
  vaultId: vaultId,
  cluster: "mainnet",
});

// Setup instructions = all except the last (environment preparation)
// The last instruction is the direct operate call — not needed for CPI
const setupInstructions = ixs.slice(0, -1);

// Build a v0 transaction with setup instructions + your CPI instruction
const messageV0 = new TransactionMessage({
  payerKey: userPublicKey,
  recentBlockhash: (await connection.getLatestBlockhash()).blockhash,
  instructions: [
    ...setupInstructions,
    // your program instruction that makes the CPI call
  ],
}).compileToV0Message(addressLookupTableAccounts);

const versionedTx = new VersionedTransaction(messageV0);
```

--------------------------------

### Handle Missing Prices

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-price.mdx

Example of how to check for and handle missing token prices in your application.

```javascript
const price = prices[mint]?.usdPrice;
if (price === undefined) {
  // Token has no reliable price
  // Show "Price unavailable" or fallback
}
```

--------------------------------

### Full code example

Source: https://github.com/jup-ag/docs/blob/main/lend/borrow/borrow.mdx

This example demonstrates how to borrow assets using the Jupiter Lend SDK. It covers loading the keypair, establishing a connection, getting borrow instructions, building and signing a versioned transaction, and sending it to the network.

```typescript
import {
    Connection,
    Keypair,
    TransactionMessage,
    VersionedTransaction,
} from "@solana/web3.js";
import BN from "bn.js";
import { getOperateIx } from "@jup-ag/lend/borrow";
import fs from "fs";
import path from "path";

const KEYPAIR_PATH = "/path/to/your/keypair.json"; // Path to your local keypair file (update this path)
const RPC_URL = "https://api.mainnet-beta.solana.com"; // RPC endpoint
const VAULT_ID = 1; // Target vault (market)
const POSITION_ID = 0; // nftId from Create Position script
const BORROW_AMOUNT = new BN(100_000); // Amount to borrow, in smallest units (borrow token base units)

function loadKeypair(keypairPath: string): Keypair {
    const fullPath = path.resolve(keypairPath);
    const secret = JSON.parse(fs.readFileSync(fullPath, "utf8"));
    return Keypair.fromSecretKey(new Uint8Array(secret));
}

// 1. Load user keypair and establish connection
const userKeypair = loadKeypair(KEYPAIR_PATH);
const connection = new Connection(RPC_URL, { commitment: "confirmed" });
const signer = userKeypair.publicKey;

// 2. Get borrow instructions from SDK (operate with zero colAmount, positive debtAmount)
const { ixs, addressLookupTableAccounts } = await getOperateIx({
    vaultId: VAULT_ID,
    positionId: POSITION_ID,
    colAmount: new BN(0),
    debtAmount: BORROW_AMOUNT,
    connection,
    signer,
});

if (!ixs?.length) {
    throw new Error("No borrow instructions returned by Jupiter Lend SDK.");
}

// 3. Build the transaction with latest blockhash and add borrow instructions
// Versioned (v0) transaction with address lookup tables; ready to be signed and sent
const latestBlockhash = await connection.getLatestBlockhash();
const message = new TransactionMessage({
    payerKey: signer,
    recentBlockhash: latestBlockhash.blockhash,
    instructions: ixs,
}).compileToV0Message(addressLookupTableAccounts ?? []);

const transaction = new VersionedTransaction(message);
transaction.sign([userKeypair]);

// 4. Send and confirm the transaction
const signature = await connection.sendTransaction(transaction, {
    skipPreflight: false,
    maxRetries: 3,
    preflightCommitment: "confirmed",
});
await connection.confirmTransaction(
    { signature, ...latestBlockhash },
    "confirmed"
);

console.log("Borrow successful! Signature:", signature);

```

--------------------------------

### Start local development server

Source: https://github.com/jup-ag/docs/blob/main/README.md

Run this command at the root of your documentation where docs.json is located to start the local preview server.

```bash
mint dev
```

--------------------------------

### Full Flash Loan Execution Example

Source: https://github.com/jup-ag/docs/blob/main/lend/flashloan/execute.mdx

This TypeScript example shows the complete process of executing a flash loan, including loading a keypair, getting borrow and payback instructions, defining custom logic, assembling the transaction, and sending it.

```typescript
import {
  Connection,
  Keypair,
  PublicKey,
  TransactionMessage,
  VersionedTransaction,
} from "@solana/web3.js";
import BN from "bn.js";
import { getFlashloanIx } from "@jup-ag/lend/flashloan";
import fs from "fs";
import path from "path";

const KEYPAIR_PATH = "/path/to/your/keypair.json";
const RPC_URL = "https://api.mainnet-beta.solana.com";
const ASSET = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"); // USDC
const BORROW_AMOUNT = new BN(100_000_000); // 100 USDC

function loadKeypair(keypairPath: string): Keypair {
  const fullPath = path.resolve(keypairPath);
  const secret = JSON.parse(fs.readFileSync(fullPath, "utf8"));
  return Keypair.fromSecretKey(new Uint8Array(secret));
}

async function main() {
  // 1. Load user keypair and establish connection
  const userKeypair = loadKeypair(KEYPAIR_PATH);
  const connection = new Connection(RPC_URL, { commitment: "confirmed" });
  const signer = userKeypair.publicKey;

  // 2. Get the borrow and payback instructions
  const { borrowIx, paybackIx } = await getFlashloanIx({
    connection,
    signer,
    asset: ASSET,
    amount: BORROW_AMOUNT,
  });

  // 3. Define custom instructions that utilise the borrowed funds
  const customIxs = [
    // ... insert your custom logic here
  ];

  // 4. Assemble the transaction: Borrow -> Custom Logic -> Payback
  const instructions = [
    borrowIx,
    ...customIxs,
    paybackIx
  ];

  // 5. Build and sign transaction
  const latestBlockhash = await connection.getLatestBlockhash();
  const message = new TransactionMessage({
    payerKey: signer,
    recentBlockhash: latestBlockhash.blockhash,
    instructions,
  }).compileToV0Message(); // If your custom logic uses ALTs, pass them here

  const transaction = new VersionedTransaction(message);
  transaction.sign([userKeypair]);

  // 6. Send and confirm the transaction
  const signature = await connection.sendTransaction(transaction, {
    skipPreflight: false,
    maxRetries: 3,
    preflightCommitment: "confirmed",
  });

  await connection.confirmTransaction(
    { signature, ...latestBlockhash },
    "confirmed"
  );

  console.log("Flashloan successful! Signature:", signature);
}

main().catch(console.error);

```

--------------------------------

### Development Wallet Setup (.env)

Source: https://github.com/jup-ag/docs/blob/main/studio/claim-fee.mdx

Set up a development wallet using a private key stored in a .env file. This method is not recommended for production.

```javascript
// index.js
import { Keypair } from '@solana/web3.js';
import dotenv from 'dotenv';
require('dotenv').config();
const wallet = Keypair.fromSecretKey(bs58.decode(process.env.PRIVATE_KEY || ''));
```

```bash
# .env
PRIVATE_KEY=''
```

--------------------------------

### Full Code Example for Depositing Assets

Source: https://github.com/jup-ag/docs/blob/main/lend/earn/deposit.mdx

This TypeScript example demonstrates how to deposit assets into Jupiter Lend to earn yield. It covers loading the keypair, establishing a connection, getting deposit instructions from the SDK, building the transaction, and sending it.

```typescript
import {
    Connection,
    Keypair,
    PublicKey,
    Transaction,
    sendAndConfirmTransaction,
} from "@solana/web3.js";
import BN from "bn.js";
import { getDepositIxs } from "@jup-ag/lend/earn";
import fs from "fs";
import path from "path";


const KEYPAIR_PATH = "/path/to/your/keypair.json"; // Path to your local keypair file (update this path)
const ASSET_MINT = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"); // Asset mint to deposit (USDC for example)
const DEPOSIT_AMOUNT = new BN(10_000_000); // Amount to deposit, in smallest units (e.g., 1 USDC = 1_000_000)
const RPC_URL = "https://api.mainnet-beta.solana.com"; // RPC endpoint

function loadKeypair(keypairPath: string): Keypair {
    const fullPath = path.resolve(keypairPath);
    const secret = JSON.parse(fs.readFileSync(fullPath, "utf8"));
    return Keypair.fromSecretKey(new Uint8Array(secret));
}

// 1. Load user keypair and establish connection
const userKeypair = loadKeypair(KEYPAIR_PATH);
const connection = new Connection(RPC_URL, { commitment: "confirmed" });
const signer = userKeypair.publicKey;

// 2. Get deposit instructions from SDK
const { ixs: depositIxs } = await getDepositIxs({
    connection,
    signer,
    asset: ASSET_MINT,
    amount: DEPOSIT_AMOUNT,
});

if (!depositIxs?.length) {
    throw new Error("No deposit instructions returned by Jupiter Lend SDK.");
}

// 3. Build the transaction with latest blockhash and add deposit instructions
// This prepares the transaction ready to be signed and sent
const latestBlockhash = await connection.getLatestBlockhash();
const transaction = new Transaction({
    feePayer: signer,
    ...latestBlockhash,
});
transaction.add(...depositIxs);
transaction.sign(userKeypair);

// 4. Sign and send the transaction
const signature = await sendAndConfirmTransaction(connection, transaction, [userKeypair]);
console.log("Deposit successful! Signature:", signature);

```

--------------------------------

### Get Fees Endpoint

Source: https://github.com/jup-ag/docs/blob/main/ultra/fees.mdx

This example shows how to use the /fees endpoint to check fees and category given the input and output mint.

```bash
curl -X GET 'https://api.jup.ag/ultra/v1/fees?inputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&outputMint=So11111111111111111111111111111111111111112' \
  -H 'x-api-key: your-api-key'
```

--------------------------------

### Setup

Source: https://github.com/jup-ag/docs/blob/main/lend/wallets/privy-earn.mdx

Initialize PrivyClient, Connection, and retrieve wallet information for transaction signing.

```typescript
import { PrivyClient} from "@privy-io/node";
import {
  Connection,
  PublicKey,
  TransactionMessage,
  VersionedTransaction,
} from "@solana/web3.js";
import BN from "bn.js";
import { getDepositIxs, getWithdrawIxs } from "@jup-ag/lend/earn";

const PRIVY_APP_ID = "put-your-privy-app-id-here";
const PRIVY_APP_SECRET = "put-your-privy-app-secret-here";
const RPC_ENDPOINT = "https://api.mainnet-beta.solana.com";
const ASSET_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"; // USDC
const AUTH_KEY_ID = "put-your-auth-key-id-here"; // from Privy dashboard or REST API
const AUTH_KEY_PRIVATE = "put-your-auth-key-private-here"; // P-256 private key
const WALLET_ID = "put-your-wallet-id-here";

const privy = new PrivyClient({
  appId: PRIVY_APP_ID,
  appSecret: PRIVY_APP_SECRET,
});

const connection = new Connection(RPC_ENDPOINT);

const wallet = await privy.wallets().get(WALLET_ID);
if (!wallet) {
  throw new Error(`Wallet ${WALLET_ID} not found`);
}
const signer = new PublicKey(wallet.address);
```

--------------------------------

### Build, Simulate, and Submit Swap Transaction

Source: https://github.com/jup-ag/docs/blob/main/swap/build/index.mdx

This example demonstrates the full process of using the Jupiter Swap API. It includes fetching swap instructions, adding custom instructions, simulating the transaction to determine compute unit limits, and submitting the signed transaction for execution. Ensure you have your API key and RPC URL configured in your environment variables.

```typescript
const API_KEY = process.env.JUPITER_API_KEY;
const RPC_URL = process.env.RPC_URL;
if (!API_KEY) throw new Error("Missing JUPITER_API_KEY");
if (!RPC_URL) throw new Error("Missing RPC_URL");

const signer = await createKeyPairSignerFromBytes(
  getBase58Encoder().encode(process.env.BS58_PRIVATE_KEY!),
);
const rpc = createSolanaRpc(RPC_URL);

// Step 1: Get swap instructions from /build
const buildRes = await fetch(
  "https://api.jup.ag/swap/v2/build?" +
    new URLSearchParams({
      inputMint: "So11111111111111111111111111111111111111112",
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: "100000000",
      taker: signer.address,
      slippageBps: "100",
      tipAmount: "1000000", // 0.001 SOL tip for /submit (omit if using your own RPC)
    }),
  { headers: { "x-api-key": API_KEY } },
);
if (!buildRes.ok) {
  console.error(`/build failed: ${buildRes.status}`, await buildRes.text());
  process.exit(1);
}
const build: BuildResponse = await buildRes.json();

// Step 2: Collect instructions (no compute unit limit yet, we simulate first)
// Example: add a SOL transfer after the swap
const RECIPIENT = address("YOUR_RECIPIENT_ADDRESS");
const transferIx = getTransferSolInstruction({
  source: signer,
  destination: RECIPIENT,
  amount: 1_000_000n, // 0.001 SOL
});

const instructions = [
  ...build.setupInstructions.map(createInstruction),
  createInstruction(build.swapInstruction),
  transferIx, // Your custom instruction, added after the swap
  ...(build.cleanupInstruction
    ? [createInstruction(build.cleanupInstruction)]
    : []),
  ...build.otherInstructions.map(createInstruction),
  ...(build.tipInstruction
    ? [createInstruction(build.tipInstruction)]
    : []),
];

// Step 3: Prepare blockhash and address lookup tables
const blockhash = transformBlockhash(build.blockhashWithMetadata);
const alts = transformALTs(build.addressesByLookupTableAddress);

// Step 4: Simulate with max CU limit to estimate actual usage
const simulationTx = buildTransaction(
  [
    createInstruction(makeSetComputeUnitLimitIx(COMPUTE_UNIT_LIMIT_MAX)),
    ...instructions,
  ],
  blockhash,
  alts,
  signer.address,
);

const simulationResult = await rpc
  .simulateTransaction(getBase64EncodedWireTransaction(simulationTx), {
    encoding: "base64",
    commitment: "confirmed",
    replaceRecentBlockhash: true,
  })
  .send();

if (simulationResult.value.err) {
  console.error("Simulation failed:", simulationResult.value.err);
}

// Set 1.2x buffer on simulated CU, capped at max
const estimatedCUL = simulationResult.value.unitsConsumed
  ? Math.min(
      Math.ceil(Number(simulationResult.value.unitsConsumed) * 1.2),
      COMPUTE_UNIT_LIMIT_MAX,
    )
  : COMPUTE_UNIT_LIMIT_MAX;

// Step 5: Build final transaction with estimated CU limit + CU price from response
const compiledTx = buildTransaction(
  [
    createInstruction(makeSetComputeUnitLimitIx(estimatedCUL)),
    ...build.computeBudgetInstructions.map(createInstruction),
    ...instructions,
  ],
  blockhash,
  alts,
  signer.address,
);

// Step 6: Sign and submit via /submit (or use your own RPC / transaction pipeline)
const signedTransaction = await signTransaction([signer.keyPair], compiledTx);

const submitRes = await fetch("https://api.jup.ag/tx/v1/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    signedTransaction: getBase64EncodedWireTransaction(signedTransaction),
  }),
});

const { signature } = await submitRes.json();
console.log("Submitted:", `https://solscan.io/tx/${signature}`);

// Step 7: Confirm the transaction landed
const confirmation = await rpc
  .confirmTransaction(signature, {
    strategy: { type: "blockhash", ...blockhash },
    commitment: "confirmed",
  })
  .send();

if (confirmation.value.err) {
  console.error("Transaction failed:", confirmation.value.err);
  process.exit(1);
}

console.log("Confirmed:", signature);

```

--------------------------------

### Error Response: Rate limited (429)

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-price.mdx

Example JSON response when the API rate limit has been exceeded.

```json
{
  "message": "Rate limit exceeded"
}
```

--------------------------------

### Build and Execute a Jupiter Swap

Source: https://github.com/jup-ag/docs/blob/main/swap/build/index.mdx

This example demonstrates the full process of building a swap transaction using the Jupiter API. It includes fetching swap instructions, adding custom instructions, resolving address lookup tables, simulating the transaction to determine compute unit limits, signing, and submitting the transaction for confirmation.

```typescript
const API_KEY = process.env.JUPITER_API_KEY;
const RPC_URL = process.env.RPC_URL;
if (!API_KEY) throw new Error("Missing JUPITER_API_KEY");
if (!RPC_URL) throw new Error("Missing RPC_URL");

const connection = new Connection(RPC_URL);
const signer = Keypair.fromSecretKey(
  bs58.decode(process.env.BS58_PRIVATE_KEY!),
);

// Step 1: Get swap instructions from /build
const buildRes = await fetch(
  "https://api.jup.ag/swap/v2/build?" +
    new URLSearchParams({
      inputMint: "So11111111111111111111111111111111111111112",
      outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      amount: "100000000",
      taker: signer.publicKey.toString(),
      slippageBps: "100",
      tipAmount: "1000000", // 0.001 SOL tip for /submit (omit if using your own RPC)
    }),
  { headers: { "x-api-key": API_KEY } },
);
if (!buildRes.ok) {
  console.error(`/build failed: ${buildRes.status}`, await buildRes.text());
  process.exit(1);
}
const build: BuildResponse = await buildRes.json();

// Step 2: Collect instructions (no compute unit limit yet, we simulate first)
// Example: add a SOL transfer after the swap
const RECIPIENT = new PublicKey("YOUR_RECIPIENT_ADDRESS");
const transferIx = SystemProgram.transfer({
  fromPubkey: signer.publicKey,
  toPubkey: RECIPIENT,
  lamports: 1_000_000, // 0.001 SOL
});

const instructions = [
  ...build.setupInstructions.map(toInstruction),
  toInstruction(build.swapInstruction),
  transferIx, // Your custom instruction, added after the swap
  ...(build.cleanupInstruction
    ? [toInstruction(build.cleanupInstruction)]
    : []),
  ...build.otherInstructions.map(toInstruction),
  ...(build.tipInstruction
    ? [toInstruction(build.tipInstruction)]
    : []),
];

// Step 3: Resolve address lookup tables (from /build response, no RPC needed)
const addressLookupTableAccounts = transformALTs(
  build.addressesByLookupTableAddress,
);

const { blockhash, lastValidBlockHeight } = build.blockhashWithMetadata;
const recentBlockhash = bs58.encode(Buffer.from(blockhash));

// Step 4: Simulate with max CU limit to estimate actual usage
const simulationMessage = new TransactionMessage({
  payerKey: signer.publicKey,
  recentBlockhash,
  instructions: [
    ComputeBudgetProgram.setComputeUnitLimit({ units: COMPUTE_UNIT_LIMIT_MAX }),
    ...instructions,
  ],
}).compileToV0Message(addressLookupTableAccounts);

const simulationTx = new VersionedTransaction(simulationMessage);
const simulationResult = await connection.simulateTransaction(simulationTx, {
  replaceRecentBlockhash: true,
});

if (simulationResult.value.err) {
  console.error("Simulation failed:", simulationResult.value.err);
}

// Set 1.2x buffer on simulated CU, capped at max
const estimatedCUL = simulationResult.value.unitsConsumed
  ? Math.min(
      Math.ceil(simulationResult.value.unitsConsumed * 1.2),
      COMPUTE_UNIT_LIMIT_MAX,
    )
  : COMPUTE_UNIT_LIMIT_MAX;

// Step 5: Build final transaction with estimated CU limit + CU price from response
const finalMessage = new TransactionMessage({
  payerKey: signer.publicKey,
  recentBlockhash,
  instructions: [
    ComputeBudgetProgram.setComputeUnitLimit({ units: estimatedCUL }),
    ...build.computeBudgetInstructions.map(toInstruction), // CU price from response
    ...instructions,
  ],
}).compileToV0Message(addressLookupTableAccounts);

// Step 6: Sign and submit via /submit (or use your own RPC / transaction pipeline)
const transaction = new VersionedTransaction(finalMessage);
transaction.sign([signer]);

const submitRes = await fetch("https://api.jup.ag/tx/v1/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
  },
  body: JSON.stringify({
    signedTransaction: Buffer.from(transaction.serialize()).toString("base64"),
  }),
});

const { signature } = await submitRes.json();
console.log("Submitted:", `https://solscan.io/tx/${signature}`);

// Step 7: Confirm the transaction landed
const confirmation = await connection.confirmTransaction(
  { signature, blockhash: recentBlockhash, lastValidBlockHeight },
  "confirmed",
);

if (confirmation.value.err) {
  console.error("Transaction failed:", confirmation.value.err);
  process.exit(1);
}

console.log("Confirmed:", signature);

```

--------------------------------

### Search by mint, symbol, or name

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-information.mdx

Example of searching for tokens by mint, symbol, or name using Python.

```python
import requests

response = requests.get(
    'https://api.jup.ag/tokens/v2/search',
    params={'query': 'JUP'},
    headers={'x-api-key': 'YOUR_API_KEY'}
)
response.raise_for_status()
tokens = response.json()
```

--------------------------------

### Search by mint, symbol, or name

Source: https://github.com/jup-ag/docs/blob/main/guides/how-to-get-token-information.mdx

Example of searching for tokens by mint, symbol, or name using JavaScript.

```javascript
const response = await fetch(
  'https://api.jup.ag/tokens/v2/search?query=JUP',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const tokens = await response.json();
```

--------------------------------

### Fee Settlement via /build

Source: https://github.com/jup-ag/docs/blob/main/swap/fee-settlement.mdx

This example shows how to use the `/build` endpoint with the `integratorFeeBps` parameter to generate raw swap instructions. This method requires the user to assemble, sign, and submit the transaction independently.

```APIDOC
## GET /swap/v2/build

### Description
Generates raw swap instructions, including a specified integrator fee, for manual transaction assembly.

### Method
GET

### Endpoint
/swap/v2/build

### Parameters
#### Query Parameters
- **inputMint** (string) - Required - The mint address of the input token.
- **outputMint** (string) - Required - The mint address of the output token.
- **amount** (integer) - Required - The amount of input tokens to swap.
- **taker** (string) - Required - The wallet address of the taker.
- **integratorFeeBps** (integer) - Required - The fee percentage for the integrator in basis points (e.g., 50 for 0.5%).

### Request Example
```http
GET https://api.jup.ag/swap/v2/build?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000000&taker=YOUR_WALLET&integratorFeeBps=50
```

### Response
#### Success Response (200)
Returns raw swap instructions. The user is responsible for assembling, signing, and submitting the transaction.
```