> ## 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 API reference — quote, swap & instructions

> Get started with the Vulcx API on Fogo: base URL, the {success, data, error} response envelope, status codes, authentication, and the full endpoint reference.

**Base URL**: `https://api.vulcx.xyz`

All swap endpoints are under `/api/v1`. The API currently operates on **Fogo**.

<Note>
  Every endpoint below requires an API key (`Authorization: Bearer vulcx_...`, or `?key=` for the
  WebSocket stream) **except** `GET /health` and `GET /api/v1/tokens`. See
  [Authentication](/get-started/authentication).
</Note>

## Response format

All responses use a consistent envelope:

**Success:**

```json theme={"theme":"github-dark"}
{
  "success": true,
  "data": { ... }
}
```

**Error:**

```json theme={"theme":"github-dark"}
{
  "success": false,
  "error": "error message describing what went wrong"
}
```

## HTTP status codes

| Code  | Meaning                                                    |
| ----- | ---------------------------------------------------------- |
| `200` | Success                                                    |
| `400` | Bad request: invalid parameters, missing required fields   |
| `401` | No API key was provided                                    |
| `403` | The API key is invalid, disabled, or revoked               |
| `404` | Not found: no route exists for the given token pair/amount |
| `429` | Rate limited: too many requests                            |
| `500` | Internal error: transaction build or simulation failed     |

## Endpoints

| Endpoint                                         | Method | Auth required | Description                                                      |
| ------------------------------------------------ | ------ | :-----------: | ---------------------------------------------------------------- |
| `GET https://api.vulcx.xyz/api/v1/quote`         | GET    |       ✅       | Get swap quote with routing details                              |
| `POST https://api.vulcx.xyz/api/v1/swap`         | POST   |       ✅       | Build unsigned swap transaction                                  |
| `POST https://api.vulcx.xyz/api/v1/instructions` | POST   |       ✅       | Get raw swap instructions                                        |
| `WS wss://api.vulcx.xyz/api/v1/stream`           | WS     |       ✅       | [Stream live quotes over WebSocket](/api-reference/stream/index) |
| `GET https://api.vulcx.xyz/api/v1/price/:mint`   | GET    |       ✅       | [Spot USD price for a token](/api-reference/price/index)         |
| `GET https://api.vulcx.xyz/api/v1/tokens`        | GET    |       —       | Curated list of well-known token mints                           |
| `GET https://api.vulcx.xyz/health`               | GET    |       —       | Service health check                                             |


## Related topics

- [SDK types reference](/sdk/types.md)
- [Get Instructions](/api-reference/instructions/index.md)
- [Rate Limits](/api-reference/rate-limits.md)
- [Vulcx architecture — how swaps are routed on Fogo](/get-started/architecture.md)
- [Error Codes](/api-reference/errors.md)