Get Instructions

POST /api/v1/instructions returns raw instructions instead of a complete transaction. Use this when you need to combine swap instructions with other logic in a single transaction.

When to use this instead of `/swap`

You need to create token accounts before the swap.
You want to add a memo instruction for tracking.
You need to close accounts after the swap.
You’re building a multi-action transaction (e.g., swap + stake in one tx).
You want full control over compute budget and priority fees.

If you just need a simple swap, use POST /swap instead.

Request

The request body is identical to /swap except there is no skipSimulation field (no transaction is built, so there’s nothing to simulate).

string

required

User’s wallet address (signer).

string

required

Input token mint address.

string

required

Output token mint address.

string

required

Amount in smallest token units.

string

required

ExactIn or ExactOut.

integer

default:"50"

Slippage tolerance in basis points.

string

Firm-quote ID from GET /quote or a stream push. Replays the exact quoted route with min-out anchored to the quoted price. See Firm quotes.

boolean

default:"false"

Price-or-fail redemption — requires quoteId, only within the quote’s firmForMs window. See Firm quotes.

string

Optional referrer wallet (base58). Receives integratorFeeBps in full, paid on-chain in the output token in the same transaction as the swap. Required whenever integratorFeeBps is set.

integer

default:"0"

Your own fee rate, in basis points of the output amount — you keep 100% of it. It is added to Vulcx’s platformFeeBps, not carved out of it, and the sum may not exceed 100 bps (400 otherwise). Requires referrer. See Fees.

string

Optional Fogo session account (base58). Builds a session-shaped route: the session account is the signing authority (userWallet’s ATAs still hold the funds), and no ATA-create or SOL-wrap instructions are emitted — the response’s requiredTokenAccounts lists what must already exist. Send via the Fogo Sessions SDK (session key signs, paymaster pays). Session routes are currently Valiant-V1-only.

Example

curl -X POST "https://api.vulcx.xyz/api/v1/instructions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VULCX_KEY" \
  -d '{
    "userWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",
    "amount": "1000000000",
    "swapMode": "ExactIn",
    "slippageBps": 50
  }'

const response = await fetch("https://api.vulcx.xyz/api/v1/instructions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.VULCX_KEY}`,
  },
  body: JSON.stringify({
    userWallet: wallet.publicKey.toBase58(),
    inputMint: "So11111111111111111111111111111111111111112",
    outputMint: "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",
    amount: "1000000000",
    swapMode: "ExactIn",
    slippageBps: 50,
  }),
});

const { success, data, error } = await response.json();
if (!success) throw new Error(error);

console.log(`${data.instructions.length} instructions, ${data.hopCount} hop(s)`);

import os, requests

resp = requests.post(
    "https://api.vulcx.xyz/api/v1/instructions",
    json={
        "userWallet": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
        "inputMint": "So11111111111111111111111111111111111111112",
        "outputMint": "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",
        "amount": "1000000000",
        "swapMode": "ExactIn",
        "slippageBps": 50,
    },
    headers={"Authorization": f"Bearer {os.environ['VULCX_KEY']}"},
)
result = resp.json()
if not result["success"]:
    raise Exception(result["error"])

data = result["data"]
print(f"{len(data['instructions'])} instructions, {data['hopCount']} hop(s)")

Response

{
  "success": true,
  "data": {
    "amountIn": "1000000000",
    "amountOut": "145320000",
    "otherAmountThreshold": "144593400",
    "feeAmount": "100005",
    "route": [
      "So11111111111111111111111111111111111111112",
      "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG"
    ],
    "hopCount": 1,
    "pools": ["HJPjoWUrhoZzkNfRpHuieeFk9WcZWjwy6PBjZ81ngndJ"],
    "instructions": [
      {
        "programId": "vnt1u7PzorND5JjweFWmDawKe2hLWoTwHU6QKz6XX98",
        "data": "AQAAAA...",
        "accounts": [
          { "publicKey": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM", "isSigner": true, "isWritable": true },
          { "publicKey": "HJPjoWUrhoZzkNfRpHuieeFk9WcZWjwy6PBjZ81ngndJ", "isSigner": false, "isWritable": true }
        ]
      }
    ],
    "addressLookupTableAddresses": [
      "AddressLookupTab1e1111111111111111111111111"
    ]
  }
}

Response fields

string

Input amount in smallest units.

string

Estimated output amount.

string

Slippage-adjusted threshold. ExactIn: minimum output. ExactOut: maximum input.

string

DEX pool trading fee across every hop — the LP fee the pools take, not Vulcx’s.

integer

Vulcx’s fee rate, in bps of the output. 0 when the protocol fee is disabled on-chain or waived for you.

string

platformFeeBps applied to amountOut, in output token units.

integer

Your own fee rate, echoed back. Independent of platformFeeBps — the two add. See Fees.

string

integratorFeeBps applied to amountOut, paid on-chain to your referrer wallet.

string[]

Token path from input to output.

integer

Number of swap hops.

string[]

Pool addresses used.

RawInstruction[]

Ordered list of instructions to include in the transaction.

Show RawInstruction fields

string

Base58-encoded program ID.

string

Base64-encoded instruction data.

RawAccountMeta[]

Account list for this instruction.

Show RawAccountMeta fields

string

Base58-encoded account public key.

boolean

Whether this account must sign the transaction.

boolean

Whether this account is written to.

string[]

Address Lookup Table (ALT) addresses. Include these when building a v0 transaction to reduce transaction size.

string[]

Session mode only (sessionAccount set): the user’s ATAs the route touches, ordered [inputMint, …intermediates, outputMint]. They must exist — and the input ATA hold amountIn — before the session transaction is sent, since session instructions include no ATA-create or SOL-wrap steps.

Building a transaction from instructions

TypeScript

import {
  Connection,
  TransactionMessage,
  VersionedTransaction,
  PublicKey,
  AddressLookupTableAccount,
} from "@solana/web3.js";

const connection = new Connection("https://mainnet.fogo.io");

// 1. Fetch address lookup tables
const altAccounts: AddressLookupTableAccount[] = [];
for (const altAddress of data.addressLookupTableAddresses) {
  const altAccount = await connection.getAddressLookupTable(new PublicKey(altAddress));
  if (altAccount.value) altAccounts.push(altAccount.value);
}

// 2. Convert raw instructions to TransactionInstruction
const instructions = data.instructions.map((ix) => ({
  programId: new PublicKey(ix.programId),
  keys: ix.accounts.map((acc) => ({
    pubkey: new PublicKey(acc.publicKey),
    isSigner: acc.isSigner,
    isWritable: acc.isWritable,
  })),
  data: Buffer.from(ix.data, "base64"),
}));

// 3. Build v0 transaction
const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();

const messageV0 = new TransactionMessage({
  payerKey: wallet.publicKey,
  recentBlockhash: blockhash,
  instructions,
}).compileToV0Message(altAccounts);

const transaction = new VersionedTransaction(messageV0);
transaction.sign([wallet]);

// 4. Submit
const signature = await connection.sendRawTransaction(transaction.serialize());
await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight });

Always include the addressLookupTableAddresses when building a v0 transaction. Without them, the transaction may exceed the size limit for multi-hop routes.

Swap

Concepts

Get Instructions

Get Instructions

When to use this instead of `/swap`

Request

Example

Response

Response fields

Building a transaction from instructions

​Get Instructions

​When to use this instead of /swap

​Request

​Example

​Response

​Response fields

​Building a transaction from instructions

Get Instructions

When to use this instead of `/swap`

Request

Example

Response

Response fields

Building a transaction from instructions