Build Transaction

POST /api/v1/swap builds a complete unsigned transaction for a token swap. Sign it with the user’s wallet and submit to the network.

Request

string

required

User’s wallet address (base58). This wallet signs and pays for the transaction.

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. Default: 50 (0.5%).

boolean

default:"false"

Skip transaction simulation. Faster but no pre-flight validation. Only set true if you handle validation yourself.

string

Firm-quote ID from GET /quote or a stream push. Replays the exact quoted route with min-out anchored to the quoted price. Pair, amount, and swapMode must match the quote. 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.

boolean

default:"false"

Price-or-fail redemption — requires quoteId, only within the quote’s firmForMs window. Slippage collapses to the server’s firm margin (default 10 bps); if the price drifted past it, the request fails with 409 instead of executing worse. See Firm quotes.

Example

curl -X POST "https://api.vulcx.xyz/api/v1/swap" \
  -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/swap", {
  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(`Transaction built. Expires at block ${data.lastValidBlockHeight}`);

import os, requests

resp = requests.post(
    "https://api.vulcx.xyz/api/v1/swap",
    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"Transaction built. Expires at block {data['lastValidBlockHeight']}")

Response

{
  "success": true,
  "data": {
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAHEAo...",
    "lastValidBlockHeight": 245832190,
    "amountIn": "1000000000",
    "amountOut": "145320000",
    "minAmountOut": "144593400",
    "feeAmount": "0",
    "simulation": {
      "success": true,
      "logs": [],
      "computeUnitsConsumed": 85000,
      "insufficientFunds": false,
      "slippageExceeded": false
    },
    "computeUnitsEstimate": 85000,
    "route": [
      "So11111111111111111111111111111111111111112",
      "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG"
    ],
    "hopCount": 1,
    "pools": ["HJPjoWUrhoZzkNfRpHuieeFk9WcZWjwy6PBjZ81ngndJ"],
    "isSplitRoute": false
  }
}

Response fields

string

Base64-encoded unsigned transaction. Deserialize, sign, and submit.

integer

Transaction expires after this block height (~60 seconds from creation).

string

Input amount in smallest units.

string

Estimated output amount in smallest units.

string

Minimum output after slippage (ExactIn only). Transaction reverts if actual output is less.

string

Maximum input after slippage (ExactOut only). Transaction reverts if actual input exceeds this.

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.

object

Simulation result (omitted if skipSimulation: true).

Show SimulationResult fields

boolean

Whether the simulation passed.

string[]

Program log output.

integer

CU used during simulation.

string

Error message if simulation failed.

boolean

Wallet doesn’t have enough balance.

boolean

Price moved beyond tolerance.

integer

Estimated compute units for execution.

string[]

Token path from input to output.

integer

Number of swap hops.

string[]

Pool addresses used, in execution order.

boolean

Whether liquidity is split across multiple pools.

integer[]

Percentage split per pool (only if isSplitRoute is true).

Simulation

By default, the API simulates the transaction before returning it. This catches common issues early:

`simulation` field	Meaning	What to do
`insufficientFunds: true`	Wallet doesn’t have enough tokens or FOGO for fees	Show balance error to user
`slippageExceeded: true`	Price changed between quote and transaction build	Retry with a fresh quote
`success: false` + `error`	Other simulation failure	Check `logs` for details

Set skipSimulation: true only if you need lower latency and handle validation yourself.

What’s next

After receiving the transaction, sign and submit it.

Swap

Concepts

Build Transaction

Build Transaction

Request

Example

Response

Response fields

Simulation

What’s next

​Build Transaction

​Request

​Example

​Response

​Response fields

​Simulation

​What’s next

Build Transaction

Request

Example

Response

Response fields

Simulation

What’s next