Authentication — API keys & the Authorization header

An API key is optional on REST calls to the Vulcx API (https://api.vulcx.xyz) — /quote, /swap, /instructions, and /price all work with no key. Without one, you’re on a small shared anonymous budget of 2 cost units/second; send a key and you get your plan’s own budget — 20 cost units/second on Free, more on paid plans. Keys look like vulcx_ followed by a long hex string, and you send them in the standard Authorization: Bearer header (or as a ?key= query parameter).

The WebSocket stream is the exception: GET /api/v1/stream always requires a key, passed as ?key= since a browser WS handshake can’t carry custom headers, and the key’s plan must include stream connections. See WebSocket streaming below.

Getting a key is worthwhile even on Free: anonymous access is capped at 2 cost units per second, burst 20, against the 20/40 a Free key gets (see Rate limits), and a key is what gives you your own budget rather than a bucket shared with every anonymous caller on your IP. Paid plans raise the budget and add stream connections.

Get an API key

Create a key

Sign in to the portal with Google or GitHub and create a key. It works against mainnet immediately on the Free plan; upgrade there when you need a larger budget or the stream.

Open the Vulcx Portal

Keys, per-key fee defaults, usage and earnings.

Need something the plans don’t cover? Ask on Telegram.

Store it as an environment variable

Never hard-code a key in source. Keep it in an environment variable:

export VULCX_KEY="vulcx_your_key_here"

Authenticate a request

Send your key in the Authorization header on every request:

curl "https://api.vulcx.xyz/api/v1/quote?inputMint=uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG&outputMint=So11111111111111111111111111111111111111112&amount=10000000&swapMode=ExactIn" \
  -H "Authorization: Bearer $VULCX_KEY"

const res = await fetch(
  "https://api.vulcx.xyz/api/v1/quote?inputMint=uSd2...&outputMint=So11...&amount=10000000&swapMode=ExactIn",
  { headers: { Authorization: `Bearer ${process.env.VULCX_KEY}` } },
);

import os, requests

res = requests.get(
    "https://api.vulcx.xyz/api/v1/quote",
    params={
        "inputMint": "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",  # USDC.s, 6 decimals
        "outputMint": "So11111111111111111111111111111111111111112",  # FOGO, 9 decimals
        "amount": "10000000",  # 10 USDC.s
        "swapMode": "ExactIn",
    },
    headers={"Authorization": f"Bearer {os.environ['VULCX_KEY']}"},
)

SDK

The SDK takes the key directly — you don’t set headers yourself.

SDK

import { VulcxSDK } from "@vulcx/sdk";

const sdk = new VulcxSDK({ apiKey: process.env.VULCX_KEY });

WebSocket streaming

Browsers can’t set custom headers on a WebSocket connection, so the streaming endpoint accepts the key as a key query parameter instead:

wss://api.vulcx.xyz/api/v1/stream?key=vulcx_your_key_here

The stream is part of paid plans from Starter up, and each plan caps how many connections the account may hold at once — see Rate limits. Free-plan keys keep one connection until 14 November 2026.

Keep your key secret

A key grants access under your account’s rate limits. Treat it like a password.

Server-side keys stay on the server. Don’t commit keys to git or ship them in a public repo.
Browser usage exposes the key in client code. For client-side embeds, use a key you’ve provisioned for that purpose and rotate it if it leaks.
Rotate compromised keys by requesting a new one and retiring the old.

Errors

Status	Meaning
`401 Unauthorized`	No API key was provided, on an endpoint that requires one — only the WebSocket stream (`/api/v1/stream`) requires a key; REST calls with no key succeed anonymously instead.
`403 Forbidden`	The key is invalid, disabled, or revoked — or, on the stream, its plan does not include stream connections (`STREAM_NOT_IN_PLAN`).
`429 Too Many Requests`	On the stream: the account already holds its plan’s connections (`STREAM_LIMIT`).

The SDK surfaces these as AuthError — see SDK error handling. For throughput limits — including the tighter anonymous-tier limit — and the 429 response, see Rate limits.

​Get an API key

Open the Vulcx Portal

​Authenticate a request

​SDK

​WebSocket streaming

​Keep your key secret

​Errors

Get an API key

Authenticate a request

SDK

WebSocket streaming

Keep your key secret

Errors