# Integrate in the RFQ

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

:::warning[Testnet]

Maker integration is open on Robinhood Chain **testnet**. The contracts have not had a third-party audit yet; mainnet
addresses and the mainnet allowlist follow the launch.

:::

Any allowlisted market maker can buy the options Earn upfront users sell. Makers connect to the RFQ gateway over a
WebSocket, receive every request at once, and answer within a **2-second window** with a **firm EIP-712 quote they
sign themselves**, valid for up to 120 seconds. The gateway returns the best quote to the user, who fills it on chain
through `RfqSettler` from their own wallet. The gateway holds no funds or keys and cannot change your quote. There is
no last look.

![One request, message by message: the app posts /v1/rfq; the gateway sends an rfq frame to every maker; each answers with a signed quote or a decline within 2 seconds; the gateway checks every quote and returns the best with the fill calldata; makers get won or lost; the user sends RfqSettler.fill; the gateway sees the Filled event and sends the winner a fill frame.](https://docs.hedgehood.io/img/earn-upfront/rfq-flow-en.svg)

## What you trade

European options on Robinhood Chain stock tokens, priced in USDG, expiring at the 16:00 ET close of a listed day.
A series is `(underlying, quote, oracle, expiry, isPut, strike, physical)`.

| `side` | The user | You | Premium |
|---|---|---|---|
| `0` MakerBuys | writes a covered call or cash-secured put (locks the collateral) | receive the long (ERC-6909 in `OptionsCore`) | you pay `premium + fee` |
| `1` MakerSells | closes a short early | deliver a long you already hold | you receive `premium − fee` |

- **No credit risk.** Every long you buy is fully collateralised in the kernel; you post no margin.
- **Payouts are pushed.** After expiry, Hedgehood's keeper settles each series and redeems every long to its holder.
  See [Settlement for makers](https://docs.hedgehood.io/earn-upfront/makers/settlement).
- **Closes are optional.** Hedgehood does not promise users an early exit. You can only quote a close for a series you
  hold, and the gateway checks that.

## Messages

WebSocket `wss://<gateway>/v1/maker/ws`, JSON text frames. After a challenge-and-login (an EIP-191 signature by your
maker key or a hot key the maker delegated), the gateway sends `ready` with your epoch and the fees in effect.

| Direction | Frame | Meaning |
|---|---|---|
| ← | `rfq` | a request; answer before `respondBy` |
| → | `quote` / `decline` | your signed quote, or a reason |
| ← | `won` / `lost` | whether your quote was returned to the user |
| ← | `fill` | the user filled your quote on chain (`txHash`) |
| ← | `rejected` | why your quote cannot win (see codes below) |
| → | `pause` / `resume` | stop or restart receiving requests |

### Data structures

```ts
type Rfq = {
  type: "rfq"
  rfqId: string
  chainId: number            // 46630 on testnet
  settler: string            // RfqSettler address
  taker: string              // the user's wallet
  side: 0 | 1                // 0 MakerBuys (open), 1 MakerSells (close)
  series: SeriesParams
  amount: string             // stock token raw, 18 decimals: "1000000000000000000" = 1 share
  respondBy: number          // unix ms: request time + 2 s
  minValidUntil: number      // unix s: your validUntil must be at least this
}

type SeriesParams = {
  underlying: string         // stock token
  quote: string              // USDG (6 decimals)
  oracle: string             // the listed StockSettlementSource
  expiry: number             // unix s, a 16:00 New York close
  isPut: boolean
  strike: string             // USDG raw per whole token: "330000000" = $330
  physical: boolean
}

type Quote = {               // signed as EIP-712 "Quote" (domain "Hedgehood RFQ Settler", version "2")
  maker: string
  signer: string             // the maker, or a hot key it delegated with setSigner
  taker: string              // must match the request
  externalAccount: string    // 0x0 = pay from your settler balance; else the wallet that pays by allowance
  series: SeriesParams       // must match the request
  side: 0 | 1                // must match the request
  amount: string             // must match the request
  minFill: string            // must equal amount (whole fills only)
  premium: string            // USDG raw for the whole amount, fee excluded
  validUntil: number         // unix s, at most now + 120 s
  nonce: string              // unique per quote (bitmap nonce)
  epoch: string              // must equal settler.epoch(maker)
}

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

uint256 fields (`amount`, `strike`, `minFill`, `premium`, `nonce`, `epoch`) are decimal strings; `expiry`,
`validUntil`, `side` and `chainId` are JSON numbers. The SDKs build, sign and check all of this for you.

### Why a quote cannot win

| Code | Meaning |
|---|---|
| `bad_signature` | not signed by the maker or a live delegated signer |
| `mismatch` | a field differs from the request, `minFill ≠ amount`, or premium is 0 |
| `expiry` | `validUntil` outside [`minValidUntil`, now + 120 s] |
| `stale_epoch` / `nonce_used` | the quote was cancelled |
| `funding` | side 0: your settler balance, or the external account's balance, allowance and link, is below premium + fee |
| `inventory` | side 1: you do not hold the long, or the settler is not your operator |
| `late` | arrived after `respondBy` |
| `unavailable` / `invalid` | the gateway could not read the chain / the frame is malformed |

## Fees

The settler charges the **maker**, per fill: `min(premium × 12.5 %, notional × 1 %)`, where notional is
amount × strike, enforced on chain. The `premium` you sign excludes the fee: on a buy you pay premium + fee, on a sell
you receive premium − fee.

Example: 10 TSLA puts at strike 220, premium 300 USDG. 12.5 % would be 37.5; the cap is 1 % × 2,200 = 22; the fee is
22 USDG.

A fee **increase** is scheduled on chain (`FeeIncreaseScheduled`) and applies 24 hours later, so a quote you signed
never fills under a fee you could not see; a decrease applies at once.

## Timing and limits

| Rule | Value |
|---|---|
| Auction window | `respondBy` = request + 2 s; the gateway answers early once every maker has replied |
| Quote life | `validUntil` ≤ now + 120 s and ≥ `minValidUntil` (`respondBy` + 15 s) |
| Fill size | whole fills (`minFill = amount`) |
| Request size | opens below the gateway's minimum notional (amount × strike) are refused before makers are asked; closes are exempt. Current bounds: `GET /healthz` → `limits` |
| New positions | listed oracle and expiry, not paused, not too close to the expiry |

Answer every request: a decline counts as an answer. 20 unanswered requests in a row, or 3 fades (a winning quote you
cancelled) within an hour, pause your connection for 15 minutes. Your scorecard is public at `GET /v1/makers`.

## Clients

MIT-licensed, with quote signing byte-equal to the settler and checked against the same
[test vectors](https://github.com/0xHedgeHood/sdks/blob/main/vectors/goldens.json):

| | Repository | Install |
|---|---|---|
| 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 and CLI | [hedgehood-maker-go](https://github.com/0xHedgeHood/hedgehood-maker-go) | `go get github.com/0xHedgeHood/hedgehood-maker-go/maker` |

The full wire reference, every frame and the scorecard rules are in the
[maker guide](https://github.com/0xHedgeHood/sdks/blob/main/docs/MAKER_GUIDE.md). To get connected, follow the
[maker quickstart](https://docs.hedgehood.io/earn-upfront/makers/quickstart).

## Testnet

Robinhood Chain testnet, chainId 46630. Mainnet addresses follow the launch.

| | |
|---|---|
| `RfqSettler` (proxy) | `0xda43b0933031e41D5B367E1807536FcF4ebdEE7e` |
| `OptionsCore` (proxy) | `0xde5ce903254E9597822D5456a82a25640285B8B4` |
| Test USDG (6 decimals) | `0x850DE815d41F6983Aaf09247f9a465c0aefff04C` |
| TSLA test stock token (18 decimals) | `0x6661d20C2e343Bb78B42535eB060C3058c744f3F` |
| TSLA settlement source | `0x9e6C529CAA69d44b63df27483c57f97a42D6e898` |
| RPC | `https://rpc.testnet.chain.robinhood.com` |
| Maker WebSocket | `wss://testnet-rfq.hedgehood.io/v1/maker/ws` |
| Request for quote / limits / scorecard | `https://testnet-rfq.hedgehood.io` `/v1/rfq`, `/healthz`, `/v1/makers` |

## Going live

![How a maker goes live: an intro call, testnet setup, a 48-hour testnet run with at least three opens and two closes filled and one position held to expiry, then mainnet after a scorecard review.](https://docs.hedgehood.io/img/earn-upfront/onboarding-en.svg)

| Stage | What happens |
|---|---|
| 1. Intro call | You share your maker address, underlyings and sizes. We allowlist you on testnet and agree initial mainnet limits. |
| 2. Testnet setup | Delegate a hot signer, fund, approve the settler as operator of your longs, connect your bot. See the [quickstart](https://docs.hedgehood.io/earn-upfront/makers/quickstart). |
| 3. Testnet run | 48 hours connected across a US session; every request answered in time; at least 3 opens and 2 early closes filled; one position held to expiry. |
| 4. Mainnet | We review your testnet scorecard with you and add you to the mainnet allowlist. |

## Contact

- **Allowlisting and integration questions:** [admin@hedgehood.io](mailto:admin@hedgehood.io).
- **Security:** report vulnerabilities privately to [admin@hedgehood.io](mailto:admin@hedgehood.io) before disclosing
  anything, and do not test against other users' positions.
