Metis

https://metis.builders/docs
Admin
Metis is a self-hosted API binary for Solana that provides quoting and swap transaction building...
Tokens:19,649
Snippets:132
Trust Score:5.6
Update:8 months ago
Show doc for...
Tokens:
Raw
### Start Metis Self-hosted API Binary with Binary Key (Bash)

Source: https://metis.builders/docs/binary-key

This command demonstrates how to launch the Metis Self-hosted API Binary using a Binary Key. It requires setting the `BINARY_KEY` environment variable and other necessary parameters like RPC URL and gRPC endpoints. This example specifically uses Yellowstone gRPC streaming.

```bash
RUST_LOG=info ./metis-binary \
  --binary-key YOUR_BINARY_KEY_HERE \
  --rpc-url YOUR_RPC_URL \
  --yellowstone-grpc-endpoint YOUR_GRPC_ENDPOINT \
  --yellowstone-grpc-x-token YOUR_X_TOKEN
```

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

### Install Solana Development Libraries

Source: https://metis.builders/docs/add-fees-to-swap

Installs essential libraries for Solana blockchain development, including web3.js for core blockchain interactions, spl-token for SPL token management, bs58 for base58 encoding/decoding, and dotenv for environment variable management.

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

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

### Install Solana Web3.js and Dependencies

Source: https://metis.builders/docs/send-swap-transaction

Installs the necessary libraries for interacting with the Solana blockchain, including web3.js for core operations, bs58 for base58 encoding/decoding, and dotenv for environment variable management.

```bash
npm install @solana/web3.js bs58 dotenv
```

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

### Fetch Quote with Instruction Version (JavaScript)

Source: https://metis.builders/docs/add-fees-to-swap

This JavaScript code demonstrates fetching a quote from the Metis Builders API, specifying the `instructionVersion` as `V2`. This version is necessary for collecting fees in Token2022 tokens. The example includes parameters for input and output mints, amount, slippage, and platform fee.

```javascript
const quoteResponse = await (
    await fetch(
        'https://0.0.0.0:8080/quote' + 
        '?inputMint=So11111111111111111111111111111111111111112' + 
        '&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' + 
        '&amount=100000000' + 
        '&slippageBps=100' + 
        '&platformFeeBps=20' + 
        '&instructionVersion=V2'
    )
  ).json();
```

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

### Integrate Jupiter Swap via CPI with Rust Crate

Source: https://metis.builders/docs/build-swap-transaction

This snippet demonstrates how to integrate the Jupiter Swap functionality into your Solana program using the `jupiter-cpi` Rust crate. It shows how to add the dependency to `cargo.toml` and provides an example of constructing the necessary accounts and calling the `shared_accounts_route` function for performing a swap via CPI. This method is recommended for its optimizations, though it has limitations with ALTs.

```toml
theme={null}
[dependencies]
jupiter-cpi = { git = "https://github.com/jup-ag/jupiter-cpi", rev = "5eb8977" }
```

```rust
theme={null}
    use jupiter_cpi;
  ...

  let signer_seeds: &[&[&[u8]]] = &[...];

  // Pass accounts to context one-by-one and construct accounts here
  // Or in practise, it may be easier to use remaining_accounts
  // https://book.anchor-lang.com/anchor_in_depth/the_program_module.html

  let accounts = jupiter_cpi::cpi::accounts::SharedAccountsRoute {
      token_program: ,
      program_authority: ,
      user_transfer_authority: ,
      source_token_account: ,
      program_source_token_account: ,
      program_destination_token_account: ,
      destination_token_account: ,
      source_mint: ,
      destination_mint: ,
      platform_fee_account: ,
      token_2022_program: ,
  };
  let cpi_ctx = CpiContext::new_with_signer(
      ctx.accounts.jup.to_account_info(),
      accounts,
      signer_seeds,
  );

  jupiter_cpi::cpi::shared_accounts_route(
      cpi_ctx,
      id,
      route_plan,
      in_amount,
      quoted_out_amount,
      slippage_bps,
      platform_fee_bps,
  );

  ...

```

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

### Start Metis API Server (Poll Mode)

Source: https://metis.builders/docs/self-host

Starts the Metis API server in poll mode, which periodically polls the Solana RPC node for accounts. This mode is heavier on nodes and not recommended. Requires a binary key and RPC URL.

```bash
RUST_LOG=info ./metis-binary \
  --binary-key YOUR_BINARY_KEY_HERE \
  --rpc-url YOUR_RPC_URL
```

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

### GET /quote

Source: https://metis.builders/docs/requote-with-lower-max-accounts

This endpoint allows you to fetch a quote for a transaction. You can specify the `maxAccounts` parameter to control the maximum number of accounts used in the swap, which can help in reducing the overall transaction size and allowing for custom instructions.

```APIDOC
## GET /quote

### Description
Fetches a quote for a transaction, with an option to limit the maximum number of accounts used.

### Method
GET

### Endpoint
/quote

### Parameters
#### Query Parameters
- **maxAccounts** (integer) - Optional - The maximum number of accounts to be used in the swap. Reducing this value can help manage transaction size limits and allow for the addition of custom instructions.

### Request Example
```
GET /quote?maxAccounts=10
```

### Response
#### Success Response (200)
- **quoteDetails** (object) - Details of the transaction quote.
  - **estimatedGas** (string) - Estimated gas fees.
  - **swapRate** (string) - The exchange rate for the swap.
  - **maxAccountsUsed** (integer) - The actual maximum number of accounts used in the quote.

#### Response Example
```json
{
  "quoteDetails": {
    "estimatedGas": "0.1 ETH",
    "swapRate": "1 ETH = 3000 USDC",
    "maxAccountsUsed": 10
  }
}
```
```

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

### Get Quote from Metis API (JavaScript)

Source: https://metis.builders/docs/get-quote

Demonstrates how to fetch a token swap quote from the Metis API using a JavaScript fetch request. It requires input and output mint addresses, the amount of input tokens, and slippage settings. The response includes detailed swap information.

```javascript
const quoteResponse = await (
    await fetch(
        'https://0.0.0.0:8080/quote' + 
        '?inputMint=So11111111111111111111111111111111111111112' + 
        '&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' + 
        '&amount=100000000' + 
        '&slippageBps=100' + 
    )
  ).json();
```

```json
{
  "inputMint": "So11111111111111111111111111111111111111112",
  "inAmount": "100000000",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "outAmount": "16198753",
  "otherAmountThreshold": "16117760",
  "swapMode": "ExactIn",
  "slippageBps": 100,
  "platformFee": null,
  "priceImpactPct": "0",
  "routePlan": [
    {
      "swapInfo": {
        "ammKey": "5BKxfWMbmYBAEWvyPZS9esPducUba9GqyMjtLCfbaqyF",
        "label": "Meteora DLMM",
        "inputMint": "So11111111111111111111111111111111111111112",
        "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "inAmount": "100000000",
        "outAmount": "16198753",
        "feeAmount": "24825",
        "feeMint": "So11111111111111111111111111111111111111112"
      },
      "percent": 100
    }
  ],
  "contextSlot": 299283763,
  "timeTaken": 0.015257836
}
```

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

### GET /quote

Source: https://metis.builders/docs/get-quote

Fetches a quote for a specific token pair from the Metis Routing Engine, accessing liquidity within Solana's DEX ecosystem.

```APIDOC
## GET /quote

### Description
Fetches a quote for a specific token pair from the Metis Routing Engine, accessing liquidity within Solana's DEX ecosystem.

### Method
GET

### Endpoint
/quote

### Parameters
#### Query Parameters
- **inputMint** (string) - Required - The public key or token mint address of the input token.
- **outputMint** (string) - Required - The public key or token mint address of the output token.
- **amount** (string) - Required - The raw amount of input tokens (e.g., lamports for SOL, atomic units for others).
- **slippageBps** (number) - Optional - The slippage in basis points (100 bps = 1%).
- **platformFeeBps** (number) - Optional - The platform fee in basis points to be added to the quote.
- **feeAccount** (string) - Optional - A valid token account address to receive the platform fee.
- **onlyDirectRoutes** (boolean) - Optional - If true, restricts routing to only direct (single market) trades.

### Request Example
```
GET https://0.0.0.0:8080/quote?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=100000000&slippageBps=100
```

### Response
#### Success Response (200)
- **inputMint** (string) - The mint address of the input token.
- **inAmount** (string) - The amount of input tokens after decimal application.
- **outputMint** (string) - The mint address of the output token.
- **outAmount** (string) - The calculated amount of output tokens.
- **otherAmountThreshold** (string) - A threshold for the output amount.
- **swapMode** (string) - The mode of the swap (e.g., "ExactIn").
- **slippageBps** (number) - The slippage in basis points.
- **platformFee** (any) - Information about the platform fee, if applied.
- **priceImpactPct** (string) - The percentage of price impact.
- **routePlan** (array) - An array detailing the routing plan for the swap.
  - **ammKey** (string) - The address of the Automated Market Maker (AMM).
  - **label** (string) - The label of the AMM.
  - **inputMint** (string) - The input mint for this leg of the route.
  - **outputMint** (string) - The output mint for this leg of the route.
  - **inAmount** (string) - The input amount for this leg.
  - **outAmount** (string) - The output amount for this leg.
  - **feeAmount** (string) - The fee amount for this leg.
  - **feeMint** (string) - The mint address of the fee.
- **percent** (number) - The percentage of the route this leg represents.
- **contextSlot** (number) - The context slot of the transaction.
- **timeTaken** (number) - The time taken to generate the quote in seconds.

#### Response Example
```json
{
  "inputMint": "So11111111111111111111111111111111111111112",
  "inAmount": "100000000",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "outAmount": "16198753",
  "otherAmountThreshold": "16117760",
  "swapMode": "ExactIn",
  "slippageBps": 100,
  "platformFee": null,
  "priceImpactPct": "0",
  "routePlan": [
    {
      "ammKey": "5BKxfWMbmYBAEWvyPZS9esPducUba9GqyMjtLCfbaqyF",
      "label": "Meteora DLMM",
      "inputMint": "So11111111111111111111111111111111111111112",
      "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "inAmount": "100000000",
      "outAmount": "16198753",
      "feeAmount": "24825",
      "feeMint": "So11111111111111111111111111111111111111112"
    }
  ],
  "percent": 100,
  "contextSlot": 299283763,
  "timeTaken": 0.015257836
}
```
```

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

### JavaScript: Build and Send Solana Swap Transaction

Source: https://metis.builders/docs/requote-with-lower-max-accounts

This JavaScript code snippet demonstrates how to build and send a swap transaction on the Solana network. It includes fetching quotes, obtaining swap instructions, and constructing a versioned transaction. The code handles potential transaction size issues by adjusting the `maxAccounts` parameter and utilizes the `@solana/web3.js` library. Dependencies include Node.js for file system access and the Solana Web3.js library.

```javascript
import {
    AddressLookupTableAccount,
    Connection,
    Keypair,
    PublicKey,
    TransactionInstruction,
    TransactionMessage,
    VersionedTransaction,
} from '@solana/web3.js';

// Set up dev environment
import fs from 'fs';
const privateKeyArray = JSON.parse(fs.readFileSync('/Path/to/key', 'utf8').trim());
const wallet = Keypair.fromSecretKey(new Uint8Array(privateKeyArray));
const connection = new Connection('your-own-rpc');

// Recommended
const MAX_ACCOUNTS = 64

async function getQuote(maxAccounts) {
    const params = new URLSearchParams({
        inputMint: 'insert-mint',
        outputMint: 'insert-mint',
        amount: '1000000',
        slippageBps: '100',
        maxAccounts: maxAccounts.toString()
    });

    const url = `https://0.0.0.0:8080/quote?${params}`;
    const response = await fetch(url);

    if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP ${response.status}: ${errorText}`);
    }

    const quoteResponse = await response.json();

    if (quoteResponse.error) {
        throw new Error(`API error: ${quoteResponse.error}`);
    }

    return quoteResponse;
};

async function getSwapInstructions(quoteResponse) {
    const response = await fetch('https://0.0.0.0:8080/swap-instructions', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            quoteResponse: quoteResponse,
            userPublicKey: wallet.publicKey.toString(),
            prioritizationFeeLamports: {
                priorityLevelWithMaxLamports: {
                    maxLamports: 10000000,
                    priorityLevel: "veryHigh"
                }
            },
            dynamicComputeUnitLimit: true,
        }, null, 2)
    });

    if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP ${response.status}: ${errorText}`);
    }

    const swapInstructionsResponse = await response.json();

    if (swapInstructionsResponse.error) {
        throw new Error(`API error: ${swapInstructionsResponse.error}`);
    }

    return swapInstructionsResponse;
};

async function buildSwapTransaction(swapInstructionsResponse) {
    const {
        computeBudgetInstructions,
        setupInstructions,
        swapInstruction,
        cleanupInstruction,
        otherInstructions,
        addressLookupTableAddresses,
    } = swapInstructionsResponse;

    const deserializeInstruction = (instruction) => {
        if (!instruction) return null;
        return new TransactionInstruction({
            programId: new PublicKey(instruction.programId),
            keys: instruction.accounts.map((key) => ({
                pubkey: new PublicKey(key.pubkey),
                isSigner: key.isSigner,
                isWritable: key.isWritable,
            })),
            data: Buffer.from(instruction.data, "base64"),
        });
    };

    const getAddressLookupTableAccounts = async (
        keys
    ) => {
        const addressLookupTableAccountInfos =
            await connection.getMultipleAccountsInfo(
                keys.map((key) => new PublicKey(key))
            );

        return addressLookupTableAccountInfos.reduce((acc, accountInfo, index) => {
            const addressLookupTableAddress = keys[index];
            if (accountInfo) {
                const addressLookupTableAccount = new AddressLookupTableAccount({
                    key: new PublicKey(addressLookupTableAddress),
                    state: AddressLookupTableAccount.deserialize(accountInfo.data),
                });
                acc.push(addressLookupTableAccount);
            }

            return acc;
        }, []);
    };

    const addressLookupTableAccounts = [];
    addressLookupTableAccounts.push(
        ...(await getAddressLookupTableAccounts(addressLookupTableAddresses))
    );

    const blockhash = (await connection.getLatestBlockhash()).blockhash;

    // Create transaction message with all instructions
    const messageV0 = new TransactionMessage({
        payerKey: wallet.publicKey,
        recentBlockhash: blockhash,
        instructions: [

```

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

### Create Token Account

Source: https://metis.builders/docs/add-fees-to-swap

This section details how to create an associated token account for a given mint and owner. It utilizes the Solana SPL Token library to construct and send the necessary transaction.

```APIDOC
## Create Token Account

To create a token account, you can use the following code or refer to [Solana Cookbook](https://solana.com/developers/cookbook/tokens/create-token-account).

* The code builds a transaction to create an associated token account based on the mint provided.
* We use associated token account as they are deterministic based on the given mint and owner - allowing for simpler management of token accounts.
* Refer to [Solana docs on associated token accounts](https://solana.com/docs/tokens#associated-token-account) for more details.

### Method
POST (Implicitly via transaction submission)

### Endpoint
N/A (Client-side operation)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Code executes client-side)

### Request Example
```javascript
import {
    Connection,
    Keypair,
    Transaction,
    sendAndConfirmTransaction,
    PublicKey
  } from "@solana/web3.js";
import {
    ASSOCIATED_TOKEN_PROGRAM_ID,
    TOKEN_PROGRAM_ID,
    getAssociatedTokenAddressSync,
    createAssociatedTokenAccountInstruction,
} from "@solana/spl-token";

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 mint = new PublicKey("So11111111111111111111111111111111111111112");

// Get the associated token account address
const associatedTokenAccount = getAssociatedTokenAddressSync(
    mint,
    wallet.publicKey,
    false, // allowOwnerOffCurve
    TOKEN_PROGRAM_ID,
    ASSOCIATED_TOKEN_PROGRAM_ID
);

// Create associated token account instruction
    const createAssociatedTokenAccountIx = createAssociatedTokenAccountInstruction(
    wallet.publicKey, // payer
    associatedTokenAccount, // associated token account address
    wallet.publicKey, // owner
    mint, // mint
    TOKEN_PROGRAM_ID,
    ASSOCIATED_TOKEN_PROGRAM_ID
);

// Fetch latest blockhash (ensure this is done before creating the transaction)
const latestBlockhash = await connection.getLatestBlockhash();

// Create and sign transaction for associated token account
let transaction = new Transaction({
    feePayer: wallet.publicKey,
    blockhash: latestBlockhash.blockhash,
    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight
}).add(createAssociatedTokenAccountIx);

// Sign and send transaction
const signature = await sendAndConfirmTransaction(
    connection,
    transaction,
    [wallet]
);

console.log(
    "Associated Token Account Address:",
    associatedTokenAccount.toBase58()
);
console.log("Transaction Signature:", signature);
```

### Response
#### Success Response (200)
N/A (Transaction confirmation)

#### Response Example
```json
{
  "associatedTokenAccountAddress": "<token_account_address>",
  "signature": "<transaction_signature>"
}
```
```

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

### POST /swap-instructions

Source: https://metis.builders/docs/build-swap-transaction

This endpoint allows you to build a transaction by providing instructions. It takes the same parameters as the `/swap` endpoint but returns the instructions needed to construct the transaction rather than the serialized transaction itself.

```APIDOC
## POST /swap-instructions

### Description
Build a transaction using a set of instructions. This endpoint is an alternative to directly getting a serialized transaction, providing more control over the transaction construction process.

### Method
POST

### Endpoint
/swap-instructions

### Parameters
#### Query Parameters
- **tokenA** (string) - Required - The address of the first token for the swap.
- **tokenB** (string) - Required - The address of the second token for the swap.
- **amountA** (number) - Required - The amount of tokenA to swap.
- **amountB** (number) - Required - The amount of tokenB to receive.
- **slippage** (number) - Optional - The maximum acceptable slippage percentage.
- **maxAccounts** (number) - Optional - Limits the number of accounts included in the transaction. Use with caution as it may affect trade outcomes.

### Request Body
This endpoint does not require a request body. All parameters are passed as query parameters.

### Response
#### Success Response (200)
- **computeBudgetInstructions** (array) - Instructions to set up the compute budget.
- **setupInstructions** (array) - Instructions to set up necessary accounts, like ATA.
- **swapInstruction** (object) - The core instruction for executing the swap.
- **cleanupInstruction** (object) - Optional instruction for cleanup, e.g., unwrapping SOL.
- **otherInstructions** (array) - Any additional instructions required for the transaction.
- **addressLookupTableAddresses** (array) - Addresses of lookup tables for versioned transactions.

#### Response Example
```json
{
  "computeBudgetInstructions": [
    {
      "programId": "ComputeBudget111111111111111111111111111111",
      "accounts": [],
      "data": "AQAB"
    }
  ],
  "setupInstructions": [],
  "swapInstruction": {
    "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "accounts": [
      // ... account details ...
    ],
    "data": "base64encodedswapdata"
  },
  "cleanupInstruction": null,
  "otherInstructions": [],
  "addressLookupTableAddresses": [
    "AddressLookupTableAddress1",
    "AddressLookupTableAddress2"
  ]
}
```

### Transaction Size Limit
The transaction size limit is 1232 bytes. Exceeding this limit may occur if too many accounts are added. The `maxAccounts` parameter in the `/quote` endpoint can help manage this, but be aware it might lead to less favorable trades.
```

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

### Build Swap Transaction with Instructions (JavaScript)

Source: https://metis.builders/docs/build-swap-transaction

This JavaScript function demonstrates how to construct a `VersionedTransaction` using instructions obtained from the `/swap-instructions` endpoint. It handles deserializing various instruction types, fetching address lookup table accounts, and compiling the transaction message. Dependencies include Solana Web3.js library components like `TransactionInstruction`, `PublicKey`, `Buffer`, `AddressLookupTableAccount`, `TransactionMessage`, and `VersionedTransaction`, as well as a `connection` object and a `wallet` object.

```javascript
async function buildSwapTransaction(swapResponse) {
    const {
        computeBudgetInstructions, // Required ix to setup compute budget
        setupInstructions, // Extra ix to setup missing ATA for the users
        swapInstruction, // The actual swap instruction
        cleanupInstruction, // Unwrap the SOL if required
        otherInstructions, // Other instructions to add to the transaction
        addressLookupTableAddresses, // The lookup table addresses that you can use if you are using versioned transaction
    } = swapResponse;
    
    const deserializeInstruction = (instruction) => {
        if (!instruction) return null;
        return new TransactionInstruction({
            programId: new PublicKey(instruction.programId),
            keys: instruction.accounts.map((key) => ({
                pubkey: new PublicKey(key.pubkey),
                isSigner: key.isSigner,
                isWritable: key.isWritable,
            })),
            data: Buffer.from(instruction.data, "base64"),
        });
    };

    const getAddressLookupTableAccounts = async (
        keys
    ) => {
        const addressLookupTableAccountInfos =
            await connection.getMultipleAccountsInfo(
                keys.map((key) => new PublicKey(key))
            );

        return addressLookupTableAccountInfos.reduce((acc, accountInfo, index) => {
            const addressLookupTableAddress = keys[index];
            if (accountInfo) {
                const addressLookupTableAccount = new AddressLookupTableAccount({
                    key: new PublicKey(addressLookupTableAddress),
                    state: AddressLookupTableAccount.deserialize(accountInfo.data),
                });
                acc.push(addressLookupTableAccount);
            }

            return acc;
        }, []);
    };

    const addressLookupTableAccounts = [];
    addressLookupTableAccounts.push(
        ...(await getAddressLookupTableAccounts(addressLookupTableAddresses))
    );

    const blockhash = (await connection.getLatestBlockhash()).blockhash;

    // Create transaction message with all instructions
    const messageV0 = new TransactionMessage({
        payerKey: wallet.publicKey,
        recentBlockhash: blockhash,
        instructions: [
            ...(computeBudgetInstructions?.map(deserializeInstruction).filter(Boolean) || []),
            ...(setupInstructions?.map(deserializeInstruction).filter(Boolean) || []),
            deserializeInstruction(swapInstruction),
            ...(cleanupInstruction ? [deserializeInstruction(cleanupInstruction)].filter(Boolean) : []),
            ...(otherInstructions?.map(deserializeInstruction).filter(Boolean) || []),
        ].filter(Boolean),
    }).compileToV0Message(addressLookupTableAccounts);

    const transaction = new VersionedTransaction(messageV0);

    return transaction;
  }
```

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

### Load Solana Wallet Keypair from .env

Source: https://metis.builders/docs/send-swap-transaction

Loads a Solana wallet's private key from a .env file and decodes it into a Keypair object. This method is suitable for local development and requires the PRIVATE_KEY to be set in the environment.

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

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

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

### Load Solana Wallet Keypair from Solana CLI Config

Source: https://metis.builders/docs/send-swap-transaction

Loads a Solana wallet's private key from the default Solana CLI configuration file (`id.json`) and creates a Keypair object. This method is useful if you manage your keys via the Solana CLI.

```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));
```

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

### Establish Solana RPC Connection

Source: https://metis.builders/docs/add-fees-to-swap

Establishes a connection to the Solana network using a provided RPC endpoint. It's recommended to use a dedicated RPC provider for growing applications.

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

const connection = new Connection("https://api.mainnet-beta.solana.com");
```

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

### POST /swap

Source: https://metis.builders/docs/add-fees-to-swap

Executes a token swap based on the provided quote and user details. Requires a fee account to receive swap fees.

```APIDOC
## POST /swap

### Description
Executes a token swap based on the provided quote and user details. Requires a fee account to receive swap fees.

### Method
POST

### Endpoint
`/swap`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **quoteResponse** (object) - Required - The quote object obtained from the `/quote` endpoint.
* **userPublicKey** (string) - Required - The public key of the user initiating the swap.
* **feeAccount** (string) - Required - The token account address that will receive the swap fees. This must be a valid token account for either the input or output mint of the swap pair.

### Request Example
```javascript
const swapResponse = await (
    await fetch('https://0.0.0.0:8080/swap', {
        method: 'POST',
        headers: {
        'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            quoteResponse, // Obtained from the /quote endpoint
            userPublicKey: wallet.publicKey.toBase58(), // User's public key
            feeAccount: associatedTokenAccount.toBase58(), // Fee account address
        })
    })
).json();
```

### Response
#### Success Response (200)
* **signature** (string) - The signature of the executed swap transaction.

#### Response Example
```json
{
  "signature": "<transaction_signature>"
}
```
```

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

### Quote and Swap Transaction Flow

Source: https://metis.builders/docs/requote-with-lower-max-accounts

This section details the process of requesting a quote, serializing the transaction, checking for size limitations, and then signing and sending the transaction.

```APIDOC
## GET /quote

### Description
Requests a quote for a token swap based on specified parameters.

### Method
GET

### Endpoint
`/quote`

### Query Parameters
- **inputMint** (string) - Required - The mint address of the input token.
- **outputMint** (string) - Required - The mint address of the output token.
- **amount** (string) - Required - The amount of the input token to swap.
- **slippageBps** (string) - Required - The slippage tolerance in basis points.
- **maxAccounts** (string) - Optional - The maximum number of accounts to include in the transaction. Recommended to start high and decrement if needed.

### Request Example
`GET https://0.0.0.0:8080/quote?inputMint=insert-mint&outputMint=insert-mint&amount=1000000&slippageBps=100&maxAccounts=64`

### Response
#### Success Response (200)
- **quoteResponse** (object) - Contains details for the swap transaction.
  - **error** (string) - An error message if the quote request failed.

#### Response Example
```json
{
  "quoteResponse": {
    "someQuoteDetail": "value"
  }
}
```

---

## POST /swap-instructions

### Description
Retrieves the necessary instructions to execute a swap transaction based on a provided quote.

### Method
POST

### Endpoint
`/swap-instructions`

### Request Body
- **quoteResponse** (object) - Required - The quote details obtained from the `/quote` endpoint.
- **userPublicKey** (string) - Required - The public key of the user initiating the swap.
- **prioritizationFeeLamports** (object) - Optional - Specifies prioritization fee settings.
  - **priorityLevelWithMaxLamports** (object) - Required if `prioritizationFeeLamports` is provided.
    - **maxLamports** (number) - Required - The maximum lamports to pay for priority fees.
    - **priorityLevel** (string) - Required - The desired priority level (e.g., "veryHigh").
- **dynamicComputeUnitLimit** (boolean) - Optional - Whether to use dynamic compute unit limit. Defaults to false.

### Request Example
```json
{
  "quoteResponse": {
    "someQuoteDetail": "value"
  },
  "userPublicKey": "user_public_key_string",
  "prioritizationFeeLamports": {
    "priorityLevelWithMaxLamports": {
      "maxLamports": 10000000,
      "priorityLevel": "veryHigh"
    }
  },
  "dynamicComputeUnitLimit": true
}
```

### Response
#### Success Response (200)
- **computeBudgetInstructions** (array) - Instructions for compute budget.
- **setupInstructions** (array) - Instructions for setting up the transaction.
- **swapInstruction** (object) - The core swap instruction.
- **cleanupInstruction** (object) - Instructions for cleaning up after the swap.
- **otherInstructions** (array) - Any other miscellaneous instructions.
- **addressLookupTableAddresses** (array) - Addresses of lookup tables required for the transaction.
- **error** (string) - An error message if the instruction retrieval failed.

#### Response Example
```json
{
  "computeBudgetInstructions": [],
  "setupInstructions": [],
  "swapInstruction": {
    "programId": "program_id_string",
    "accounts": [],
    "data": "base64_encoded_data"
  },
  "cleanupInstruction": null,
  "otherInstructions": [],
  "addressLookupTableAddresses": ["alt_address_string"]
}
```

---

## Transaction Size Check and Signing

### Description
This process involves serializing the transaction, checking its size against limits, and requoting if necessary before signing and sending.

### Workflow
1. **Serialize Transaction**: Convert the transaction instructions into a serialized format. Logging the raw byte size is recommended.
2. **Check Transaction Size**: Evaluate if the serialized transaction exceeds the network's or a predefined limit (e.g., using `maxAccounts`).
3. **Requote if Too Large**: If the transaction is too large, request a new quote with a reduced `maxAccounts` value. Be aware that this may alter the transaction route.
4. **Sign and Send**: If the transaction size is acceptable, sign it using the wallet and send it to the network.

### Recommendations
- **`maxAccounts`**: Start with a higher value (e.g., 64) and incrementally decrease it during requotes to find an optimal balance.
- **Logging**: Log the byte size of the serialized transaction for debugging and analysis.
- **Instruction Placement**: Custom instructions can be added before or after transaction serialization.
```

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

### Load Wallet from Solana CLI Configuration

Source: https://metis.builders/docs/build-swap-transaction

Loads a Solana wallet's private key from the default Solana CLI configuration file. This is a common method for managing keys in a production environment.

```javascript
const { Keypair } = require('@solana/web3.js');
const fs = require('fs');

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

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

### Create Solana Token Account using SPL Token

Source: https://metis.builders/docs/add-fees-to-swap

This JavaScript code demonstrates how to create an associated token account on the Solana blockchain using the SPL Token program. It builds and sends a transaction to establish the account, which is deterministically derived from the mint and owner addresses. Dependencies include @solana/web3.js and @solana/spl-token.

```javascript
import {
    Connection,
    Keypair,
    Transaction,
    sendAndConfirmTransaction,
    PublicKey
  } from "@solana/web3.js";
import {
    ASSOCIATED_TOKEN_PROGRAM_ID,
    TOKEN_PROGRAM_ID,
    getAssociatedTokenAddressSync,
    createAssociatedTokenAccountInstruction,
} from "@solana/spl-token";

import fs from 'fs';

// Assume latestBlockhash is fetched prior to this snippet
// 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 mint = new PublicKey("So11111111111111111111111111111111111111112");
// const latestBlockhash = await connection.getLatestBlockhash();

// Get the associated token account address
const associatedTokenAccount = getAssociatedTokenAddressSync(
    mint,
    wallet.publicKey,
    false, // allowOwnerOffCurve
    TOKEN_PROGRAM_ID,
    ASSOCIATED_TOKEN_PROGRAM_ID
);

// Create associated token account instruction
    const createAssociatedTokenAccountIx = createAssociatedTokenAccountInstruction(
    wallet.publicKey, // payer
    associatedTokenAccount, // associated token account address
    wallet.publicKey, // owner
    mint, // mint
    TOKEN_PROGRAM_ID,
    ASSOCIATED_TOKEN_PROGRAM_ID
);

// Create and sign transaction for associated token account
let transaction = new Transaction({
    feePayer: wallet.publicKey,
    blockhash: latestBlockhash.blockhash,
    lastValidBlockHeight: latestBlockhash.lastValidBlockHeight
}).add(createAssociatedTokenAccountIx);

// Sign and send transaction
const signature = await sendAndConfirmTransaction(
    connection,
    transaction,
    [wallet]
);

console.log(
    "Associated Token Account Address:",
    associatedTokenAccount.toBase58()
);
console.log("Transaction Signature:", signature);
```

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

### Build Solana VersionedTransaction with Instructions

Source: https://metis.builders/docs/requote-with-lower-max-accounts

Constructs a Solana VersionedTransaction by deserializing and compiling various instruction types into a V0 message. It handles optional instructions and filters out any invalid ones before compiling. The function returns a VersionedTransaction object ready for further processing.

```javascript
function buildSwapTransaction(swapInstructionsResponse) {
    const { computeBudgetInstructions, setupInstructions, swapInstruction, cleanupInstruction, otherInstructions } = swapInstructionsResponse;

    const messageV0 = MessageV0.compile({ 
        payer: "YOUR_PAYER_ADDRESS", // Replace with actual payer address
        instructions: [
            ...(computeBudgetInstructions?.map(deserializeInstruction).filter(Boolean) || []),
            ...(setupInstructions?.map(deserializeInstruction).filter(Boolean) || []),
            deserializeInstruction(swapInstruction),
            ...(cleanupInstruction ? [deserializeInstruction(cleanupInstruction)].filter(Boolean) : []),
            ...(otherInstructions?.map(deserializeInstruction).filter(Boolean) || []),
        ].filter(Boolean),
    }).compileToV0Message(addressLookupTableAccounts);

    const transaction = new VersionedTransaction(messageV0);

    return transaction;
}
```

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

### Load Wallet from .env File

Source: https://metis.builders/docs/build-swap-transaction

Loads a Solana wallet's private key from a .env file using base58 decoding. This method is suitable for development environments.

```javascript
const { Keypair } = require('@solana/web3.js');
const bs58 = require('bs58');
const dotenv = require('dotenv');
dotenv.config();

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

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

### Build Swap Transaction POST Request (JavaScript)

Source: https://metis.builders/docs/build-swap-transaction

Constructs a POST request to the /swap API endpoint to build a swap transaction. It requires the quote response and the user's public key. Optional parameters like dynamicComputeUnitLimit and prioritizationFeeLamports can be included to optimize transaction landing.

```javascript
const swapResponse = await (
  await fetch('https://0.0.0.0:8080/swap', {
      method: 'POST',
      headers: {
      'Content-Type': 'application/json',
      },
      body: JSON.stringify({
      quoteResponse,
      userPublicKey: wallet.publicKey,

      // ADDITIONAL PARAMETERS TO OPTIMIZE FOR TRANSACTION LANDING
      // See next page about sending of swap transactions
      // To optimize for transaction landing
      dynamicComputeUnitLimit: true,
      prioritizationFeeLamports: {
            priorityLevelWithMaxLamports: {
              maxLamports: 1000000,
              priorityLevel: "veryHigh"
            }
          }
      })
  })
  ).json();

```

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

### Broadcasting Swap Transaction with Jito Tip (JavaScript)

Source: https://metis.builders/docs/send-swap-transaction

This JavaScript snippet demonstrates how to send a swap transaction to a Jito RPC endpoint, including a fixed Jito tip for prioritization. It uses the `fetch` API to make a POST request with transaction details in the request body. Ensure the endpoint and parameters are correctly configured for Jito processing.

```javascript
const swapTransaction = await (
  await fetch('https://0.0.0.0:8080/swap', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      quoteResponse,
      userPublicKey: wallet.publicKey,
      prioritizationFeeLamports: {
        jitoTipLamports: 1000000 // note that this is FIXED LAMPORTS not a max cap
      }
    })
  })
).json();
```

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

### POST /swap

Source: https://metis.builders/docs/build-swap-transaction

Builds a swap transaction by taking a quote response and the user's public key as input. It also allows for optional parameters to optimize transaction landing, such as dynamic compute unit limit and prioritization fees.

```APIDOC
## POST /swap

### Description
Builds a swap transaction by taking a quote response and the user's public key as input. It also allows for optional parameters to optimize transaction landing, such as dynamic compute unit limit and prioritization fees.

### Method
POST

### Endpoint
/swap

### Parameters
#### Query Parameters
- **quoteResponse** (object) - Required - The quote response from the Get Quote API.
- **userPublicKey** (string) - Required - The public key of the wallet keypair to sign the transaction.
- **dynamicComputeUnitLimit** (boolean) - Optional - When enabled, it will simulate the transaction to determine the compute unit used and set it in ComputeBudget's compute unit limit.
- **prioritizationFeeLamports** (object) - Optional - Specifies a level or amount of additional fees to prioritize the transaction.
  - **maxLamports** (number) - Required if prioritizationFeeLamports is provided - The maximum lamports to offer for prioritization.
  - **priorityLevel** (string) - Required if prioritizationFeeLamports is provided - The priority level (e.g., 'veryHigh').

### Request Example
```json
{
  "quoteResponse": { ... },
  "userPublicKey": "<user_public_key>",
  "dynamicComputeUnitLimit": true,
  "prioritizationFeeLamports": {
    "maxLamports": 1000000,
    "priorityLevel": "veryHigh"
  }
}
```

### Response
#### Success Response (200)
- **swapTransaction** (string) - The base64-encoded swap transaction.
- **lastValidBlockHeight** (number) - The last valid block height for the transaction.
- **prioritizationFeeLamports** (number) - The actual prioritization fee in lamports.
- **computeUnitLimit** (number) - The compute unit limit for the transaction.
- **prioritizationType** (object) - Details about the prioritization fee calculation.
- **simulationSlot** (number) - The slot at which the transaction was simulated.
- **dynamicSlippageReport** (object | null) - Report on dynamic slippage, if applicable.
- **simulationError** (string | null) - Any error encountered during simulation.
- **addressesByLookupTableAddress** (object | null) - Addresses associated with lookup tables, if applicable.

#### Response Example
```json
{
  "swapTransaction": "<base64-encoded-swap-transaction>",
  "lastValidBlockHeight": 356607094,
  "prioritizationFeeLamports": 1789048,
  "computeUnitLimit": 304832,
  "prioritizationType": {
    "computeBudget": {
      "microLamports": 5868966,
      "estimatedMicroLamports": 5868966
    }
  },
  "simulationSlot": 378451364,
  "dynamicSlippageReport": null,
  "simulationError": null,
  "addressesByLookupTableAddress": null
}
```
```

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

### Execute Swap with Fee Account (JavaScript)

Source: https://metis.builders/docs/add-fees-to-swap

This JavaScript code snippet illustrates how to execute a token swap using the Metis Builders API's `/swap` endpoint. It includes the `feeAccount` parameter, which specifies the token account designated to receive swap fees. The `feeAccount` must be compatible with the input or output mint of the swap pair, as detailed in the documentation.

```javascript
const swapResponse = await (
    await fetch('https://0.0.0.0:8080/swap', {
        method: 'POST',
        headers: {
        'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            quoteResponse,
            userPublicKey: wallet.publicKey, // Pass in actual referred user in production
            feeAccount: associatedTokenAccount, // feeAccount is the token account that will receive the fees
        })
    })
).json();
```

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

### Establish Solana RPC Connection

Source: https://metis.builders/docs/send-swap-transaction

Establishes a connection to the Solana network using a provided RPC endpoint. It's recommended to use a dedicated RPC provider for production applications.

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

const connection = new Connection('https://api.mainnet-beta.solana.com');
```

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

### Establish RPC Connection to Solana Network

Source: https://metis.builders/docs/build-swap-transaction

Connects to the Solana network using a provided RPC endpoint. It's recommended to use a dedicated RPC provider for growing applications.

```javascript
const { Connection } = require('@solana/web3.js');

const connection = new Connection('https://api.mainnet-beta.solana.com');
```
Tokens:
Raw