# Quoting

Builders and signers for the two messages a desk sends in an opening auction: a sealed **bid intent** while the RFQ collects, and an executable **quote** when you win the award. The builders only copy fields. The price is always yours: the SDK has no pricing logic.


## How an auction uses these

1. An RFQ arrives on your feed. Read its snapshot with [`client.getRfq`](https://docs.covr.markets/reference/sdk/gateway-client.md#clientgetrfq) and decode its market ([`decodeMarketV3`](https://docs.covr.markets/reference/sdk/markets.md#decodemarketv3)).
2. Within 3 s of the RFQ ([`COLLECT_MS`](https://docs.covr.markets/reference/sdk/constants.md#collect_ms)), send one bid intent: [`buildBidIntent`](#buildbidintent), [`signIntent`](#signintent), [`client.sendBidIntent`](https://docs.covr.markets/reference/sdk/gateway-client.md#clientsendbidintent). One intent per maker per auction.
3. The gateway ranks intents by price. The winner gets an `award` with an `awardUntil` deadline (at most 3 s, [`AWARD_MS`](https://docs.covr.markets/reference/sdk/constants.md#award_ms)).
4. The winner answers with a quote: [`buildQuote`](#buildquote), [`signQuote`](#signquote), [`client.sendQuote`](https://docs.covr.markets/reference/sdk/gateway-client.md#clientsendquote), or passes with [`client.sendAwardDecline`](https://docs.covr.markets/reference/sdk/gateway-client.md#clientsendawarddecline).
5. The customer's wallet signs and submits the fill. You see it only on chain, as your position PDA ([`derivePosition`](https://docs.covr.markets/reference/sdk/setup.md#deriveposition)).

> [!NOTE]
> covr's markets list only covr's own maker today. Every other desk's bid intent is verified exactly like a real one and then refused with `Bid intent verified but not entered: this market does not list this maker yet` ("practice mode"). It never wins and never moves a price.

See [RFQ lifecycle](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md) for the full protocol.


## Units used on this page

| Field | Unit |
| --- | --- |
| `price` | Gross premium per **one whole** collateral token, in USDC × 10^18 (`priceE18`), as a decimal string on the wire. `2400000000000000000` is 2.40 USDC per token. |
| `quantity` | Collateral atoms scaled to 18 decimals (`quantityE18`), decimal string. For JitoSOL (9 decimals), 1 atom is `1000000000`. Convert with [`atomsFromWire`](https://docs.covr.markets/reference/sdk/settlement.md#atomsfromwire). |
| `strike` | Strike in USD × 10^8 (`strikeE8`), decimal string. `17000000000` is $170. |
| `expiry`, `validUntil` | Unix seconds, integer `number`. |
| `nonce` | u64 as a decimal string. |
| `closesAt`, `hardDeadline`, `awardUntil` | Epoch **milliseconds**. |

The gross premium of a fill is `atoms × price / 10^(decimals + 12)` USDC atoms, and it must be exact. The gateway refuses an intent whose premium is not a whole USDC atom. Round your price with [`exactPriceAtOrBelow`](https://docs.covr.markets/reference/sdk/settlement.md#exactpriceatorbelow).


## BID_INTENT_TYPES

The EIP-712 types of a bid intent.

```ts
export declare const BID_INTENT_TYPES: {
    BidIntent: {
        name: string;
        type: string;
    }[];
};
```

- **Value:** `BidIntent(bytes32 auctionId, uint8 kind, bytes32 market, bytes32 position, bytes32 wallet, address assetAddress, uint256 chainId, bool isPut, uint256 strike, uint64 expiry, address maker, uint256 price, uint256 quantity, bool isTakerBuy, uint64 validUntil, address usd, address collateralAsset)`, in that order.
- **Where it matters:** [`signIntent`](#signintent) signs with it, and the gateway verifies with it. The object is not frozen: never modify it.


## QUOTE_V2_TYPES

The EIP-712 types of an executable quote. The program rebuilds the same digest at fill.

```ts
export declare const QUOTE_V2_TYPES: {
    QuoteV2: {
        name: string;
        type: string;
    }[];
};
```

- **Value:** `QuoteV2(bytes32 auctionId, bytes32 writer, address assetAddress, uint256 chainId, bool isPut, uint256 strike, uint64 expiry, address maker, uint64 nonce, uint256 price, uint256 quantity, bool isTakerBuy, uint64 validUntil, address usd, address collateralAsset)`, in that order.
- **Where it matters:** [`signQuote`](#signquote). The object is not frozen: never modify it.


## WITHDRAW_TYPES

The EIP-712 types of a quote withdrawal: `WithdrawBid(string rfqId, bytes32 quoteHash)`.

```ts
export declare const WITHDRAW_TYPES: {
    WithdrawBid: {
        name: string;
        type: string;
    }[];
};
```

- **Value:** `{ WithdrawBid: [{ name: 'rfqId', type: 'string' }, { name: 'quoteHash', type: 'bytes32' }] }`
- **Where it matters:** only [`signWithdrawal`](#signwithdrawal), which desks cannot use today.


## auctionKey

Hashes an RFQ id into the `bytes32` the intent and quote sign: `keccak256(utf8(id))`.

```ts
export declare const auctionKey: (id: string) => string;
```

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | RFQ id: a lowercase UUID v4, for example `3f2b8c1e-5d4a-4e7b-9c2d-1a2b3c4d5e6f`. |

**Returns:** `string`, `0x` plus 64 hex characters.

**Throws:** `Invalid auction ID` when `id` is not a lowercase UUID v4 (uppercase is refused).


```ts
import { auctionKey } from '@covrfun/maker-sdk';

auctionKey('3f2b8c1e-5d4a-4e7b-9c2d-1a2b3c4d5e6f');
// '0x7237c0c9e587161e71471ae107a640d9a6f65b26ab32795d70836ee1e90cd42d'
```

## defaultIntentValidUntil

Returns the bid intent expiry covr's own maker uses: `min(option expiry, ceil(hardDeadline / 1000) + 60)`.

```ts
export declare function defaultIntentValidUntil(snapshot: Pick<RfqSnapshot, 'hardDeadline' | 'request'>): number;
```

| Name | Type | Description |
| --- | --- | --- |
| `snapshot.hardDeadline` | `number` | Auction hard deadline, epoch ms. |
| `snapshot.request.expiry` | `number` | Option expiry, unix seconds. |

**Returns:** `number`, unix seconds. It always lies after the collection window closes, which [`buildBidIntent`](#buildbidintent) requires.

**Throws:** nothing. A missing `hardDeadline` yields `NaN`, which [`buildBidIntent`](#buildbidintent) then refuses.


```ts
import { defaultIntentValidUntil, type RfqSnapshot } from '@covrfun/maker-sdk';

declare const snapshot: RfqSnapshot;
const validUntil = defaultIntentValidUntil(snapshot);
```

## buildBidIntent

Builds the unsigned sealed bid intent for an opening RFQ. It copies every instrument field verbatim from the snapshot, because the gateway compares them as exact strings.

```ts
export declare function buildBidIntent(snapshot: RfqSnapshot, input: {
    maker: string;
    price: bigint | string;
    validUntil: number;
}): UnsignedBidIntent;
```

| Name | Type | Description |
| --- | --- | --- |
| `snapshot` | [`RfqSnapshot`](https://docs.covr.markets/reference/sdk/types.md#rfqsnapshot) | From [`client.getRfq`](https://docs.covr.markets/reference/sdk/gateway-client.md#clientgetrfq). |
| `input.maker` | `string` | Your quote key address (`0x…`). The gateway requires it to equal the key your token is registered to. |
| `input.price` | `bigint \| string` | Gross premium per one whole collateral token, USDC × 10^18. Positive, below 2^128. A string must be a canonical decimal integer. |
| `input.validUntil` | `number` | Intent expiry, unix seconds. Must be after `ceil(closesAt / 1000)` and at most `request.expiry`. |

**Returns:** [`UnsignedBidIntent`](https://docs.covr.markets/reference/sdk/types.md#unsignedbidintent) with 17 fields: `auctionId` (= `snapshot.id`), `kind: 'open'`, `market`, `position: null`, `wallet` (the writer), `assetAddress` (= `request.asset`), `chainId`, `expiry`, `isPut`, `isTakerBuy`, `quantity`, `strike`, `usd`, `collateralAsset`, `maker`, `price` (decimal string) and `validUntil`.

It does not check `snapshot.status`, your clock or the market. Skip RFQs whose status is not `collecting` or whose `closesAt` has passed.

**Throws:**

| Condition | Message |
| --- | --- |
| `snapshot.kind` is not `open`, or `position` is not `null` | `maker-sdk: only open (opening) auctions take bid intents` |
| `snapshot.id` is not a lowercase UUID v4 | `maker-sdk: invalid auction id` |
| `market` or `wallet` is not a string | `maker-sdk: snapshot must carry market and wallet` |
| `price` is a string that is not a canonical decimal integer | `canonical unsigned integer required` |
| `price` is a string of 2^128 or more | `integer overflow` |
| `price` is zero, negative, or a bigint of 2^128 or more | `maker-sdk: price must be a positive u128 priceE18 (USDC per whole token, 18 decimals)` |
| `validUntil` is not a safe integer | `maker-sdk: validUntil must be integer unix seconds` |
| `validUntil <= ceil(closesAt / 1000)` | `maker-sdk: validUntil must be after the collection window closes` |
| `validUntil > request.expiry` | `maker-sdk: validUntil must not exceed the option expiry` |


```ts
import {
  atomsFromWire,
  buildBidIntent,
  defaultIntentValidUntil,
  exactPriceAtOrBelow,
  type DecodedMarketV3,
  type RfqSnapshot,
} from '@covrfun/maker-sdk';

declare const snapshot: RfqSnapshot;
declare const market: DecodedMarketV3;
declare const quoteKeyAddress: string;
// Your model: USDC x 1e18 per whole collateral token.
declare function myModel(snapshot: RfqSnapshot, market: DecodedMarketV3): Promise<bigint>;

const atoms = atomsFromWire(snapshot.request.quantity, market.collateralDecimals);
const myPriceE18 = await myModel(snapshot, market);
const price = exactPriceAtOrBelow(myPriceE18, atoms, market.collateralDecimals);
if (price === 0n) throw new Error('no exact price at or below the model: skip this RFQ');

const unsigned = buildBidIntent(snapshot, {
  maker: quoteKeyAddress,
  price,
  validUntil: defaultIntentValidUntil(snapshot),
});
```

## buildQuote

Builds the unsigned executable quote that answers an award. It takes the maker, price and instrument from your intent, and binds the quote to this auction and to the writer's wallet.

```ts
export declare function buildQuote(snapshot: Pick<RfqSnapshot, 'id' | 'wallet'>, intent: UnsignedBidIntent | BidIntent, input: {
    nonce: bigint;
    validUntil: number;
}): UnsignedQuoteV2;
```

| Name | Type | Description |
| --- | --- | --- |
| `snapshot.id` | `string` | The RFQ id. Must equal `intent.auctionId`. |
| `snapshot.wallet` | `string` | The writer (customer) wallet. Becomes `writer`. |
| `intent` | [`BidIntent`](https://docs.covr.markets/reference/sdk/types.md#bidintent) | **Your own stored copy** of the intent you signed, never the copy inside the award. |
| `input.nonce` | `bigint` | A fresh nonce: `0` to `2^64 - 2`, at least your on-chain `min_nonce`, never used before. |
| `input.validUntil` | `number` | Quote expiry, unix seconds, positive, at most the option expiry. |

**Returns:** [`UnsignedQuoteV2`](https://docs.covr.markets/reference/sdk/types.md#unsignedquotev2) with 15 fields: `auctionId`, `writer`, `assetAddress`, `chainId`, `isPut`, `strike`, `expiry`, `maker`, `nonce` (decimal string), `price`, `quantity`, `isTakerBuy`, `validUntil`, `usd`, `collateralAsset`.

Beyond what this function checks, the quote must also pass:

- the gateway: `now < validUntil <= now + 60` on its clock, and the award not yet expired;
- the program at fill: chain clock `< validUntil`, `validUntil <= expiry`, `nonce >= min_nonce`, and the position PDA for this nonce not existing yet.

Leave a few seconds of margin: covr's example bot uses `min(expiry, now + 55)`.

> [!WARNING]
> Write the nonce, terms and the cash it can cost to durable storage **before** you sign. A reply that times out can still mean a live quote, and only the chain settles it.

**Throws:**

| Condition | Message |
| --- | --- |
| `intent.auctionId !== snapshot.id` | `maker-sdk: intent belongs to another auction` |
| `nonce` is not a bigint in `[0, 2^64 - 2]` | `maker-sdk: nonce must be a u64 below 2^64-1 (that value is reserved)` |
| `validUntil` not a positive safe integer, or after `intent.expiry` | `maker-sdk: validUntil must be unix seconds no later than the option expiry` |


If the award's intent is not the one you stored, decline it at once. Throwing or staying silent holds the award until the hard deadline, and the customer gets no quote.

```ts
import {
  buildQuote,
  REVIEW_SECONDS,
  type Award,
  type BidIntent,
  type GatewayClient,
  type RfqSnapshot,
} from '@covrfun/maker-sdk';

declare const client: GatewayClient;
declare const snapshot: RfqSnapshot;
declare const myIntent: BidIntent; // the intent you signed and stored for award.id
declare function reserveNonceDurably(): Promise<bigint>; // your journal: fsync before signing

async function onAward(award: Award) {
  if (JSON.stringify(myIntent) !== JSON.stringify(award.intent)) {
    await client.sendAwardDecline(award.id, award.intent.signature); // pass it on now
    return;
  }
  const nonce = await reserveNonceDurably();
  const now = Math.floor(Date.now() / 1000);
  const unsignedQuote = buildQuote(snapshot, myIntent, {
    nonce,
    validUntil: Math.min(snapshot.request.expiry, now + REVIEW_SECONDS - 5),
  });
  // Sign with signQuote, then client.sendQuote(myIntent.signature, quote).
}
```

## signIntent

Signs a bid intent with your quote key in the market's domain. Returns the exact 18-field object to send as `bid_intent` params.

```ts
export declare function signIntent(signer: TypedDataSigner, domain: TypedDataDomain, intent: UnsignedBidIntent): Promise<BidIntent>;
```

| Name | Type | Description |
| --- | --- | --- |
| `signer` | [`TypedDataSigner`](https://docs.covr.markets/reference/sdk/signing.md#typeddatasigner) | Your quote key. |
| `domain` | `TypedDataDomain` | [`quoteDomain`](https://docs.covr.markets/reference/sdk/markets.md#quotedomain) of the RFQ's market. |
| `intent` | [`UnsignedBidIntent`](https://docs.covr.markets/reference/sdk/types.md#unsignedbidintent) | From [`buildBidIntent`](#buildbidintent). Exactly the 17 unsigned fields (a `signature` key is ignored). |

**Returns:** [`BidIntent`](https://docs.covr.markets/reference/sdk/types.md#bidintent): the 17 fields in canonical order plus `signature` (lowercase 0x-hex, 65 bytes).

**Throws:**

| Condition | Message |
| --- | --- |
| `intent` is not an object | `maker-sdk: intent object required` |
| Any field missing or extra | `maker-sdk: intent must have exactly the 17 unsigned bid intent fields` |
| `auctionId` is not a lowercase UUID v4 | `Invalid auction ID` |
| `market`, `wallet` or `position` is not a valid Solana key | `SolanaError` from `@solana/kit` |
| An `address` or `uint` field is malformed | an `ethers` encoding error |
| Signature malformed or high-s | see [`assertCanonicalSignature`](https://docs.covr.markets/reference/sdk/signing.md#assertcanonicalsignature) |
| Signature recovers to another key | `maker-sdk: signature recovers to <recovered>, not the maker <maker>` |


```ts
import { quoteDomain, signIntent, type DecodedMarketV3, type TypedDataSigner, type UnsignedBidIntent } from '@covrfun/maker-sdk';

declare const signer: TypedDataSigner;
declare const market: DecodedMarketV3;
declare const unsigned: UnsignedBidIntent; // from buildBidIntent

const intent = await signIntent(signer, quoteDomain(market), unsigned);
// Store `intent` by RFQ id before sending it: you answer the award from this copy.
```

## signQuote

Signs an executable quote in the market's domain. Returns the exact 16-field object to send as the `quote` param.

```ts
export declare function signQuote(signer: TypedDataSigner, domain: TypedDataDomain, quote: UnsignedQuoteV2): Promise<QuoteV2>;
```

| Name | Type | Description |
| --- | --- | --- |
| `signer` | [`TypedDataSigner`](https://docs.covr.markets/reference/sdk/signing.md#typeddatasigner) | Your quote key. |
| `domain` | `TypedDataDomain` | [`quoteDomain`](https://docs.covr.markets/reference/sdk/markets.md#quotedomain) of the RFQ's market. The program verifies the signature in the same domain at fill. |
| `quote` | [`UnsignedQuoteV2`](https://docs.covr.markets/reference/sdk/types.md#unsignedquotev2) | From [`buildQuote`](#buildquote). Exactly the 15 fields. |

**Returns:** [`QuoteV2`](https://docs.covr.markets/reference/sdk/types.md#quotev2): the 15 fields plus `signature` (lowercase 0x-hex).

**Throws:**

| Condition | Message |
| --- | --- |
| `quote` is not an object | `quote object required` |
| Fields missing or extra | `Unsupported quote schema` |
| `auctionId` or `writer` missing | `maker-sdk: QuoteV2 (with auctionId and writer) required` |
| `auctionId` is not a lowercase UUID v4 | `Invalid auction ID` |
| `writer` is not a valid Solana key | `SolanaError` from `@solana/kit` |
| Signature malformed or high-s | see [`assertCanonicalSignature`](https://docs.covr.markets/reference/sdk/signing.md#assertcanonicalsignature) |
| Signature recovers to another key | `maker-sdk: signature recovers to <recovered>, not the maker <maker>` |


```ts
import { signQuote, quoteDomain, type DecodedMarketV3, type TypedDataSigner, type UnsignedQuoteV2 } from '@covrfun/maker-sdk';

declare const signer: TypedDataSigner;
declare const market: DecodedMarketV3;
declare const unsignedQuote: UnsignedQuoteV2; // from buildQuote, journaled first

const quote = await signQuote(signer, quoteDomain(market), unsignedQuote);
```

## signWithdrawal

Signs the body of a quote withdrawal: `WithdrawBid(rfqId, keccak256(quote signature))`.

```ts
export declare function signWithdrawal(signer: TypedDataSigner, domain: TypedDataDomain, quote: Pick<QuoteV2, 'auctionId' | 'maker' | 'signature'>): Promise<{
    quoteSignature: string;
    signature: string;
}>;
```

> [!WARNING]
> Desks cannot use this today. The gateway serves the withdrawal route only to covr's own maker, not on the desk listener. A withdrawal would never cancel a quote on chain anyway. For an immediate, reversible stop, pause your mint policy ([Cancel quotes](https://docs.covr.markets/guides/cancel-quotes.md)). To cancel signed quotes for good, raise `min_nonce` with [`configureMaker`](https://docs.covr.markets/reference/sdk/setup.md#configuremaker).

| Name | Type | Description |
| --- | --- | --- |
| `signer` | [`TypedDataSigner`](https://docs.covr.markets/reference/sdk/signing.md#typeddatasigner) | The quote's maker key. |
| `domain` | `TypedDataDomain` | The quote's market domain. |
| `quote` | `Pick<QuoteV2, 'auctionId' \| 'maker' \| 'signature'>` | The signed quote to withdraw. |

**Returns:** `{ quoteSignature, signature }`: the quote's signature and the withdrawal signature (lowercase).

**Throws:**

| Condition | Message |
| --- | --- |
| `quote` is not an object or `auctionId` is not a lowercase UUID v4 | `maker-sdk: invalid auction id` |
| `quote.signature` malformed or high-s | see [`assertCanonicalSignature`](https://docs.covr.markets/reference/sdk/signing.md#assertcanonicalsignature) |
| The new signature recovers to another key than `quote.maker` | `maker-sdk: signature recovers to <recovered>, not the maker <maker>` |


```ts
import { signWithdrawal, type QuoteV2, type TypedDataSigner } from '@covrfun/maker-sdk';
import type { TypedDataDomain } from 'ethers';

declare const signer: TypedDataSigner;
declare const domain: TypedDataDomain;
declare const quote: QuoteV2;
const body = await signWithdrawal(signer, domain, quote);
```

---

Source: https://docs.covr.markets/reference/sdk/quoting · Part of covr Docs, https://docs.covr.markets/llms.txt
