# GMGN Solana 交易 API 集成指南

**作者：吉祥法师**

## 一、API 概述与访问权限

GMGN 为专业交易者提供了基于 Solana 区块链的高速交易 API 接口，支持 SOL、BSC、Base 和 ETH 等多条链上的交易操作。该 API 的设计目标是为量化交易策略提供低延迟、高效率的交易执行通道，使开发者能够以编程方式完成代币兑换、流动性管理等复杂操作。

### 1.1 访问权限申请

GMGN 交易 API 并非完全开放，而是采用基于交易量的权限授予机制。申请者需要在 GMGN 平台上保持足够的交易活跃度，通过审核后方可使用。具体申请流程如下：

- **申请途径**：通过填写官方 Google 表单提交申请（https://forms.gle/CWABDLRe8twvygvy5）
- **审核周期**：提交申请后，GMGN 团队将在 24 小时内完成审核
- **结果通知**：审核通过后，API Key 将通过电子邮件发送至申请人邮箱；若未通过审核，则不会收到任何通知
- **权限标准**：GMGN 会根据申请人在平台上的累计交易量进行综合评估，交易活跃度越高，获得 API 权限的可能性越大

### 1.2 API 认证机制

获得 API Key 后，开发者需要在每次 API 请求的 HTTP 头部（Header）中包含该密钥以完成身份验证。具体配置如下：

- **Header 名称**：`x-route-key`
- **请求频率限制**：每个 API Key 的调用频率限制为每 5 秒一次

这种认证机制确保了 API 的调用安全性和稳定性，同时也防止了滥用行为。开发者应在代码中妥善管理和存储 API Key，避免泄露。

## 二、核心 API 功能详解

### 2.1 路由查询接口（Get Swap Route）

路由查询是交易流程的第一步，该接口负责计算最佳兑换路径并生成未签名的交易数据。同时，该接口原生支持 JITO 抗 MEV（最大可提取价值）保护功能，有效防止交易被机器人抢先交易。

#### 接口基本信息

- **请求方式**：GET
- **接口地址**：`https://gmgn.ai/defi/router/v1/sol/tx/get_swap_route`

#### 输入参数说明

| 参数名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `token_in_address` | string | 是 | 支付代币的合约地址，例如 Wrapped SOL 地址 `So11111111111111111111111111111111111111112` |
| `token_out_address` | string | 是 | 目标代币的合约地址 |
| `in_amount` | string | 是 | 兑换数量，单位为 lamports（1 SOL = 10^9 lamports），例如 `100000000` 表示 0.1 SOL |
| `from_address` | string | 是 | 发起交易的钱包地址 |
| `slippage` | float | 是 | 滑点容忍度百分比，例如 `10` 表示允许 10% 的滑点 |
| `swap_mode` | string | 否 | 兑换模式：`ExactIn`（精确输入）或 `ExactOut`（精确输出），默认为 `ExactIn` |
| `fee` | float | 否 | 网络优先费及 RPC 节点小费，单位为 SOL。例如 `0.006`，GMGN 会自动分配节点小费和网络优先费。启用 JITO 抗 MEV 时，该值需至少为 `0.002` |
| `is_anti_mev` | bool | 否 | 是否启用 JITO 抗 MEV 保护，设为 `true` 时启用 |
| `partner` | string | 否 | 合作方来源标识（可选） |

#### 响应参数详解

接口返回的数据结构包含两个核心部分：`quote`（报价信息）和 `raw_tx`（原始交易数据）。

**quote 字段说明：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `inputMint` | string | 输入代币地址 |
| `inAmount` | string | 输入代币数量（lamports） |
| `outputMint` | string | 输出代币地址 |
| `outAmount` | string | 预期输出代币数量（lamports） |
| `otherAmountThreshold` | string | 考虑滑点后的最小输出数量（lamports） |
| `swapMode` | string | 兑换模式（ExactIn/ExactOut） |
| `slippageBps` | int | 滑点基点值，以 10000 为分母 |
| `platformFee` | string/null | 平台费用，无则返回 null |
| `priceImpactPct` | string | 价格影响百分比 |
| `routePlan` | Array | 路由计划，包含具体的兑换路径步骤 |
| `contextSlot` | int | 当前 Solana 网络槽位号 |
| `timeTaken` | float | 路由计算耗时（秒） |

**raw_tx 字段说明：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `swapTransaction` | string | Base64 编码的未签名交易数据 |
| `lastValidBlockHeight` | int | 交易创建时的区块高度 |
| `recentBlockhash` | string | 最近的区块哈希值 |
| `prioritizationFeeLamports` | int | 建议的优先费（lamports） |

### 2.2 交易提交接口（Send Transaction）

在获取路由信息并完成本地签名后，开发者需要将签名后的交易提交至 GMGN 的交易代理服务。

#### 接口基本信息

- **请求方式**：POST
- **接口地址**：`https://gmgn.ai/txproxy/v1/send_transaction`

#### 请求参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `chain` | string | 区块链类型，目前仅支持 `"sol"` |
| `signedTx` | string | 签名后的交易数据（Base64 编码） |
| `isAntiMev` | bool | 是否使用 JITO 抗 MEV 提交（可选） |

#### 响应参数

```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "hash": "交易哈希值",
        "resArr": [
            {
                "hash": "交易哈希值",
                "err": null
            }
        ]
    }
}
```

### 2.3 交易状态查询接口

交易提交后，可以通过状态查询接口追踪交易的执行状态。

#### 接口基本信息

- **请求方式**：GET
- **接口地址**：`https://gmgn.ai/defi/router/v1/sol/tx/get_transaction_status`

#### 输入参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `hash` | string | 交易提交后返回的交易哈希值 |
| `last_valid_height` | int | 交易创建时的区块高度 |

#### 响应字段说明

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `code` | int | 状态码，0 表示成功 |
| `msg` | string | 状态描述 |
| `data.success` | bool | 交易是否成功上链 |
| `data.failed` | bool | 交易是否上链但执行失败 |
| `data.expired` | bool | 交易是否已过期 |

**状态判断逻辑：**
- `success=true`：交易已成功写入区块链
- `expired=true` 且 `success=false`：交易已过期，需要重新提交（通常约 60 秒后过期）
- `failed=true`：交易已上链但执行失败

## 三、完整交易流程示例

以下是使用 JavaScript 实现完整交易流程的示例代码，涵盖从路由查询到交易状态追踪的全过程。

### 3.1 环境准备

```javascript
import { Wallet } from '@project-serum/anchor';
import { Connection, Keypair, VersionedTransaction, LAMPORTS_PER_SOL } from '@solana/web3.js';
import bs58 from 'bs58';
import fetch from 'node-fetch';
import sleep from './util/sleep.js';
```

### 3.2 参数配置

```javascript
// 交易参数配置
const inputToken = 'So11111111111111111111111111111111111111112';  // Wrapped SOL
const outputToken = '7EYnhQoR9YM3N7UoaKRoA44Uy8JeaZV3qyouov87awMs'; // 目标代币
const amount = '50000000';  // 0.05 SOL
const fromAddress = '2kpJ5QRh16aRQ4oLZ5LnucHFDAZtEFz6omqWWMzDSNrx';
const slippage = 0.5;  // 0.5% 滑点
const API_HOST = 'https://gmgn.ai';
```

### 3.3 核心交易逻辑

```javascript
async function main() {
    // 初始化钱包（使用 Phantom 钱包可跳过此步骤）
    const wallet = new Wallet(Keypair.fromSecretKey(bs58.decode(process.env.PRIVATE_KEY || '')));
    console.log(`钱包地址: ${wallet.publicKey.toString()}`);

    // Step 1: 获取报价和未签名交易
    const quoteUrl = `${API_HOST}/defi/router/v1/sol/tx/get_swap_route?token_in_address=${inputToken}&token_out_address=${outputToken}&in_amount=${amount}&from_address=${fromAddress}&slippage=${slippage}`;
    let route = await fetch(quoteUrl);
    route = await route.json();
    console.log('路由信息:', route);

    // Step 2: 签名交易
    const swapTransactionBuf = Buffer.from(route.data.raw_tx.swapTransaction, 'base64');
    const transaction = VersionedTransaction.deserialize(swapTransactionBuf);
    transaction.sign([wallet.payer]);
    const signedTx = Buffer.from(transaction.serialize()).toString('base64');
    console.log('签名交易:', signedTx);

    // Step 3: 提交交易
    let res = await fetch(`${API_HOST}/txproxy/v1/send_transaction`, {
        method: 'POST',
        headers: {'content-type': 'application/json'},
        body: JSON.stringify({
            "chain": "sol",
            "signedTx": signedTx
        })
    });
    res = await res.json();
    console.log('提交结果:', res);

    // Step 4: 持续查询交易状态
    while (true) {
        const hash = res.data.hash;
        const lastValidBlockHeight = route.data.raw_tx.lastValidBlockHeight;
        const statusUrl = `${API_HOST}/defi/router/v1/sol/tx/get_transaction_status?hash=${hash}&last_valid_height=${lastValidBlockHeight}`;
        let status = await fetch(statusUrl);
        status = await status.json();
        console.log('交易状态:', status);

        // 交易成功或过期时退出循环
        if (status && (status.data.success === true || status.data.expired === true)) break;
        await sleep(1000);  // 每秒查询一次
    }
}

main();
```

### 3.4 关键实现要点

**交易签名过程**需要对从路由接口获取的 Base64 交易数据进行反序列化，使用本地的私钥对交易进行签名，然后再序列化为 Base64 格式提交。

**交易状态轮询**采用循环机制，每秒钟查询一次交易状态，直至交易上链成功或确认超时过期。建议在实际生产环境中，通过指数退避或动态调整轮询频率来优化资源利用。

**错误处理机制**应涵盖网络异常、交易过期、余额不足等常见情况，确保系统的稳定性与可靠性。

## 四、最佳实践与注意事项

### 4.1 API 使用建议

- **请求频率控制**：严格遵守每 5 秒一次的调用限制，避免因频繁请求导致 API 被限制。建议在代码中实现请求队列或节流机制。
- **滑点设置**：根据交易对流动性状况合理设置滑点参数，低流动性代币应适当放宽滑点，以确保交易能够成功执行。
- **费用管理**：合理配置 `fee` 参数，在交易速度和成本之间找到平衡点。

### 4.2 抗 MEV 策略

启用 JITO Anti-MEV 功能（`is_anti_mev: true`）可有效保护交易免受三明治攻击，但需要额外设置至少 0.002 SOL 的费用。对于大额交易或高价值交易，建议始终启用该功能。

### 4.3 交易状态监控

交易过期时间约 60 秒，建议在轮询查询中加入超时机制，当确认交易过期后及时重新提交或取消订单。同时，应记录所有交易的哈希值和状态变化，用于后续对账和分析。

## 五、总结

GMGN Solana 交易 API 提供了一个完整的量化交易解决方案，其核心优势在于：

1. **低延迟路由**：智能路由算法自动寻找最优兑换路径
2. **抗 MEV 保护**：原生支持 JITO 防抢跑机制
3. **简化的交易流程**：三个核心接口覆盖从报价到确认的完整流程
4. **灵活的参数配置**：支持精确输入/输出、自定义滑点和费用设置

通过合理利用该 API，开发者可以构建高性能的自动交易系统，实现复杂交易策略。建议在实际部署前，先在测试环境充分验证交易流程，确保系统的稳定性和可靠性。