> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulcx.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Vulcx architecture — how swaps are routed on Fogo

> How Vulcx routes and executes swaps on Fogo: the API server, off-chain routing engine, and on-chain program, plus the /swap vs /instructions paths.

<Frame caption="Your app calls the Vulcx API, which finds the best-price route and returns an unsigned transaction; your wallet signs and submits it to Fogo.">
  <img src="https://mintcdn.com/argyros/r_t42XYOxJfxLnCX/images/architecture.png?fit=max&auto=format&n=r_t42XYOxJfxLnCX&q=85&s=4978421dc7cd88741f2b855537c254b3" alt="Vulcx system overview: the widget, SDK, and your app call the Vulcx API at api.vulcx.xyz over HTTPS (GET /quote, POST /swap). The API finds the best-price route across all pools and returns an unsigned transaction. Your wallet signs and submits it on-chain to Fogo, where liquidity comes from Vortex, Fluxbeam, Fogo.fun, and Moonit." width="3239" height="1340" data-path="images/architecture.png" />
</Frame>

## Data flow

```
Client                    Vulcx API                 Fogo
  │                           │                          │
  GET /quote                  │                          │
  ──────────────────────────> │                          │
                              │  find best route         │
  QuoteResponse               │  across all pools        │
  <────────────────────────── │                          │
                              │                          │
  POST /swap                  │                          │
  ──────────────────────────> │                          │
                              │  build transaction       │
  unsigned transaction        │                          │
  <────────────────────────── │                          │
                              │                          │
  sign + submit ────────────────────────────────────────>│
                              │                          │
  confirmation <─────────────────────────────────────────│
```

## Components

**API Server.** HTTP service that handles quote requests, builds swap transactions, and returns raw instructions. Stateless and horizontally scalable.

**Routing Engine.** Off-chain route search that evaluates routes across all supported DEXs on Fogo. Finds direct swaps, multi-hop paths (e.g., Token A → FOGO → USDC → Token B), and split routes across multiple pools.

**Supported DEXs.** Vortex (concentrated liquidity), Fluxbeam (AMM), Fogo.fun (bonding curves), and Moonit (bonding curves).

**On-chain Program.** Verifies and executes the swap instructions atomically. If any hop fails or slippage is exceeded, the entire transaction reverts.

## Three integration paths

| Path             | Endpoint                          | Use case                                                                                                                                                                                                      |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Transaction**  | `POST /api/v1/swap`               | Get a ready-to-sign transaction. Sign it and submit. Simplest integration.                                                                                                                                    |
| **Instructions** | `POST /api/v1/instructions`       | Get raw instructions to compose with your own transaction logic (e.g., adding custom instructions before/after the swap).                                                                                     |
| **CPI accounts** | `POST /api/v1/cpi/route-accounts` | Call the `route` instruction **on-chain** from another program via CPI, signed by your program's PDA. Makes a swap one atomic step inside your protocol. See [Composing Swaps On-Chain](/guides/onchain-cpi). |

The first two paths start with `GET /api/v1/quote` to find the best route. For prices that update in
real time, the API also exposes a WebSocket [quote stream](/docs/swap/stream-quotes) that pushes a new
quote whenever a pair's price changes.


## Related topics

- [Introduction to Vulcx — best-price swaps on Fogo](/get-started/introduction.md)
- [Vulcx FAQ — Fogo swaps, chains, fees & limits](/get-started/faq.md)
- [Swap routing — multi-hop best-price paths on Fogo](/concepts/routing.md)
- [Swap Overview](/docs/swap/overview.md)
- [AI Integration](/ai/overview.md)