# Vulcx

> Vulcx is a swap aggregator on Fogo providing best-price multi-hop routing across Vortex, Fluxbeam, Fogo.fun and Moonit bonding curves.
> Base URL: `https://api.vulcx.xyz`. Three core endpoints: GET /api/v1/quote, POST /api/v1/swap, POST /api/v1/instructions. Every endpoint requires an API key (Authorization: Bearer or ?key= for WebSocket) except GET /health and GET /api/v1/tokens.

## Get Started

- [Introduction](https://docs.vulcx.xyz/get-started/introduction): Introduction to Vulcx, a swap aggregator on Fogo. Covers what Vulcx is, its value props (best-price multi-hop routing, fast execution, simple 3-endpoint API), the endpoint table (GET /api/v1/quote, POST /api/v1/swap, POST /api/v1/instructions, GET /health, GET /api/v1/tokens) with an auth-required column, and quick cURL + TypeScript + Python examples (each including the required Authorization: Bearer header) for getting a FOGO→USDC quote on Fogo. Notes that every endpoint requires an API key except GET /health and GET /api/v1/tokens — see /get-started/authentication. Also available as a self-hosted community binary (see /get-started/self-hosted) for operators who want full control with their own FluxRPC key and community license.
- [Authentication](https://docs.vulcx.xyz/get-started/authentication): How to authenticate with the Vulcx API. Every request to https://api.vulcx.xyz is authenticated with an API key (format vulcx_...) sent in the Authorization: Bearer header, EXCEPT GET /health and GET /api/v1/tokens, which require no key. Covers getting a key (free during beta via Telegram), authenticating with cURL/TypeScript/Python, passing the key in the SDK (apiKey) and widget (api-key attribute), the WebSocket query-param form (/api/v1/stream?key=vulcx_...) which is required (not optional) since browsers can't set custom headers on a WS handshake, 401/403 errors for missing or invalid keys, key security best practices, and a link to rate limits. Fogo.
- [Architecture](https://docs.vulcx.xyz/get-started/architecture): High-level architecture of Vulcx on Fogo. Covers the data flow (client → API → Fogo network), components (API server, routing engine, on-chain program), supported DEXs (Vortex, Fluxbeam, Fogo.fun | Moonit bonding curves), and the two integration paths: POST /api/v1/swap for ready-to-sign transactions vs POST /api/v1/instructions for custom transaction composition.
- [Self-Hosted](https://docs.vulcx.xyz/get-started/self-hosted): Overview of the Vulcan (self-hosted) binary for Fogo. Explains hosted API vs self-hosted comparison (auth: API key vs license key; rate limits: gateway-enforced vs built-in; infra: managed vs self-managed; cost: subscription vs RPC fees only). Requirements: FluxRPC key (fluxrpc.com?ref=VULCX), community license key (license.vulcx.xyz), Linux amd64 or arm64 server. Docker Compose quickstart: copy .env, fill RPC_URL/YELLOWSTONE_TOKEN/COMMUNITY_LICENSE_KEY, docker compose up -d, curl /health. Same API surface as the hosted instance — all endpoints (quote, swap, instructions, price, stream) work identically. Links to full self-hosting guide (/guides/self-hosting) and vulcan GitHub. Fogo.
- [FAQ](https://docs.vulcx.xyz/get-started/faq): Frequently asked questions about Vulcx. Covers supported chains (Fogo), supported tokens on Fogo (Vortex, Fluxbeam, Fogo.fun, Moonit), quote freshness, devnet support, transaction size limits, ExactIn vs ExactOut, fee structure, rate limits, multi-hop behavior, and how to monitor API status.

## Docs — Swap

- [Swap Overview](https://docs.vulcx.xyz/docs/swap/overview): Overview of the Vulcx swap lifecycle on Fogo: get quote, build transaction or get instructions, sign and submit. Explains when to use POST /swap vs POST /instructions, ExactIn vs ExactOut swap modes, Fogo capabilities (5 max hops, Vortex/Fluxbeam/Fogo.fun/Moonit DEXs), supported tokens, and links to detailed pages for each step.
- [Get Quote](https://docs.vulcx.xyz/docs/swap/get-quote): Detailed guide for GET /api/v1/quote on Fogo. Covers all parameters (inputMint, outputMint, amount, swapMode, slippageBps), complete response schema (QuoteResponse with RouteInfo array, price impact fields, otherAmountThreshold), cURL, TypeScript, and Python examples, and price impact severity guidance.
- [Build Transaction](https://docs.vulcx.xyz/docs/swap/build-transaction): Detailed guide for POST /api/v1/swap on Fogo. Covers request body (userWallet, inputMint, outputMint, amount, swapMode, slippageBps, skipSimulation), complete response schema (SwapHandlerResponse with base64 transaction, lastValidBlockHeight, SimulationResult), simulation error handling, and cURL + TypeScript + Python examples.
- [Get Instructions](https://docs.vulcx.xyz/docs/swap/get-instructions): Detailed guide for POST /api/v1/instructions on Fogo. Explains when to use instructions instead of swap (custom transaction composition, adding memos, creating accounts). Covers request body, response schema (InstructionsResponse with RawInstruction array, addressLookupTableAddresses), and complete TypeScript example for building a v0 transaction from raw instructions with Address Lookup Tables.
- [Send Transaction](https://docs.vulcx.xyz/docs/swap/send-transaction): How to sign, submit, and confirm an Vulcx swap transaction on Fogo. Covers deserializing the base64 transaction from POST /api/v1/swap, signing with @solana/web3.js VersionedTransaction, sendRawTransaction, confirmTransaction with lastValidBlockHeight, transaction expiry handling, retry strategy, preflight checks, and confirmation levels (processed, confirmed, finalized). Includes TypeScript and Python examples.
- [Stream Quotes](https://docs.vulcx.xyz/docs/swap/stream-quotes): Guide to the Vulcx WebSocket quote stream (wss://api.vulcx.xyz/api/v1/stream) on Fogo. Requires an API key as a ?key=vulcx_... query parameter, same as every endpoint except GET /health and GET /api/v1/tokens. Explains when to stream vs poll GET /api/v1/quote, how to connect, the subscribe/unsubscribe protocol with a pairs array ({in, out, amount, exactIn}), how to handle quote and ack messages, reconnection, and limits (256 subscriptions/connection, change-only pushes, ~50ms debounce). Includes runnable Browser and Node.js (ws) examples with the key in the connection URL.

## Docs — Concepts

- [Supported Chains](https://docs.vulcx.xyz/concepts/chains): Vulcx currently supports Fogo as the primary chain. Covers Fogo capabilities: max hops per route (5), supported DEXs (Vortex, Fluxbeam, Fogo.fun, Moonit), and token standard (SPL Token).
- [Routing](https://docs.vulcx.xyz/concepts/routing): How Vulcx routing works at a high level on Fogo. Covers direct swaps, multi-hop routing through intermediate tokens (up to 5 hops), supported liquidity sources (Vortex, Fluxbeam, Fogo.fun, Moonit bonding curves), price impact severity levels, and slippage protection mechanics.
- [Fees](https://docs.vulcx.xyz/concepts/fees): Vulcx fee structure on Fogo. Covers pool fees (set by DEX operators like Vortex, Fluxbeam, Fogo.fun, and Moonit, shown in feeBps), aggregator protocol fees (shown in feeAmount), and the no-hidden-fees guarantee where amountIn/amountOut already account for all fees.
- [Security](https://docs.vulcx.xyz/concepts/security): Vulcx security model on Fogo. Covers non-custodial design (API returns unsigned transactions, user's wallet signs and submits directly), atomic execution (multi-hop reverts if any hop fails), slippage protection (on-chain enforcement via slippageBps), and open-source verification of on-chain program instructions.

## SDK

- [SDK Quickstart](https://docs.vulcx.xyz/sdk/quickstart): Quickstart for the @vulcx/sdk TypeScript SDK. Covers npm install, initializing VulcxSDK, calling sdk.quote() for a FOGO to USDC quote on Fogo, building an unsigned transaction with sdk.swap(), and signing/submitting with @solana/web3.js VersionedTransaction. Fogo.
- [SDK Configuration](https://docs.vulcx.xyz/sdk/configuration): Configuration reference for the Vulcx TypeScript SDK. Documents the SDKConfig object passed to the VulcxSDK constructor: apiKey, baseUrl, and retry behavior (retries, backoff). Includes a self-hosted API base URL override.
- [sdk.quote()](https://docs.vulcx.xyz/sdk/quote): Reference for sdk.quote() in the Vulcx TypeScript SDK. Documents QuoteRequest params (inputMint, outputMint, amount in smallest units, swapMode ExactIn/ExactOut, slippageBps default 50) and QuoteResponse fields (amountIn, amountOut, priceImpactBps, priceImpactPercent, priceImpactSeverity none/low/moderate/high/extreme, feeBps, otherAmountThreshold, routes RouteInfo array). Includes a token-decimals table and error cases. Fogo.
- [sdk.swap()](https://docs.vulcx.xyz/sdk/swap): Reference for sdk.swap() in the Vulcx TypeScript SDK. Documents SwapRequest params and SwapResponse (base64 transaction, lastValidBlockHeight, amountIn/amountOut, SimulationResult). Shows signing and submitting with @solana/web3.js VersionedTransaction and with a React wallet adapter. Fogo.
- [sdk.instructions()](https://docs.vulcx.xyz/sdk/instructions): Reference for sdk.instructions() in the Vulcx TypeScript SDK. Returns InstructionsResponse (RawInstruction array, RawAccountMeta, addressLookupTableAddresses) for composing custom transactions when you need memos/tips, account creation, or batched swaps. Includes a full v0 VersionedTransaction example with Address Lookup Tables, plus guidance on instructions() vs swap().
- [SDK Error Handling](https://docs.vulcx.xyz/sdk/error-handling): Error handling for the Vulcx TypeScript SDK. All errors extend VulcxError. Documents typed subclasses by HTTP status: BadRequestError (400), AuthError (401/403), NoRouteError (404), RateLimitError (429), ServerError (5xx), with fields and when each is thrown. Covers automatic retry/backoff and a catch-all pattern.
- [SDK Types Reference](https://docs.vulcx.xyz/sdk/types): TypeScript types exported from @vulcx/sdk. Unions: SwapMode (ExactIn or ExactOut), PriceImpactSeverity (none/low/moderate/high/extreme). Config: SDKConfig. Quote: QuoteRequest, QuoteResponse, RouteInfo. Swap: SwapRequest, SwapResponse, SimulationResult. Plus instruction types.
- [SDK Examples](https://docs.vulcx.xyz/sdk/examples): End-to-end Vulcx TypeScript SDK examples for React, Next.js (App Router), Node.js, and browser/CDN, plus an ExactOut-mode example. Each shows initializing VulcxSDK, quoting, building a transaction, and signing/submitting on Fogo.

## Widget

- [Widget Quickstart](https://docs.vulcx.xyz/widget/quickstart): Quickstart for the @vulcx/widget vulcx-swap Web Component. Shows installation via npm and CDN UMD, and embedding in plain HTML, React, Vue, and Next.js. Framework-agnostic swap UI for Fogo.
- [Widget Attributes](https://docs.vulcx.xyz/widget/attributes): Attribute reference for the Vulcx vulcx-swap Web Component: api-key (required), base-url, default-input-mint, default-output-mint, theme (dark or light), rpc-url. Covers dynamically updating attributes and examples (minimal, pre-selected FOGO to USDC, self-hosted with custom RPC).
- [Widget Events](https://docs.vulcx.xyz/widget/events): Event reference for the Vulcx vulcx-swap Web Component. Documents quote-update (QuoteResponse), swap-initiated (inputMint, outputMint, amount), swap-complete (SwapResponse), swap-error (error string), and connect-wallet. All events bubble and are composed so they cross the shadow DOM. Includes React and Vue listener examples.
- [Widget Theming](https://docs.vulcx.xyz/widget/theming): Theming guide for the Vulcx vulcx-swap Web Component. Built-in dark (default) and light themes; full CSS custom-property reference (--vulcx-bg, --vulcx-surface, --vulcx-accent, --vulcx-error, --vulcx-radius, and more). Custom branding examples (accent, rounded/sharp corners, custom background and font), Shadow DOM notes, and width control.
- [Widget Wallet Integration](https://docs.vulcx.xyz/widget/wallet-integration): Wallet integration for the Vulcx vulcx-swap Web Component. The widget bundles no wallet adapter; it exposes setWallet(address) and a connect-wallet event. Covers wiring the Solana Wallet Adapter (React), Phantom in vanilla JS, and displaying balances.
- [Widget Examples](https://docs.vulcx.xyz/widget/examples): Complete Vulcx vulcx-swap Web Component examples for HTML/CDN, React with Wallet Adapter, Vue 3, Next.js (App Router), and Svelte, plus a light-theme custom-accent example.

## API Reference

- [API Reference Overview](https://docs.vulcx.xyz/api-reference/introduction): Vulcx API reference overview. Base URL: https://api.vulcx.xyz. Currently supports Fogo chain. Covers the JSON response envelope ({success, data, error}), HTTP status codes (200, 400, 401, 403, 404, 429, 500), the auth requirement (every endpoint needs an API key except GET /health and GET /api/v1/tokens — see /get-started/authentication), and the endpoint table with an auth-required column linking to GET /api/v1/quote, POST /api/v1/swap, POST /api/v1/instructions, WS /api/v1/stream, GET /api/v1/price, GET /api/v1/tokens, and GET /health.
- [Rate Limits](https://docs.vulcx.xyz/api-reference/rate-limits): Vulcx API rate limits. Default: 60 requests/minute, 10 requests/second burst. Covers the 429 response format, exponential backoff retry strategy with cURL, TypeScript, and Python examples, and best practices (cache quotes, batch wisely, use instructions endpoint).
- [Error Codes](https://docs.vulcx.xyz/api-reference/errors): Complete Vulcx error reference. Covers HTTP status codes, per-endpoint error messages (quote: invalid inputMint, no route found, insufficient liquidity; swap: invalid user wallet, simulation failed; instructions: missing pool data), SimulationResult fields (insufficientFunds, slippageExceeded), and on-chain errors (SlippageExceeded, BlockhashExpired, InvalidAccountData) with recovery actions.
- [Stream Quotes API](https://docs.vulcx.xyz/api-reference/stream): Protocol reference for the Vulcx WebSocket quote stream at wss://api.vulcx.xyz/api/v1/stream on Fogo. Requires an API key as a ?key=vulcx_... query parameter (not a header — browsers can't set custom headers on a WS handshake); connecting without one fails the handshake. Raw JSON-over-WebSocket (not socket.io). Clients send subscribe/unsubscribe ops with a pairs array ({in, out, amount, exactIn}); the server replies with an immediate first quote, an ack ({type:subscribed|unsubscribed|error, count}), and thereafter pushes a quote message ({type:quote, in, out, amount, amountOut, priceImpactBps, hops, slot}) only when the quote materially changes. Limits: 256 subscriptions per connection, change-only pushes, ~50ms debounce.
- [Get Price API](https://docs.vulcx.xyz/api-reference/price): Reference for GET /api/v1/price on the Vulcx API (Fogo). Returns the spot/mid USD price for a token mint, derived from live on-chain pool state (not an external feed). Anchored on stablecoins = $1 and the native FOGO token priced from the deepest native↔stable pool; every other token is priced from its deepest anchor-paired pool. Single lookup GET /api/v1/price/:mint and batch GET /api/v1/price?mints=a,b,c (max 100). Response fields: mint, price, slot, updatedAt. price is 0 when unknown (no anchor-paired pool yet, or decimals pending). This is a spot oracle distinct from GET /api/v1/quote, which is size- and slippage-aware.

## Guides

- [Executing Swaps](https://docs.vulcx.xyz/guides/executing-swaps): Step-by-step guide to executing a token swap on Vulcx on Fogo. Covers the full flow: GET /api/v1/quote (with cURL + TypeScript + Python), POST /api/v1/swap to build the transaction, then sign with @solana/web3.js VersionedTransaction, sendRawTransaction, and confirmTransaction. Includes complete runnable code examples.
- [Handling Errors](https://docs.vulcx.xyz/guides/handling-errors): Error handling guide for the Vulcx API on Fogo. Covers the error response format, common HTTP errors (400, 404, 429, 500) with causes and fixes, simulation error fields (insufficientFunds, slippageExceeded), on-chain transaction errors (SlippageExceeded, BlockhashExpired), and retry strategy with cURL, TypeScript, and Python examples for each error category.
- [Embedding Swap in a dApp](https://docs.vulcx.xyz/guides/embedding-swap): Complete guide to embedding Vulcx swap in a React web app on Fogo. Includes TypeScript functions for getQuote and buildSwapTransaction, an executeSwap function using @solana/wallet-adapter-react signTransaction, a full React SwapButton component example, error handling table for UI messages, and best practices (show price impact, refresh quotes, handle rate limits).
- [Self-Hosting](https://docs.vulcx.xyz/guides/self-hosting): Step-by-step deployment guide for the Vulcan (self-hosted) binary on Fogo. Prerequisites: FluxRPC key (fluxrpc.com?ref=VULCX) and community license key (license.vulcx.xyz). Deployment options: Docker Compose or raw binary (linux-amd64/arm64 from GitHub releases). Full env var reference: COMMUNITY_MODE=true, CHAIN=fogo, RPC_URL, YELLOWSTONE_URL, YELLOWSTONE_TOKEN, COMMUNITY_LICENSE_KEY, COMMUNITY_LICENSE_API, REFERRER_WALLET (optional — dApp builders only, not bot operators), ALLOWED_IPS, HTTP_PORT, LUT_AUTHORITY_KEY_FOGO (optional, holds private key — treat as secret). Nginx + SSL with certbot, referral fee setup, systemd unit for auto-restart. Fogo.

## AI

- [AI Integration](https://docs.vulcx.xyz/ai/overview): Overview of AI-friendly resources for Vulcx. Covers llms.txt (LLM-optimized site index for discovering relevant pages), skill.md (decision-tree playbook for AI agents to route intents to the correct API endpoints), and how to use these resources for automated swap integration.

## Updates

- [Changelog](https://docs.vulcx.xyz/updates/index): Vulcx API changelog. Tracks API updates, new features, breaking changes, and deprecations in reverse chronological order.