Skip to main content
Every request to the Vulcx API (https://api.vulcx.xyz) is authenticated with an API key, except GET /health and GET /api/v1/tokens, which are public and require no key. 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 only option for the WebSocket stream).
This applies to the WebSocket stream too: GET /api/v1/stream requires a key just like every other endpoint. See WebSocket streaming below for the query-param form.
Vulcx is free during beta — there are no paid tiers yet. You still need a key so we can apply rate limits and keep the service healthy.

​
Get an API key

1

Request a key

During beta, keys are issued through our Telegram. Reach out and ask — keys are granted at no cost.

Get an API key on Telegram

Message the Vulcx team on Telegram and request a key.
2

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 and widget

The SDK and widget take the key directly — you don’t set headers yourself. 
import { VulcxSDK } from "@vulcx/sdk";

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

<vulcx-swap api-key="vulcx_your_key_here" theme="dark"></vulcx-swap>

​
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 and widget 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

A missing or invalid key returns an authentication error:
StatusMeaning
401 UnauthorizedNo API key was provided.
403 ForbiddenThe key is invalid, disabled, or revoked.
The SDK surfaces these as AuthError — see SDK error handling. For throughput limits and the 429 response, see Rate limits.
Last modified on July 5, 2026

Related topics

Stream QuotesHandling ErrorsVulcx API reference — quote, swap & instructionsIntroduction to Vulcx — best-price swaps on Fogo