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 1 cost unit/second; send a key and you get your own 100 cost units/second. 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. See WebSocket streaming below.

Vulcx is free during beta — there are no paid tiers yet. Getting a key is still worthwhile: anonymous access is capped at 1 cost unit per second against the 100 a 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.

Get an API key

Request a key

Keys are free during beta and issued by hand, so the form asks what you are building. You will hear back within a day.

Request an API key

Takes a minute. Email, product, and what you are building.

Prefer to just ask? Telegram still works.

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=So11111111111111111111111111111111111111112&outputMint=uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG&amount=1000000000&swapMode=ExactIn" \
  -H "Authorization: Bearer $VULCX_KEY"

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

import os, requests

res = requests.get(
    "https://api.vulcx.xyz/api/v1/quote",
    params={
        "inputMint": "So11111111111111111111111111111111111111112",
        "outputMint": "uSd2czE61Evaf76RNbq4KPpXnkiL3irdzgLFUMe3NoG",
        "amount": "1000000000",
        "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

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.

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

Request an API key

​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