# 接入 RFQ

Source: https://docs.hedgehood.io/zh/earn-upfront/makers

:::warning[测试网]

做市商接入目前在 Robinhood Chain **测试网**开放。合约尚未经过第三方审计；主网地址和主网白名单在上线后公布。

:::

任何白名单做市商都可以买入 Earn upfront 用户卖出的期权。做市商通过 WebSocket 连接 RFQ 网关，同时收到每个询价，在 **2 秒窗口**内回复一个**自己签名的 EIP-712 确定报价**，有效期最长 120 秒。网关把最好的报价返回给用户，用户从自己的钱包通过 `RfqSettler` 在链上成交。网关不持有资金或私钥，也改不了你的报价。没有 last look。

![一次询价，逐条消息：应用 POST /v1/rfq；网关向每个做市商发送 rfq；每个做市商在 2 秒内回复签名报价或拒绝；网关检查每个报价，返回最好的报价和成交 calldata；做市商收到 won 或 lost；用户发送 RfqSettler.fill；网关看到 Filled 事件后向中标者发送 fill。](https://docs.hedgehood.io/img/earn-upfront/rfq-flow-zh.svg)

## 交易什么

Robinhood Chain 股票代币的欧式期权，以 USDG 计价，在挂牌交易日美东 16:00 收盘时到期。一个系列由 `(underlying, quote, oracle, expiry, isPut, strike, physical)` 确定。

| `side` | 用户 | 你 | 权利金 |
|---|---|---|---|
| `0` MakerBuys | 卖出备兑看涨或现金担保看跌（锁定抵押品） | 收到多头（`OptionsCore` 里的 ERC-6909） | 你支付 `premium + fee` |
| `1` MakerSells | 提前平掉空头 | 交出你已持有的多头 | 你收到 `premium − fee` |

- **没有信用风险。** 你买到的每个多头都在内核里全额抵押；你不需要交保证金。
- **结算所得主动发放。** 到期后 Hedgehood 的 keeper 结算每个系列，并把每个多头赎回给持有人。见[到期结算](https://docs.hedgehood.io/zh/earn-upfront/makers/settlement)。
- **平仓报价不是义务。** Hedgehood 不向用户承诺可以提前退出。你只能为自己持有的系列报平仓价，网关会检查。

## 消息

WebSocket `wss://<gateway>/v1/maker/ws`，JSON 文本帧。完成挑战和登录（由做市商密钥或做市商授权的热密钥做 EIP-191 签名）后，网关发送 `ready`，带上你的 epoch 和当前生效的费率。

| 方向 | 帧 | 含义 |
|---|---|---|
| ← | `rfq` | 一个询价；在 `respondBy` 之前回复 |
| → | `quote` / `decline` | 你的签名报价，或拒绝原因 |
| ← | `won` / `lost` | 你的报价是否被返回给用户 |
| ← | `fill` | 用户已在链上成交你的报价（`txHash`） |
| ← | `rejected` | 你的报价为什么不能中标（见下方代码） |
| → | `pause` / `resume` | 停止或恢复接收询价 |

### 数据结构

```ts
type Rfq = {
  type: "rfq"
  rfqId: string
  chainId: number            // 测试网为 46630
  settler: string            // RfqSettler 地址
  taker: string              // 用户钱包
  side: 0 | 1                // 0 MakerBuys（开仓），1 MakerSells（平仓）
  series: SeriesParams
  amount: string             // 股票代币原始单位，18 位小数："1000000000000000000" = 1 股
  respondBy: number          // unix 毫秒：询价时间 + 2 秒
  minValidUntil: number      // unix 秒：你的 validUntil 不能早于它
}

type SeriesParams = {
  underlying: string         // 股票代币
  quote: string              // USDG（6 位小数）
  oracle: string             // 挂牌的 StockSettlementSource
  expiry: number             // unix 秒，纽约时间 16:00 收盘
  isPut: boolean
  strike: string             // 每个完整代币的 USDG 原始单位："330000000" = $330
  physical: boolean
}

type Quote = {               // 按 EIP-712 "Quote" 签名（domain "Hedgehood RFQ Settler"，version "2"）
  maker: string
  signer: string             // 做市商本人，或它用 setSigner 授权的热密钥
  taker: string              // 必须与询价一致
  externalAccount: string    // 0x0 = 从结算合约余额支付；否则为用授权额度支付的钱包
  series: SeriesParams       // 必须与询价一致
  side: 0 | 1                // 必须与询价一致
  amount: string             // 必须与询价一致
  minFill: string            // 必须等于 amount（只能整笔成交）
  premium: string            // 整个数量的 USDG 原始单位，不含手续费
  validUntil: number         // unix 秒，最多 now + 120 秒
  nonce: string              // 每个报价唯一（位图 nonce）
  epoch: string              // 必须等于 settler.epoch(maker)
}

// → {"type":"quote","rfqId":"…","quote":{…},"signature":"0x…"}   65 字节 r‖s‖v，low-s
// → {"type":"decline","rfqId":"…","reason":"no_inventory"}
```

uint256 字段（`amount`、`strike`、`minFill`、`premium`、`nonce`、`epoch`）是十进制字符串；`expiry`、`validUntil`、`side` 和 `chainId` 是 JSON 数字。SDK 会帮你构建、签名和检查这些字段。

### 报价不能中标的原因

| 代码 | 含义 |
|---|---|
| `bad_signature` | 不是做市商或有效的授权签名者签的 |
| `mismatch` | 某个字段与询价不一致、`minFill ≠ amount`，或权利金为 0 |
| `expiry` | `validUntil` 不在 [`minValidUntil`, now + 120 秒] 之间 |
| `stale_epoch` / `nonce_used` | 报价已被撤销 |
| `funding` | side 0：你的结算合约余额，或外部账户的余额、授权额度和关联，低于 权利金 + 手续费 |
| `inventory` | side 1：你没有持有这个多头，或结算合约不是你的 operator |
| `late` | 在 `respondBy` 之后才到 |
| `unavailable` / `invalid` | 网关读不到链上数据 / 帧格式错误 |

## 费用

结算合约按每笔成交向**做市商**收费：`min(premium × 12.5%, notional × 1%)`，notional 为 数量 × 行权价，在链上强制执行。你签名的 `premium` 不含手续费：买入时你支付 权利金 + 手续费，卖出时你收到 权利金 − 手续费。

示例：10 份 TSLA 看跌，行权价 220，权利金 300 USDG。12.5% 是 37.5；上限是 1% × 2,200 = 22；手续费为 22 USDG。

手续费**提高**要先在链上排期（`FeeIncreaseScheduled`），24 小时后才生效，所以你签过的报价不会按你看不到的费率成交；降低立即生效。

## 时限和限制

| 规则 | 数值 |
|---|---|
| 竞价窗口 | `respondBy` = 询价时间 + 2 秒；所有做市商都回复后网关会提前返回 |
| 报价有效期 | `validUntil` ≤ now + 120 秒，且 ≥ `minValidUntil`（`respondBy` + 15 秒） |
| 成交规模 | 整笔成交（`minFill = amount`） |
| 询价规模 | 低于网关最低名义金额（数量 × 行权价）的开仓询价在发给做市商之前就被拒绝；平仓不受限制。当前限制见 `GET /healthz` → `limits` |
| 新开仓 | 预言机和到期日已挂牌、未暂停、离到期不太近 |

每个询价都要回复：拒绝也算回复。连续 20 个询价不回复，或一小时内 3 次失约（撤销已中标的报价），你的连接会被暂停 15 分钟。你的成绩单公开在 `GET /v1/makers`。

## 客户端

MIT 许可，报价签名与结算合约逐字节一致，并用同一套[测试向量](https://github.com/0xHedgeHood/sdks/blob/main/vectors/goldens.json)校验：

| | 仓库 | 安装 |
|---|---|---|
| Python | [hedgehood-maker-py](https://github.com/0xHedgeHood/hedgehood-maker-py) | `pip install hedgehood-maker` |
| TypeScript | [hedgehood-maker-ts](https://github.com/0xHedgeHood/hedgehood-maker-ts) | `npm install @hedgehood-io/maker` |
| Go 和命令行 | [hedgehood-maker-go](https://github.com/0xHedgeHood/hedgehood-maker-go) | `go get github.com/0xHedgeHood/hedgehood-maker-go/maker` |

完整的协议参考、所有消息帧和成绩单规则见[做市商指南](https://github.com/0xHedgeHood/sdks/blob/main/docs/MAKER_GUIDE.md)。要接入，按[做市商快速上手](https://docs.hedgehood.io/zh/earn-upfront/makers/quickstart)操作。

## 测试网

Robinhood Chain 测试网，chainId 46630。主网地址在上线后公布。

| | |
|---|---|
| `RfqSettler`（代理） | `0xda43b0933031e41D5B367E1807536FcF4ebdEE7e` |
| `OptionsCore`（代理） | `0xde5ce903254E9597822D5456a82a25640285B8B4` |
| 测试 USDG（6 位小数） | `0x850DE815d41F6983Aaf09247f9a465c0aefff04C` |
| TSLA 测试股票代币（18 位小数） | `0x6661d20C2e343Bb78B42535eB060C3058c744f3F` |
| TSLA 结算源 | `0x9e6C529CAA69d44b63df27483c57f97a42D6e898` |
| RPC | `https://rpc.testnet.chain.robinhood.com` |
| 做市商 WebSocket | `wss://testnet-rfq.hedgehood.io/v1/maker/ws` |
| 询价 / 限制 / 成绩单 | `https://testnet-rfq.hedgehood.io` `/v1/rfq`、`/healthz`、`/v1/makers` |

## 上线流程

![做市商上线：介绍会、测试网配置、测试网跑 48 小时（至少 3 笔开仓和 2 笔平仓成交，一笔持有到期），复盘成绩单后上主网。](https://docs.hedgehood.io/img/earn-upfront/onboarding-zh.svg)

| 阶段 | 内容 |
|---|---|
| 1. 介绍会 | 你提供做市商地址、标的和规模。我们把你加入测试网白名单，并商定初始主网额度。 |
| 2. 测试网配置 | 授权热签名密钥、出资、授权结算合约为多头的 operator、连接机器人。见[快速上手](https://docs.hedgehood.io/zh/earn-upfront/makers/quickstart)。 |
| 3. 测试网运行 | 覆盖一个美股交易时段、连续在线 48 小时；每个询价按时回复；至少 3 笔开仓和 2 笔提前平仓成交；一个仓位持有到期。 |
| 4. 主网 | 我们和你一起复盘测试网成绩单，把你加入主网白名单。 |

## 联系方式

- **白名单和接入问题：** [admin@hedgehood.io](mailto:admin@hedgehood.io)。
- **安全：** 发现漏洞请先私下发邮件到 [admin@hedgehood.io](mailto:admin@hedgehood.io)，不要公开披露，也不要拿其他用户的仓位做测试。
