covr.Docs

SDK reference

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 and decode its market (decodeMarketV3).
  2. Within 3 s of the RFQ (COLLECT_MS), send one bid intent: buildBidIntent, signIntent, client.sendBidIntent. 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).
  4. The winner answers with a quote: buildQuote, signQuote, client.sendQuote, or passes with client.sendAwardDecline.
  5. The customer's wallet signs and submits the fill. You see it only on chain, as your position PDA (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 for the full protocol.

Units used on this page

FieldUnit
priceGross 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.
quantityCollateral atoms scaled to 18 decimals (quantityE18), decimal string. For JitoSOL (9 decimals), 1 atom is 1000000000. Convert with atomsFromWire.
strikeStrike in USD × 10^8 (strikeE8), decimal string. 17000000000 is $170.
expiry, validUntilUnix seconds, integer number.
nonceu64 as a decimal string.
closesAt, hardDeadline, awardUntilEpoch 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.

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 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. 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, 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;
NameTypeDescription
idstringRFQ 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;
NameTypeDescription
snapshot.hardDeadlinenumberAuction hard deadline, epoch ms.
snapshot.request.expirynumberOption expiry, unix seconds.

Returns: number, unix seconds. It always lies after the collection window closes, which buildBidIntent requires.

Throws: nothing. A missing hardDeadline yields NaN, which 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;
NameTypeDescription
snapshotRfqSnapshotFrom client.getRfq.
input.makerstringYour quote key address (0x…). The gateway requires it to equal the key your token is registered to.
input.pricebigint | stringGross premium per one whole collateral token, USDC × 10^18. Positive, below 2^128. A string must be a canonical decimal integer.
input.validUntilnumberIntent expiry, unix seconds. Must be after ceil(closesAt / 1000) and at most request.expiry.

Returns: 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:

ConditionMessage
snapshot.kind is not open, or position is not nullmaker-sdk: only open (opening) auctions take bid intents
snapshot.id is not a lowercase UUID v4maker-sdk: invalid auction id
market or wallet is not a stringmaker-sdk: snapshot must carry market and wallet
price is a string that is not a canonical decimal integercanonical unsigned integer required
price is a string of 2^128 or moreinteger overflow
price is zero, negative, or a bigint of 2^128 or moremaker-sdk: price must be a positive u128 priceE18 (USDC per whole token, 18 decimals)
validUntil is not a safe integermaker-sdk: validUntil must be integer unix seconds
validUntil <= ceil(closesAt / 1000)maker-sdk: validUntil must be after the collection window closes
validUntil > request.expirymaker-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;
NameTypeDescription
snapshot.idstringThe RFQ id. Must equal intent.auctionId.
snapshot.walletstringThe writer (customer) wallet. Becomes writer.
intentBidIntentYour own stored copy of the intent you signed, never the copy inside the award.
input.noncebigintA fresh nonce: 0 to 2^64 - 2, at least your on-chain min_nonce, never used before.
input.validUntilnumberQuote expiry, unix seconds, positive, at most the option expiry.

Returns: 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:

ConditionMessage
intent.auctionId !== snapshot.idmaker-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.expirymaker-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>;
NameTypeDescription
signerTypedDataSignerYour quote key.
domainTypedDataDomainquoteDomain of the RFQ's market.
intentUnsignedBidIntentFrom buildBidIntent. Exactly the 17 unsigned fields (a signature key is ignored).

Returns: BidIntent: the 17 fields in canonical order plus signature (lowercase 0x-hex, 65 bytes).

Throws:

ConditionMessage
intent is not an objectmaker-sdk: intent object required
Any field missing or extramaker-sdk: intent must have exactly the 17 unsigned bid intent fields
auctionId is not a lowercase UUID v4Invalid auction ID
market, wallet or position is not a valid Solana keySolanaError from @solana/kit
An address or uint field is malformedan ethers encoding error
Signature malformed or high-ssee assertCanonicalSignature
Signature recovers to another keymaker-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>;
NameTypeDescription
signerTypedDataSignerYour quote key.
domainTypedDataDomainquoteDomain of the RFQ's market. The program verifies the signature in the same domain at fill.
quoteUnsignedQuoteV2From buildQuote. Exactly the 15 fields.

Returns: QuoteV2: the 15 fields plus signature (lowercase 0x-hex).

Throws:

ConditionMessage
quote is not an objectquote object required
Fields missing or extraUnsupported quote schema
auctionId or writer missingmaker-sdk: QuoteV2 (with auctionId and writer) required
auctionId is not a lowercase UUID v4Invalid auction ID
writer is not a valid Solana keySolanaError from @solana/kit
Signature malformed or high-ssee assertCanonicalSignature
Signature recovers to another keymaker-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). To cancel signed quotes for good, raise min_nonce with configureMaker.

NameTypeDescription
signerTypedDataSignerThe quote's maker key.
domainTypedDataDomainThe quote's market domain.
quotePick<QuoteV2, 'auctionId' | 'maker' | 'signature'>The signed quote to withdraw.

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

Throws:

ConditionMessage
quote is not an object or auctionId is not a lowercase UUID v4maker-sdk: invalid auction id
quote.signature malformed or high-ssee assertCanonicalSignature
The new signature recovers to another key than quote.makermaker-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);