> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/integration-guides/rfq.md).

# RFQ

RFQ lets a trader ask market makers for extra liquidity before trading a large size. For the product overview, see [RFQ](https://docs.lighter.xyz/trading/rfq). The requester posts the market and the size they want to trade. Whitelisted market makers see the request and can add liquidity to the order book. The requester then trades against the book with a normal order.

RFQ doesn't settle anything by itself: there are no private quotes and nothing is locked. Every trade is a normal order on the Lighter order book. The RFQ endpoints and the `rfq` WebSocket channel are only how both sides coordinate.

The examples below use Lighter mainnet REST at `https://mainnet.zklighter.elliot.ai` and WebSocket at `wss://mainnet.zklighter.elliot.ai/stream`. Market makers and requesters use the same environment.

This page covers:

* [How an RFQ works](#how-an-rfq-works)
* [Market makers: answer RFQs](#market-makers-answer-rfqs)
* [Requesters: request and execute](#requesters-request-and-execute)
* [Integrators](#integrators)
* [Reference](#reference)

## How an RFQ works

![RFQ flow: the requester creates a request; a market maker can acknowledge, place ordinary orders, then report liquidity\_provided. The requester executes via sendTx and updates status. An RFQ can close from opened or order\_created, or expire about 1–2 minutes after creation.](https://1252326453-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDEieHYipGNMWymYUQkvO%2Fuploads%2FEGQlK4rSQm7PeVnoqiK1%2Frfq-flow-v2.jpg?alt=media)

1. The requester creates an RFQ with a market, a direction and a size.
2. Every subscriber to the `rfq` WebSocket channel receives the new RFQ. Non-requesters see the market and size but **not the side**.
3. A market maker can respond with `acknowledged`, place ordinary orders on the book, then report `liquidity_provided` once those orders are on the book. A maker can instead respond with `not_interested`. Makers can keep adjusting their order prices.
4. The requester watches the responses and the order book, then executes with a normal order through `sendTx`.
5. The requester marks the RFQ as `order_created` after creating an execution order. The requester can close the RFQ directly from `opened` or from `order_created`. The expiry worker runs once per minute and closes any non-closed RFQ older than one minute, including `order_created` entries. Closure normally occurs about 1–2 minutes after creation; use status updates rather than assuming a guaranteed execution window.

### Statuses

RFQ status:

| Status          | Meaning                                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `opened`        | Live: market makers can respond.                                                                                                                                              |
| `order_created` | The requester reports that an execution order has been created. This is a coordination status, not proof of a fill. MMs can still update their response until the RFQ closes. |
| `closed`        | Cancelled by the requester or expired. Final.                                                                                                                                 |

Allowed transitions: `opened → order_created`, `opened → closed`, `order_created → closed`.

Market maker response status (one entry per MM account, updated in place):

| Status               | Meaning                                                |
| -------------------- | ------------------------------------------------------ |
| `acknowledged`       | Seen, working on it.                                   |
| `liquidity_provided` | Liquidity has been added to the book for this request. |
| `not_interested`     | Passing.                                               |

### Who can do what

| Action                         | Who                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------- |
| Create an RFQ                  | Any authenticated account that meets the market and balance checks                |
| Update an RFQ                  | The account that created it                                                       |
| Get and list RFQs              | Any authenticated account, with requester-only fields redacted for other accounts |
| Subscribe to the `rfq` channel | Any account (authenticated)                                                       |
| Respond to an RFQ              | Whitelisted market makers only (error `64005` otherwise)                          |

The whitelist is per L1 address, so every account and sub-account owned by a whitelisted address can respond. To get whitelisted, [request access here](https://t.me/lighter_customer_bot?start=rfq_docs).

### Authentication

Every RFQ endpoint and the `rfq` channel require authentication. The REST examples use the `Authorization` header; REST also accepts the `auth` parameter. WebSocket subscriptions use the `auth` field. See [API keys](https://docs.lighter.xyz/developers/integration-guides/api-keys) for how to create one.

* `rfq/create`, `rfq/respond` and `rfq/update` need a standard auth token signed by an API key of the acting account. Read-only (`ro:`) tokens are rejected.
* `rfq/get`, `rfq/list` and the `rfq` channel also accept read-only tokens.
* The acting account is the one in the token. There is no `account_index` parameter on write endpoints. On `rfq/list`, `account_index` filters the requester whose RFQs you want to list; it does not change your identity or visibility.

## Market makers: answer RFQs

### 1. Subscribe to the `rfq` channel

```json
{ "type": "subscribe", "channel": "rfq", "auth": "<AUTH_TOKEN>" }
```

You first receive a `subscribed/rfq` message with every RFQ that isn't closed, then `update/rfq` messages each time an RFQ is created, answered, updated or expires. Each update carries the full RFQ entry, so you can replace your local copy by `id`.

```json
{
  "type": "update/rfq",
  "channel": "rfq",
  "rfqs": [
    {
      "id": 12345,
      "account_index": 678,
      "market_index": 1,
      "direction": -1,
      "base_amount": "250000",
      "quote_amount": "",
      "status": "opened",
      "metadata": {},
      "responses": [],
      "created_at": 1762350000000,
      "updated_at": 1762350000000
    }
  ]
}
```

On RFQs that aren't yours, `direction` is always `-1` (hidden), and `responses` and `metadata` are empty. You don't know the side, so quote both sides or size your quotes to the risk you're willing to take on either side.

Track `status`: stop working an RFQ once it is `closed`. RFQ closure does not cancel your existing orders; manage those through the normal order APIs.

On reconnect, subscribe again and rebuild the active RFQ set from `subscribed/rfq`. Use `rfq/get` or `rfq/list` to reconcile requests you were tracking. Refresh expired auth tokens before resubscribing. Follow the WebSocket connection and heartbeat rules in the [WebSocket reference](https://docs.lighter.xyz/api/websocket).

### 2. Respond (optional, but this is what the requester sees)

```bash
curl -X POST "https://mainnet.zklighter.elliot.ai/api/v1/rfq/respond" \
  -H "Authorization: <AUTH_TOKEN>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "rfq_id=12345&status=acknowledged"
```

Send `acknowledged` right away if you plan to quote, then `liquidity_provided` once your orders are on the book. Send `not_interested` to pass. Calling `respond` again replaces your previous status. You can respond while the RFQ is `opened` or `order_created`. A closed RFQ returns `64006`.

### 3. Provide liquidity on the order book

Place, modify and cancel normal orders through [sendTx](https://docs.lighter.xyz/api/transactions/sendtx) or [sendTxBatch](https://docs.lighter.xyz/api/transactions/sendtxbatch), for example post-only limit orders. A response doesn't reserve your liquidity for the requester: anyone can trade against your orders, and you can update them at any time.

Tip: use a dedicated API key for quoting so your RFQ orders don't queue behind other transactions on the same key (see [Core concepts](https://docs.lighter.xyz/developers/getting-started/core-concepts)).

## Requesters: request and execute

### 1. Subscribe to the `rfq` channel

Same subscription as above. For your own RFQs you get the full entry, including `direction`, `metadata` and every MM's `responses`.

### 2. Create an RFQ

```bash
curl -X POST "https://mainnet.zklighter.elliot.ai/api/v1/rfq/create" \
  -H "Authorization: <AUTH_TOKEN>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "market_index=1&direction=1&base_amount=250000"
```

| Field          | Required | Description                                                                                                                                                                                                                                                  |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `market_index` | yes      | Market ID from [orderBookDetails](https://docs.lighter.xyz/api/orders/orderbookdetails). Use the public ID of a currently active market. Perpetual and spot markets use the same RFQ workflow.                                                               |
| `direction`    | yes      | `1` = buy / long, `0` = sell / short.                                                                                                                                                                                                                        |
| `base_amount`  | one of   | Integer string in base units (scaled by the market's `size_decimals`).                                                                                                                                                                                       |
| `quote_amount` | one of   | Integer string in quote units (scaled by the market's `supported_quote_decimals`).                                                                                                                                                                           |
| `metadata`     | no       | JSON object serialized as a string, up to 1024 UTF-8 bytes. Only the requester can see it. Documented string-valued keys: `requested_est_price`, `requested_max_slippage`, `requested_slippage`, `requested_est_fill_fraction`, `mark_price`, `worst_price`. |

Send `base_amount`, `quote_amount` or both. Supplied values must be positive integer strings; omit an unused field instead of sending zero.

Convert human-readable amounts with decimal arithmetic: `base_amount = base size × 10^size_decimals`, and `quote_amount = quote size × 10^supported_quote_decimals`. For example, if `size_decimals` is 5, `base_amount=250000` represents 2.5 base units. Fetch current precision from `orderBookDetails`; do not use token L1 decimals or floating-point rounding.

Limits:

* Up to 3 RFQs in `opened` status per account per market. RFQs that are `order_created` or `closed` don't count (error `64013` when you hit the limit).
* For a perpetual RFQ, collateral must be positive. For a spot RFQ, the spot balance of the asset you give up must be positive: the quote asset for a buy, or the base asset for a sell (`64004` otherwise). Passing this check does not reserve funds or guarantee that the later order can execute.

The response contains `code` and the RFQ entry fields at the top level, including `id`, `account_index`, `market_index`, amounts, status and timestamps. Keep its `id`; there is no nested `rfq` wrapper. Each entry in `responses` includes `account_index`, `status`, `responded_at` and `updated_at` for that MM.

To retrieve it later:

```bash
curl --get "https://mainnet.zklighter.elliot.ai/api/v1/rfq/get" \
  -H "Authorization: <AUTH_TOKEN>" \
  --data-urlencode "rfq_id=12345"
```

### 3. Watch responses and the book

Follow `responses` on your RFQ through `update/rfq` messages (or poll `rfq/get`), and follow the book through the `order_book` channel. A `liquidity_provided` response means an MM says they've added liquidity. Always check the book itself before executing: prices aren't locked and can change until your order matches.

### 4. Execute

Execute with a normal order through `sendTx`. Use a market order or an IOC limit order, and set a worst price you accept. There is no RFQ-specific order type, and your order can fill against any liquidity on the book.

Act while the request is active and liquidity remains available. MMs may change or withdraw their orders at any time, including after RFQ closure. Track the execution order and its fills separately: transaction submission and RFQ status do not establish that the requested size traded.

### 5. Update the RFQ

After creating the execution order, notify the RFQ system with `order_created`:

```bash
curl -X POST "https://mainnet.zklighter.elliot.ai/api/v1/rfq/update" \
  -H "Authorization: <AUTH_TOKEN>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "rfq_id=12345&status=order_created"
```

To close the RFQ, send `status=closed`. This closes the coordination request and does not cancel orders already submitted or reverse fills. Only the account that created the RFQ can update it (`64008`).

## Integrators

Integrators can use both sides:

* **Requester side, for your users.** Create RFQs and execute on behalf of a user, with their authorization, using an auth token and signing capability for that user's account, exactly as in [Requesters](#requesters-request-and-execute). You can attach your partner attribution to the execution order like any other order (see [Partner Attribution](https://docs.lighter.xyz/developers/integration-guides/partner-attribution)). The RFQ endpoints have no partner-attribution field; attribution belongs on the execution order.
* **Market maker side.** Respond from your own accounts. Your L1 address needs to be whitelisted (see [Who can do what](#who-can-do-what)).
* **Showing RFQ data in your UI.** `rfq/list` and the `rfq` channel accept read-only tokens, so you can show a user their RFQs and MM responses without holding a signing key.

## Reference

### Endpoints

| Endpoint                                                              | Method | Purpose                                                                                                                                            |
| --------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/api/v1/rfq/create`](https://docs.lighter.xyz/api/rfq/rfq_create)   | POST   | Create an RFQ                                                                                                                                      |
| [`/api/v1/rfq/respond`](https://docs.lighter.xyz/api/rfq/rfq_respond) | POST   | MM response (whitelist)                                                                                                                            |
| [`/api/v1/rfq/update`](https://docs.lighter.xyz/api/rfq/rfq_update)   | POST   | Requester: `order_created` or `closed`                                                                                                             |
| [`/api/v1/rfq/get`](https://docs.lighter.xyz/api/rfq/rfq_get)         | GET    | One RFQ by `rfq_id`                                                                                                                                |
| [`/api/v1/rfq/list`](https://docs.lighter.xyz/api/rfq/rfq_list)       | GET    | Newest RFQ ID first. Filters: `account_index`, `status`. Paging: `limit` (default 20; use 1–100), `cursor` (`next_cursor` from the previous page). |
| [`rfq` channel](https://docs.lighter.xyz/api/websocket)               | WS     | Snapshot of non-closed RFQs, then live updates                                                                                                     |

POST bodies are `application/x-www-form-urlencoded`.

For `rfq/list`, omit `account_index` for all requesters visible to you; pass your own account index to list only your requests. The response has `code`, an `rfqs` array and an optional `next_cursor`. Keep filters unchanged and URL-encode each cursor. Stop when the cursor is absent; a final cursor can lead to an empty page. The current implementation falls back to 20 when `limit` is 0 or above 100, so explicitly use a value from 1 to 100.

```bash
curl --get "https://mainnet.zklighter.elliot.ai/api/v1/rfq/list" \
  -H "Authorization: <AUTH_TOKEN>" \
  --data-urlencode "account_index=<YOUR_ACCOUNT_INDEX>" \
  --data-urlencode "limit=20"
```

### Visibility

| Field                                                                                                      | Requester | Everyone else |
| ---------------------------------------------------------------------------------------------------------- | --------- | ------------- |
| `id`, `account_index`, `market_index`, `base_amount`, `quote_amount`, `status`, `created_at`, `updated_at` | yes       | yes           |
| `direction`                                                                                                | yes       | `-1`          |
| `metadata`, `responses`                                                                                    | yes       | empty         |

Timestamps are in milliseconds.

### Errors

RFQ error codes and explanations are listed in [Data Structures, Constants and Errors → RFQ errors](https://docs.lighter.xyz/developers/reference/data-structures-constants-and-errors.md#rfq-errors).

Handle these cases in your integration:

* `64010`: another operation on the same RFQ is in progress; retry with a short backoff.
* `64013`: the account has reached three open RFQs for this market; wait for a request to close or close one you no longer need.
* `64005`: the responding account's L1 address is not whitelisted; request access before responding.

Authentication and malformed-input failures can also return general API errors, including `20013` (invalid auth) and `20001` (invalid parameter). See [Data Structures, Constants and Errors](https://docs.lighter.xyz/developers/reference/data-structures-constants-and-errors).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lighter.xyz/developers/integration-guides/rfq.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
