> For the complete documentation index, see [llms.txt](https://docs.hipersnipe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hipersnipe.com/architecture/swap-engine.md).

# Swap engine and routing

## Overview

Swap execution flows through `swap.py` (high-level API) into `swap_engine/` (low-level builders) and provider-specific modules.

## Routing decision tree

```
Token mint detected
        │
        ▼
  Is Pump.fun bonding curve?
    │              │
   Yes             No
    │              │
    ▼              ▼
Pump direct    Jupiter aggregator
Lightning API  Raydium direct (when applicable)
Jupiter fallback Moonshot direct (launchpad)
               (+ Jito for MEV)
```

## Key modules

| File                                  | Role                                                |
| ------------------------------------- | --------------------------------------------------- |
| `swap.py`                             | `Swap` class: buy/sell entry, route racing, retries |
| `swap_engine/router.py`               | Orchestration, sell balance retry                   |
| `swap_engine/pump_direct.py`          | Native Pump.fun instructions                        |
| `swap_engine/dex_jupiter.py`          | Jupiter quote + swap build                          |
| `swap_engine/pump_api.py`             | PumpPortal Lightning                                |
| `swap_engine/jito.py`                 | Bundle submission                                   |
| `swap_engine/balance.py`              | Pre-sell balance verification                       |
| `swap_engine/fees.py`                 | Priority fee computation                            |
| `swap_engine/presigned_sell_cache.py` | Hot-path sell bullets                               |
| `swap_raydium.py`                     | Raydium AMM swap instructions                       |
| `swap_engine/moonshot_direct.py`      | Moonshot launchpad direct route                     |
| `swap_jupiter.py`                     | Jupiter SDK wrapper                                 |
| `swap_fallbacks.py`                   | Lightning + native + Jupiter fallback chain         |
| `swap_pumpfun.py`                     | Bonding curve math and instructions                 |

## Pump.fun buy: parallel route race

For bonding-curve tokens the bot races multiple routes concurrently:

1. PumpPortal Lightning
2. Native Pump.fun direct
3. Jupiter fallback

First successful on-chain signature wins. Reduces failed buys during congestion.

## Execution modes

Users select **Standard**, **Fast**, or **Turbo** per token. This maps to Jito tip levels via `shared.py`:

| Mode     | Typical use                          |
| -------- | ------------------------------------ |
| Standard | Lower tip, public RPC for some sells |
| Fast     | Jito bundle, moderate tip            |
| Turbo    | Jito bundle, highest tip             |

## MEV protection

* **Buys:** Jito bundles when mode is Fast/Turbo
* **Sells:** Standard may use public RPC; Fast/Turbo use Jito
* Tip amounts derived from user priority fee settings

## Slippage

Per-user settings stored in DB:

* `slippage_turbo` / `slippage_mev` — Raydium/Jupiter tokens
* `slippage_bonding` — Pump.fun bonding curve (higher defaults)

Bonding tokens use presets **15% / 25% / 50%** in the UI.

## Post-trade verification

After send, the bot optionally confirms on-chain. If indexing lags, success may be assumed to prevent double-spend retries. Pump slippage errors trigger automatic retry with increased slippage.

## Blockhash cache

`utils/blockhash_cache.py` maintains a fresh blockhash with RPC rotation on 429/timeouts—critical for sub-second execution paths.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hipersnipe.com/architecture/swap-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.