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

# 自托管 Raptor Solana 兑换 API

> 从 GitHub 下载免费的 Raptor 二进制文件，在自己的服务器上运行同样的兑换 API。无需 API 密钥，不限请求数，实例数量不限。

Raptor 也是一个可以在自己服务器上运行的单一二进制文件。它和 `raptor.solanatracker.io` 托管服务使用相同的路由引擎，以及相同的 [HTTP](https://docs.solanatracker.io/cn/raptor/http/get-swap-quote.md) 和 [WebSocket](#websocket-streaming) API。

* **目前免费。** 二进制文件不收费，也不需要 API 密钥或许可证密钥，下载后直接运行。
* **没有限制。** 想运行多少实例都可以，能处理多少请求只取决于你的硬件。
* **可以转售。** 在前面加上你自己的 API，收取访问费用，或添加你自己的[平台费](https://docs.solanatracker.io/cn/raptor/overview.md#platform-fees)。

> [card] [从 GitHub 下载](https://github.com/solanatracker/raptor-binary/releases/latest)
>
> 适用于 Linux 和 macOS 的最新版本，附校验和与发布说明。

> [card] [报告问题](https://github.com/solanatracker/raptor-binary/issues)
>
> Bug 和功能请求提交到 GitHub 仓库，使用问题请到 Discord 咨询。

> [!NOTE]
>
> 使用 Raptor 不一定要自托管。[托管 API](https://docs.solanatracker.io/cn/raptor/overview.md) 目前同样免费，无需任何配置。想要独立的容量、自己的基础设施，或不依赖共享服务时，再选择自托管。

## 二进制文件的功能

开箱即用时，二进制文件提供报价和兑换交易构建。另外四项功能默认关闭，需要手动开启。

| 功能 | 端点 | 默认 | 开启方式 |
| - | - | - | - |
| 在所有[支持的 DEX](https://docs.solanatracker.io/cn/raptor/overview.md#supported-dexs) 上报价，支持多跳、拆单和 [JIT](https://docs.solanatracker.io/cn/raptor/overview.md#jit-routing) 路由 | `GET /quote` | 开启 | |
| 构建兑换交易，支持优先费、小费和平台费 | `POST /swap`、`POST /swap-instructions` | 开启 | |
| 健康和就绪检查 | `GET /health`、`GET /ready` | 开启 | |
| [实时报价流](#websocket-streaming) | `/stream`、`/stream/swap` | 关闭 | `--enable-websocket` |
| [发送和追踪交易](#send-and-track-transactions) | `POST /send-transaction`、`GET /transaction/{signature}` | 关闭 | `--enable-yellowstone-jet` |
| [一次调用完成报价和构建](#quote-and-swap-in-one-call) | `POST /quote-and-swap` | 关闭 | `--enable-quote-and-swap` |
| [套利报价](https://docs.solanatracker.io/cn/raptor/overview.md#arbitrage)，输入和输出 mint 相同 | `GET /quote` | 关闭 | `--enable-arbitrage` |

请求已关闭的端点会返回 `404`。

Raptor 通过 Yellowstone gRPC 流式接收账户更新来保持池状态最新，因此启动后只使用很少的 RPC。

Yellowstone gRPC
流式推送池账户更新

Solana RPC
启动时读取与区块哈希

池索引
启动时下载一次

你的服务器
raptor
所有池都保存在内存中，报价无需等待 RPC

quoteswapstreamsend

你的应用
端口 8080 上的 HTTP 与 WebSocket

## 系统要求

* **一台 Linux 或 macOS 服务器。**
  * Linux：x86-64，glibc 2.30 或更新版本，例如 Ubuntu 20.04+、Debian 11+ 或 RHEL 9+。
  * macOS：Apple Silicon 或 Intel。
* **一个 Solana RPC 端点**，通过 `RPC_URL` 设置。
* **一个 Yellowstone gRPC 端点**，通过 `YELLOWSTONE_ENDPOINT` 设置；如果服务商要求，还需设置 `YELLOWSTONE_TOKEN`。没有它 Raptor 无法启动。
* **一个可写的池缓存目录。** 默认是二进制文件旁边的 `.r_cache`。设置 `RAPTOR_POOL_DATA_DIR` 可使用其他目录。
* **出站 HTTPS。** 启动时，Raptor 会从 Solana Tracker 下载当前的池索引，之后通过 Yellowstone 保持更新。

## 安装

**1. 选择适合服务器的文件**

每个[发布版本](https://github.com/solanatracker/raptor-binary/releases/latest)都为每个平台提供一个 zip 文件，命名为 `raptor-<version>-<platform>.zip`。

| 服务器 | 文件名中的平台 |
| - | - |
| Linux，x86-64 | `x86_64-unknown-linux-gnu` |
| macOS，Apple Silicon | `aarch64-apple-darwin` |
| macOS，Intel | `x86_64-apple-darwin` |

**2. 下载并校验**

以下命令会下载最新版本，并用发布的 `checksums.txt` 校验。

```bash Linux theme={null}
VERSION=$(curl -s https://api.github.com/repos/solanatracker/raptor-binary/releases/latest \
  | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
PLATFORM=x86_64-unknown-linux-gnu
BASE=https://github.com/solanatracker/raptor-binary/releases/download/$VERSION

curl -LO "$BASE/raptor-$VERSION-$PLATFORM.zip"
curl -LO "$BASE/checksums.txt"
sha256sum --check --ignore-missing checksums.txt
unzip "raptor-$VERSION-$PLATFORM.zip"
```

```bash macOS theme={null}
VERSION=$(curl -s https://api.github.com/repos/solanatracker/raptor-binary/releases/latest \
  | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
PLATFORM=aarch64-apple-darwin   # x86_64-apple-darwin on Intel Macs
BASE=https://github.com/solanatracker/raptor-binary/releases/download/$VERSION

curl -LO "$BASE/raptor-$VERSION-$PLATFORM.zip"
curl -LO "$BASE/checksums.txt"
shasum -a 256 --check --ignore-missing checksums.txt
unzip "raptor-$VERSION-$PLATFORM.zip"
```

校验通过时输出 `raptor-<version>-<platform>.zip: OK`。如果输出其他内容，请删除 zip 文件并重新下载。

把 `raptor.sig` 和 `raptor` 放在同一目录。二进制文件用它来确认自身未被修改。

**3. 确认可以运行**

```bash theme={null}
./raptor --version
```

如果 macOS 阻止运行从浏览器下载的二进制文件，用 `xattr -d com.apple.quarantine raptor` 清除隔离标记。

## 运行

设置端点并启动服务器。

```bash theme={null}
export RPC_URL="https://your-rpc.example.com"
export YELLOWSTONE_ENDPOINT="https://your-grpc.example.com"
export YELLOWSTONE_TOKEN="your-token"

./raptor
```

Raptor 监听 `0.0.0.0:8080`。设置 `BIND_ADDR` 可以修改，例如 `BIND_ADDR=127.0.0.1:9000`。

开启除套利外的所有可选功能：

```bash theme={null}
./raptor --enable-websocket --enable-yellowstone-jet --enable-quote-and-swap
```

### 等待服务就绪

Raptor 要先索引池才能路由。索引完成前，`/quote` 返回 `503` 和 `Server warming up`。`/ready` 在 Raptor 可以提供报价后返回 `200`，在此之前返回 `503`：

```bash theme={null}
curl http://localhost:8080/ready
```

```json theme={null}
{ "ready": true, "pool_count": 812345, "indexed_count": 812345, "indexing_in_progress": false }
```

`/health` 在服务器启动后立即返回 `OK`，即使仍在索引。把负载均衡器的健康检查指向 `/ready`，这样实例只有在可以报价时才会接收流量。

### 发起第一次报价

```bash theme={null}
curl "http://localhost:8080/quote?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=100000000&slippageBps=50"
```

把 `https://raptor.solanatracker.io` 替换为你的服务器地址后，[概览](https://docs.solanatracker.io/cn/raptor/overview.md)中的所有示例都可以用于你的实例。

## 可选功能

每个标志都有对应的环境变量。开关类变量设为 `1`、`true`、`yes` 或 `on` 都会开启功能。

### WebSocket 流式传输

```bash theme={null}
./raptor --enable-websocket      # or ENABLE_WEBSOCKET=true
```

客户端连接 `ws://your-server:8080/stream` 获取实时报价，或连接 `/stream/swap` 获取附带待签名交易的报价。最佳路由变化时 Raptor 会推送更新，客户端无需轮询。消息格式见 [WebSocket](https://docs.solanatracker.io/cn/raptor/overview.md#websocket)。

### 发送和追踪交易

```bash theme={null}
./raptor --enable-yellowstone-jet      # or ENABLE_YELLOWSTONE_JET=true
```

这会开启 `POST /send-transaction` 和 `GET /transaction/{signature}`。Raptor 通过 QUIC 使用 [Yellowstone Jet](https://github.com/rpcpool/yellowstone-jet) 把已签名交易直接发送给即将出块的 leader，并持续重发，直到交易上链或过期。请求和响应格式见[发送和追踪交易](https://docs.solanatracker.io/cn/raptor/transactions.md)。

| 标志 | 变量 | 默认值 | 作用 |
| - | - | - | - |
| `--jet-identity <PATH>` | `JET_IDENTITY` | 无 | 用于发送的密钥对文件。质押验证者身份可以从 leader 获得按质押加权的优先级。 |
| `--jet-identities <N>` | `JET_NUM_IDENTITIES` | `4` | 未设置 `--jet-identity` 时，Raptor 使用这么多随机身份发送。 |
| `--tx-cache-ttl <SECS>` | `TX_CACHE_TTL_SECS` | `30` | 已完成交易的状态可查询多长时间 |
| `--tx-pending-expiry <SECS>` | `TX_PENDING_EXPIRY_SECS` | `120` | 未上链的交易多久后标记为 `expired` |

服务器需要能通过出站 UDP 访问 Solana 验证者，以使用 QUIC。

### 一次调用完成报价和兑换

```bash theme={null}
./raptor --enable-quote-and-swap      # or -s, or ENABLE_QUOTE_AND_SWAP=true
```

这会开启 `POST /quote-and-swap`，在一个请求中完成报价和交易构建。对不需要先展示报价的机器人和后端，可以省去一次往返。参见[一次请求完成报价和兑换](https://docs.solanatracker.io/cn/raptor/http/quote-and-swap-in-one-request.md)。

### 套利

```bash theme={null}
./raptor --enable-arbitrage      # or ENABLE_ARBITRAGE=true
```

这会让 `/quote` 接受相同的 mint 作为输入和输出，例如 SOL 换 SOL。Raptor 随后会寻找一条经过多个池、换回数量多于投入的循环，详见[套利](https://docs.solanatracker.io/cn/raptor/overview.md#arbitrage)。

不开启此标志时，相同 mint 的报价返回 `400` 和 `Circular arbitrage is disabled`。

## 限制 Raptor 的路由范围

默认情况下，Raptor 会经过所有支持的 DEX 和池进行路由。下面这些过滤器在整个实例范围内缩小路由范围。DEX 过滤器还会减少 Raptor 从 Yellowstone 接收的数据流，从而节省内存和带宽。调用方还可以在每个请求上通过 [`dexes` 和 `pools`](https://docs.solanatracker.io/cn/raptor/overview#limit-the-route) 进一步收窄路由。

| 标志 | 变量 | 作用 |
| - | - | - |
| `--include-dexes <DEXES>` | `INCLUDE_DEXES` | 只使用这些 DEX，以逗号分隔 |
| `--exclude-dexes <DEXES>` | `EXCLUDE_DEXES` | 使用除这些以外的所有 DEX，以逗号分隔 |
| `--include-mints-file <PATH>` | `INCLUDE_MINTS_FILE` | 只使用至少持有此文件中一个 mint 的池 |
| `--include-pools-file <PATH>` | `INCLUDE_POOLS_FILE` | 只使用此文件中列出的池 |

DEX 名称不区分大小写，并接受多种写法，因此 `raydium-clmm`、`raydium_clmm` 和 `"Raydium CLMM"` 都指同一个 DEX。`raydium` 和 `meteora` 匹配该 DEX 的所有池类型，`orca` 匹配 Whirlpool。包含列表和排除列表只需设置其中一个；两者都设置时，以包含列表为准。

```bash theme={null}
./raptor --include-dexes raydium,meteora,whirlpool,pumpswap
```

白名单文件每行一个地址。Raptor 会忽略空行，`#` 表示注释开始。组合使用多个过滤器时，池必须全部通过。

```text theme={null}
# mints.txt
So11111111111111111111111111111111111111112
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
```

```bash theme={null}
./raptor --include-mints-file mints.txt
```

## 运行多个实例

每个实例独立运行，使用自己的 Yellowstone 流，因此可以按需在负载均衡器后面放任意数量的实例。

每个报价都带有签名的 `quoteId`。默认情况下，`/swap` 只接受同一实例生成的报价。如果负载均衡器可能把客户端的 `/quote` 和 `/swap` 发往不同实例，请为所有实例设置相同的密钥：

```bash theme={null}
export RAPTOR_QUOTE_SECRET="a-random-string-of-at-least-32-characters"
```

共享该密钥的实例会互相接受对方的报价。用 `openssl rand -hex 32` 生成一个密钥，并妥善保管。

## 内存和性能

| 标志 | 变量 | 默认值 | 作用 |
| - | - | - | - |
| `--workers <N>` | `WORKER_THREADS` | CPU 核心数 | 工作线程数 |
| `--low-memory` | `LOW_MEMORY_MODE` | 关闭 | 使用有界缓存，并把联合曲线池放在磁盘而非内存中 |
| `--memory-limit <MB>` | `MEMORY_LIMIT_MB` | 系统内存的 80% | 低内存模式的内存预算 |
| `--rpc-rate-limit <N>` | `RPC_RATE_LIMIT` | 不限 | 每秒最多 RPC 请求数，用于不超过服务商的限制 |
| | `RAPTOR_POOL_DATA_DIR` | 二进制文件旁的 `.r_cache` | 磁盘池缓存目录 |

小型服务器请使用 `--low-memory`。Pump.fun 这类发射台有数百万个联合曲线池，低内存模式会把它们放在磁盘上。

### 启动选项

| 标志 | 变量 | 作用 |
| - | - | - |
| `--skip-pool-indexer-wait` | `SKIP_POOL_INDEXER_WAIT` | 在池索引同步完成前就开始服务。早期报价可能遗漏部分池。 |
| `--no-pool-indexer` | `NO_POOL_INDEXER` | 不从 Solana Tracker 下载池索引。Raptor 只通过 Yellowstone 发现池，覆盖所有池需要的时间会长得多。 |

## 作为服务运行

> [tab] systemd
>
> 把 `raptor` 和 `raptor.sig` 放到 `/opt/raptor`，然后创建 `/etc/systemd/system/raptor.service`：
>
> ```ini theme={null}
> [Unit]
> Description=Raptor swap API
> After=network-online.target
> Wants=network-online.target
>
> [Service]
> WorkingDirectory=/opt/raptor
> ExecStart=/opt/raptor/raptor --enable-websocket --enable-yellowstone-jet
> EnvironmentFile=/opt/raptor/raptor.env
> Restart=always
> RestartSec=5
> LimitNOFILE=1048576
>
> [Install]
> WantedBy=multi-user.target
> ```
>
> 把配置写入 `/opt/raptor/raptor.env`，每行一个 `NAME=value`：
>
> ```bash theme={null}
> RPC_URL=https://your-rpc.example.com
> YELLOWSTONE_ENDPOINT=https://your-grpc.example.com
> YELLOWSTONE_TOKEN=your-token
> RAPTOR_QUOTE_SECRET=your-shared-secret
> ```
>
> 启动并跟踪日志：
>
> ```bash theme={null}
> sudo systemctl daemon-reload
> sudo systemctl enable --now raptor
> journalctl -u raptor -f
> ```

> [tab] Docker
>
> 把 Linux 版本解压到这个 `Dockerfile` 旁边：
>
> ```dockerfile theme={null}
> FROM debian:bookworm-slim
> RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
>     && rm -rf /var/lib/apt/lists/*
> WORKDIR /opt/raptor
> COPY raptor raptor.sig ./
> ENV RAPTOR_POOL_DATA_DIR=/data
> VOLUME /data
> EXPOSE 8080
> ENTRYPOINT ["/opt/raptor/raptor"]
> ```
>
> ```bash theme={null}
> docker build -t raptor .
> docker run -d --name raptor -p 8080:8080 -v raptor-data:/data \
>   -e RPC_URL=https://your-rpc.example.com \
>   -e YELLOWSTONE_ENDPOINT=https://your-grpc.example.com \
>   -e YELLOWSTONE_TOKEN=your-token \
>   raptor --enable-websocket --enable-yellowstone-jet
> ```
>
> 数据卷会在替换容器时保留池缓存。如果 Docker 网络屏蔽了出站 UDP，请使用 `--network host` 运行，让 `--enable-yellowstone-jet` 能访问验证者。

## 更新

用同样的方式下载新版本，替换 `raptor` 和 `raptor.sig`，然后重启。不同版本之间保留池缓存目录。发布说明见 [GitHub](https://github.com/solanatracker/raptor-binary/releases) 和[最近更新](https://docs.solanatracker.io/cn/raptor/recent-changes.md)。

要无停机更新多个实例，为它们设置相同的 `RAPTOR_QUOTE_SECRET`，然后逐个重启。每个实例在 `/ready` 返回 `200` 后重新加入负载均衡器。

## 配置参考

标志的值两种写法都可以：`--workers 8` 或 `--workers=8`。

| 标志 | 变量 | 默认值 | 描述 |
| - | - | - | - |
| | `RPC_URL` | 必填 | Solana RPC 端点 |
| | `YELLOWSTONE_ENDPOINT` | 必填 | Yellowstone gRPC 端点 |
| | `YELLOWSTONE_TOKEN` | 无 | Yellowstone 认证令牌 |
| | `BIND_ADDR` | `0.0.0.0:8080` | 监听的地址和端口 |
| | `RAPTOR_QUOTE_SECRET` | 无 | 至少 32 个字符的共享密钥，让实例互相接受对方的报价 |
| | `RAPTOR_POOL_DATA_DIR` | 二进制文件旁的 `.r_cache` | 池缓存目录 |
| `--enable-websocket` | `ENABLE_WEBSOCKET` | 关闭 | 提供 `/stream` 和 `/stream/swap` |
| `--enable-yellowstone-jet` | `ENABLE_YELLOWSTONE_JET` | 关闭 | 提供 `/send-transaction` 和 `/transaction/{signature}` |
| `-s`, `--enable-quote-and-swap` | `ENABLE_QUOTE_AND_SWAP` | 关闭 | 提供 `/quote-and-swap` |
| `--enable-arbitrage` | `ENABLE_ARBITRAGE` | 关闭 | 允许相同 mint 的套利报价 |
| `--include-dexes <DEXES>` | `INCLUDE_DEXES` | 全部 | 只使用这些 DEX |
| `--exclude-dexes <DEXES>` | `EXCLUDE_DEXES` | 无 | 不使用这些 DEX |
| `--include-mints-file <PATH>` | `INCLUDE_MINTS_FILE` | 无 | 只使用持有所列 mint 的池 |
| `--include-pools-file <PATH>` | `INCLUDE_POOLS_FILE` | 无 | 只使用所列的池 |
| `--jet-identity <PATH>` | `JET_IDENTITY` | 无 | 用于发送交易的密钥对 |
| `--jet-identities <N>` | `JET_NUM_IDENTITIES` | `4` | 未设置密钥对时使用的随机发送身份数量 |
| `--tx-cache-ttl <SECS>` | `TX_CACHE_TTL_SECS` | `30` | 已发送交易可查询多长时间 |
| `--tx-pending-expiry <SECS>` | `TX_PENDING_EXPIRY_SECS` | `120` | 待处理交易多久后标记为 `expired` |
| `--workers <N>` | `WORKER_THREADS` | CPU 核心数 | 工作线程数 |
| `--low-memory` | `LOW_MEMORY_MODE` | 关闭 | 有界缓存，联合曲线池存放在磁盘上 |
| `--memory-limit <MB>` | `MEMORY_LIMIT_MB` | 内存的 80% | 低内存模式的内存预算 |
| `--rpc-rate-limit <N>` | `RPC_RATE_LIMIT` | 不限 | 每秒最多 RPC 请求数 |
| `--skip-pool-indexer-wait` | `SKIP_POOL_INDEXER_WAIT` | 关闭 | 在池索引同步完成前就开始服务 |
| `--no-pool-indexer` | `NO_POOL_INDEXER` | 关闭 | 只通过 Yellowstone 发现池 |
| `-h`, `--help` | | | 显示帮助 |
| `-v`, `--version` | | | 显示版本 |

## 故障排查

> [accordion] Raptor 退出并提示“RPC\_URL environment variable is required”
>
> 在运行 Raptor 的环境中设置 `RPC_URL` 和 `YELLOWSTONE_ENDPOINT`。使用 systemd 时，把它们写入 `EnvironmentFile`，因为 shell 中导出的变量不会传给服务。

> [accordion] /quote 返回 503 和“Server warming up”
>
> Raptor 还在索引池。等 `/ready` 返回 `200`。如果一直不返回，检查日志中是否有 Yellowstone 连接错误，并确认服务器可以发起出站 HTTPS 请求。

> [accordion] /stream、/send-transaction 或 /quote-and-swap 返回 404
>
> 该功能未开启。启动 Raptor 时加上 `--enable-websocket`、`--enable-yellowstone-jet` 或 `--enable-quote-and-swap`。

> [accordion] /swap 拒绝其他实例生成的报价
>
> 在所有实例上设置相同的 `RAPTOR_QUOTE_SECRET`，或把每个客户端的 `/quote` 和 `/swap` 发往同一个实例。

> [accordion] Linux 报错“GLIBC\_2.30 not found”
>
> 二进制文件需要 glibc 2.30 或更新版本。请使用 Ubuntu 20.04+、Debian 11+ 或更新的发行版，或运行上面的 Docker 镜像。

> [accordion] RPC 服务商对 Raptor 限流
>
> 把 `--rpc-rate-limit` 设为低于套餐的每秒请求数。Raptor 的 RPC 调用大多发生在启动时，之后主要从 Yellowstone 读取数据。

## 常见问题

> [accordion] 二进制文件需要 API 密钥或许可证吗？
>
> 不需要。二进制文件目前免费：下载后直接运行。没有密钥，也没有请求限制。

> [accordion] 可以转售我的实例的访问权限吗？
>
> 可以。你可以在自己的 API 后面运行它，收取访问费用，并通过 `feeAccount` 和 `feeBps` 添加自己的平台费。

> [accordion] 它能替代 Metis 二进制文件吗？
>
> 可以。Raptor 的角色相同：一个自托管的聚合器，负责报价和构建兑换交易。它不需要二进制密钥，实例数量也不限。

> [accordion] 源代码是否公开？
>
> 不公开。Raptor 是闭源软件，[GitHub 仓库](https://github.com/solanatracker/raptor-binary)只用于托管发布版本。Bug 和功能请求可以在那里提交 issue。

> [accordion] 我的实例发起的兑换使用同一个链上程序吗？
>
> 是的。每个实例构建的交易都使用 Raptor 程序 `RaptorD5ojtsqDDtJeRsunPLg6GvLYNnwKJWxYE4m87`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.